Partners API Overview

The Markopolo Partners API enables platforms to integrate MarkTag tracking capabilities into their own systems. This API is designed for partners who want to offer MarkTag analytics as part of their platform's features.

Looking for a quick start? This is a comprehensive overview of the Partners API architecture and concepts. If you want to start integrating immediately, jump to the Quick Start Guide.

What is the Partners API?

The Partners API allows third-party platforms to:

• Manage Merchants: Create and manage merchant accounts under your partner umbrella
• Generate MarkTags: Create tracking implementations for merchant websites
• Verify Installations: Validate that MarkTag is properly installed on merchant domains
• Access Event Data: Retrieve tracking events and analytics data collected by MarkTag

Who Should Use This API?

The Partners API is designed for:

E-commerce Platforms

Integrate MarkTag tracking directly into your e-commerce platform, allowing merchants to automatically set up analytics without leaving your dashboard.

Website Builders

Offer MarkTag as a built-in analytics solution for websites created on your platform.

Key Concepts

Partner Account

Your organization's account that can create and manage multiple merchant accounts. Each partner has a unique API token for authentication.

Merchant

A business or website owner who uses MarkTag for tracking. Merchants are created and managed under your partner account.

MarkTag

The tracking implementation that collects event data from a merchant's website. Each merchant can have multiple MarkTags for different domains.

Events

User interactions and behaviors tracked by MarkTag, such as page views, purchases, and custom events.

API Architecture

Base URL

https://api-alpha.markopolo.ai

API Version

Current version: v1

All endpoints are prefixed with /v1/partners/

Request/Response Format

• Content-Type: application/json
• Authentication: Bearer token in Authorization header
• Response Format: JSON

Core Functionality

1. Merchant Management

Create and manage merchant accounts under your partner account. Each merchant represents a business that will use MarkTag tracking.

2. MarkTag Generation

Generate tracking implementations with three flexible options:

• Client-side: JavaScript-based tracking, no DNS required
• Server-side: DNS-based tracking on custom domains
• Preverified: DNS-based tracking on your partner domain

The API provides unique tag IDs and DNS configuration instructions when needed.

3. Installation Verification

Verify that merchants have correctly configured their DNS and that MarkTag is ready to collect data.

4. Event Data Access

Retrieve tracking events collected by MarkTag with filtering and pagination options.

Integration Workflows

Client-Side MarkTag Workflow (Immediate)

1. Create Merchant - Register a new merchant under your partner account
2. Generate MarkTag - Create client-side tracking (no domain needed)
3. Add Tracking Code - Merchant adds JavaScript to their website
4. Start Tracking - Events begin flowing immediately
5. Retrieve Data - Access event data through the API

Server-Side MarkTag Workflow (Custom Domain)

1. Create Merchant - Register a new merchant under your partner account
2. Generate MarkTag - Create tracking for merchant's custom domain
3. Configure DNS - Merchant adds CNAME record to their domain
4. Wait for Propagation - DNS changes propagate (5-30 minutes)
5. Verify Installation - Validate the DNS configuration
6. Add Tracking Code - Merchant adds code to their website
7. Collect Events - MarkTag begins tracking user interactions
8. Retrieve Data - Access event data through the API

Preverified MarkTag Workflow (Requires Prior Setup)

Prerequisites: Must have completed preverified setup with Markopolo

1. Create Merchant - Register a new merchant under your partner account
2. Generate MarkTag - Create tracking using your pre-configured domain
3. Add Tracking Code - Add code to merchant's website/platform
4. Start Tracking - Events begin flowing immediately
5. Retrieve Data - Access event data through the API

Choosing Your MarkTag Type

The Partners API offers three marktag types, each designed for different scenarios. Understanding which type to use is crucial for a smooth integration.

Quick Decision Guide

• Want to start tracking immediately? → Use Client-Side MarkTag
• Need tracking on merchant's own domain? → Use Server-Side MarkTag
• Managing many merchants on your platform? → Use Preverified MarkTag

MarkTag Types Comparison

