Markopolo Documentation

Appearance

Ecommerce Platform Integration Guide ​

Bring powerful analytics to your merchants in just 2 minutes. This guide shows ecommerce platforms how to integrate MarkTag tracking for comprehensive merchant analytics.

Quick Start (2 Minutes) ​

Step 1: Get Your API Token ​

Contact partners@markopolo.ai to get your Partners API token (mp_live_*). See Authentication for more details.

Step 2: Create Merchant Account ​

Use the Merchants API to create a merchant account:

bash
curl -X POST "https://api-alpha.markopolo.ai/v1/partners/merchant" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Merchant Store Name"
  }'

Step 3: Generate Client-Side MarkTag ​

Use the MarkTag API to generate a tracking tag:

bash
curl -X POST "https://api-alpha.markopolo.ai/v1/partners/marktag/generate" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "YOUR_MERCHANT_ID",
    "type": "client-side"
  }'

Response:

json
{
  "tagId": "client-ABC123",
  "status": "active",
  "type": "client-side"
}

Step 4: Add Tracking to Your Platform ​

Add this code to your platform's checkout and product pages. Replace client-ABC123 with the tagId from Step 3:

html
<script>
  window.mtrem = window.mtrem || [];
  function mtag() {
    mtrem.push(arguments);
  }
  mtag("init", "https://mtag.markopolo.ai?tagId=client-ABC123", {
    consent: true,
  });
</script>
<script async src="https://mtag.markopolo.ai/script"></script>

Note: You can add this script however works best for your platform - directly in HTML templates, via React components, or dynamically with JavaScript. The important part is that it loads on every page.

That's it! Analytics are now active. No DNS setup, no waiting.

Essential Ecommerce Events ​

The marktag script exposes a function mtag("event", <event-name>, <event-payload>) that can be used to fire events. The payload that you pass is wrapped with some additional metadata and passed to the server. To get started track these 5 critical events for complete ecommerce analytics:

1. Purchase Event (Most Important) ​

javascript
mtag("event", "Purchase", {
  email: customer.email,
  phone: customer.phone,
  value: 99.99,
  currency: "USD",
  products: [
    {
      id: "SKU-123",
      name: "Product Name",
      category: "Category",
      price: 99.99,
      quantity: 1,
    },
  ],
});

2. Add to Cart ​

javascript
mtag("event", "AddToCart", {
  value: 49.99,
  currency: "USD",
  products: [
    {
      id: "SKU-456",
      name: "Product Name",
      price: 49.99,
      quantity: 1,
    },
  ],
});

3. Begin Checkout ​

javascript
mtag("event", "BeginCheckout", {
  value: 149.99,
  currency: "USD",
  products: cartItems, // Array of product objects
});

See Web SDK Usage Guide for detailed product object structure and Events API for querying this data.

4. View Content (Product Page) ​

javascript
mtag("event", "ViewContent", {
  value: 29.99,
  currency: "USD",
  content_type: "product",
  products: [
    {
      id: "SKU-789",
      name: "Product Name",
      category: "Category",
      price: 29.99,
    },
  ],
});

5. Search ​

javascript
mtag("event", "Search", {
  search_query: "user search term",
});

Implementation Best Practices ​

Store the merchant ID in your database to maintain proper merchant-to-store mapping. This ensures you can track analytics for each merchant separately and retrieve their data correctly.

Querying Events ​

After implementing tracking, use the Events API to retrieve your merchants' analytics data:

Get Recent Events ​

bash
curl -X GET "https://api-alpha.markopolo.ai/v1/partners/events?merchantId=YOUR_MERCHANT_ID&limit=100" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

Filter by Event Type ​

bash
curl -X GET "https://api-alpha.markopolo.ai/v1/partners/events?merchantId=YOUR_MERCHANT_ID&eventName=Purchase" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

Get Events Within Date Range ​

bash
curl -X GET "https://api-alpha.markopolo.ai/v1/partners/events?merchantId=YOUR_MERCHANT_ID&startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

Example Response ​

json
{
  "events": [
    {
      "eventId": "evt_123",
      "eventName": "Purchase",
      "timestamp": "2024-01-15T14:30:00Z",
      "properties": {
        "value": 99.99,
        "currency": "USD",
        "products": [
          {
            "id": "SKU-123",
            "name": "Product Name",
            "price": 99.99,
            "quantity": 1
          }
        ]
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 487
  }
}

Analytics Dashboard ​

You can build analytics dashboards for your merchants using the Events API. Display metrics like:

  • Real-time event stream
  • Conversion tracking
  • Revenue reports
  • Customer journey analysis

Merchants will view these analytics on whatever dashboard pages you build for them using the data from the API above.

Testing Your Integration ​

1. Verify Tag is Loading ​

Open browser console and check:

javascript
// Should return true if loaded
typeof mtag === "function";

2. Test Purchase Event ​

javascript
// Test purchase event
mtag("event", "Purchase", {
  value: 10.0,
  currency: "USD",
  products: [
    { id: "TEST-001", name: "Test Product", price: 10.0, quantity: 1 },
  ],
});

3. Check Events via API ​

bash
curl -X GET "https://api-alpha.markopolo.ai/v1/partners/events?merchantId=YOUR_MERCHANT_ID&limit=5" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

Get Started Today ​

  1. Email partners@markopolo.ai for your API token
  2. Implement tracking in 2 minutes
  3. Start seeing analytics immediately

Note: While this guide focuses on client-side tracking for instant setup, MarkTag also supports server-side tracking (using merchant's domain) and preverified tracking (using your platform's domain) for advanced use cases. These require additional setup but offer benefits like custom domains and first-party tracking.

Quick Reference Checklist ​

✅ Setup (One-time) ​

  • [ ] Get Partners API token from partners@markopolo.ai
  • [ ] Create merchant accounts for your stores
  • [ ] Generate client-side MarkTag for each merchant
  • [ ] Add tracking script to your platform

✅ Essential Events ​

  • [ ] Purchase - Track completed orders with products and value
  • [ ] AddToCart - Track when items are added to cart
  • [ ] BeginCheckout - Track when checkout process starts
  • [ ] ViewContent - Track product page views
  • [ ] Search - Track search queries

✅ Implementation ​

  • [ ] Initialize MarkTag on all pages
  • [ ] Track Purchase events on order confirmation
  • [ ] Track AddToCart on cart additions
  • [ ] Track ViewContent on product pages
  • [ ] Test events in browser console

✅ Verification ​

  • [ ] Query events via API to confirm tracking
  • [ ] Verify purchase events include products array
  • [ ] Check that all events have proper currency codes
  • [ ] Confirm customer email/phone in purchase events

Copyright © 2026 Markopolo AI