Feature	Client-Side	Server-Side	Preverified
Setup Time	Instant	5-30 minutes (DNS)	Instant
DNS Required	Never	Yes (merchant's)	No (uses yours)
Domain Used	mtag.markopolo.ai	Merchant's custom	Your partner domain
Who Configures DNS	Nobody	Merchant	You (once, during onboarding)
Verification Needed	No	Yes	No
Best For	Quick start, testing	Enterprise, custom domains	Platform merchants

Detailed MarkTag Type Guide

Client-Side MarkTag (Fastest Setup)

How it works:

• JavaScript-based tracking using Markopolo's domain (mtag.markopolo.ai)
• No DNS configuration ever required
• Works immediately after generation

Perfect for:

• Immediate needs - Start tracking in seconds
• Testing & development - No infrastructure setup
• Small merchants - Those without technical DNS access
• Quick proof of concept - Demonstrate value before DNS setup

Limitations:

• Uses Markopolo's domain (not white-labeled)
• Some ad blockers may block third-party domains

Server-Side MarkTag (Custom Domain Control)

How it works:

• Tracking runs on merchant's own domain (e.g., mtag.merchantsite.com)
• Merchant must add CNAME record to their DNS
• Requires verification after DNS propagation
• Takes 5-30 minutes for DNS to propagate

Perfect for:

• Enterprise merchants - Want full control over their domain
• Privacy-conscious brands - First-party domain tracking
• Custom requirements - Specific subdomain needs
• Ad blocker resilience - First-party domains less likely blocked

Requirements:

• Merchant must have DNS access
• Technical knowledge to configure CNAME records
• Time for DNS propagation and verification

Preverified MarkTag (Seamless Platform Integration)

How it works:

• Uses your partner domain (e.g., mtag.yourplatform.com)
• You configure DNS once during partner onboarding
• All merchant marktags under your domain work instantly
• No merchant DNS configuration ever needed

Perfect for:

• Platform-hosted merchants - Stores on your platform
• White-label solutions - Branded under your domain
• Bulk merchant onboarding - Onboard many merchants quickly
• Non-technical merchants - No DNS knowledge required

Prerequisites:

• Must request preverified access from partners@markopolo.ai
• Receive CNAME record from Markopolo
• Configure CNAME on your domain
• Wait for Markopolo to verify setup
• Only then can you use preverified marktags

Note: This is an optional feature. Most partners start with client-side marktags which work immediately without any setup.

Which Type Should You Choose?

Choose Client-Side If:

• You need to start tracking immediately
• Merchants can't or won't configure DNS
• You're testing or developing the integration
• Time to market is critical

Choose Server-Side If:

• Merchants want their own domain for tracking
• Enterprise clients require domain control
• Ad blocker circumvention is important
• Merchants have technical DNS capabilities

Choose Preverified If:

• You're a platform hosting many merchants
• You want seamless, instant activation
• Merchants are non-technical
• You want white-label tracking under your brand

Can I Use Multiple Types?

Yes! Each merchant can have one marktag of each type:

• Start with client-side for immediate tracking (always available)
• Add server-side later when merchant configures their domain (always available)
• Use preverified for platform-integrated features (requires prior setup)

This allows progressive enhancement based on merchant needs and capabilities.

Important: Client-side and server-side marktags are available to all partners immediately. Preverified marktags require a separate setup process with Markopolo.

Security & Authentication

API Tokens

• Tokens start with mp_live prefix
• Each partner has a unique token
• Tokens must be kept secure and never exposed in client-side code

Partner Isolation

• Each partner can only access their own merchants
• Merchant data is isolated between partners
• All operations verify partner ownership

Error Handling

The API uses standardized error handling to provide consistent error responses. All errors follow a consistent JSON format with standardized error codes.

Standardized Error Codes

• VALIDATION_ERROR - Invalid request parameters (400)
• AUTHENTICATION_ERROR - Missing or invalid Bearer token (401)
• FORBIDDEN - Access denied to resource (403)
• NOT_FOUND - Resource doesn't exist (404)
• VALIDATION_ERROR - DNS verification pending (422) - specific to verify endpoint
• SERVICE_ERROR - Unable to process request (500)

For comprehensive error handling including examples and best practices, see the Error Handling Guide.

Best Practices

DNS Configuration

• After generating a MarkTag, ensure the merchant adds the CNAME record promptly
• DNS propagation can take up to 48 hours
• Always verify installation after DNS changes

Data Retrieval

• Use pagination for large datasets
• Apply filters to reduce data transfer
• Cache frequently accessed data when appropriate

Error Handling

• Implement retry logic for temporary failures
• Log errors for debugging
• Provide clear feedback to merchants about installation status

Getting Started

Partner Onboarding

To begin using the Partners API:

1. Contact Our Team - Email partners@markopolo.ai to start the onboarding process
2. Business Discussion - We'll learn about:
   • Your platform and business model
   • Integration requirements and use cases
   • Expected merchant volume
3. Receive API Token:
   • Partners API token (mp_live)
   • Integration documentation
   • Immediate access to client-side and server-side marktags
4. Start Integration - Begin creating merchants and generating marktags immediately

Optional: Enable Preverified MarkTags

If you want to use preverified marktags (not required):

1. Request Access - Contact partners@markopolo.ai
2. Receive CNAME - Get DNS record for your domain
3. Configure Domain - Add the CNAME record
4. Verification - We verify your setup
5. Access Enabled - Use preverified marktags

Support

For API support or questions, contact the Markopolo support team:

• Email: partners@markopolo.ai
• Documentation: This guide

Next Steps

1. Set up Authentication - Configure your API token
2. Quick Start Guide - Make your first API call
3. API Reference - Explore all available endpoints