API Reference

The Partners API provides RESTful endpoints for managing merchants, MarkTag implementations, and event data. This reference documents all available endpoints.

Base URL

All API endpoints are relative to:

https://api-alpha.markopolo.ai

Available Endpoints

The Partners API consists of three main resource groups:

Merchants

Manage merchant accounts under your partner account.

• GET /v1/partners/merchant - List all merchants with their MarkTags
• GET /v1/partners/merchant/:merchantId - Get a specific merchant
• POST /v1/partners/merchant - Create a new merchant

MarkTag

Generate and verify tracking implementations.

• POST /v1/partners/marktag/generate - Generate a MarkTag for a domain
• POST /v1/partners/marktag/verify - Verify MarkTag DNS configuration

Events

Retrieve tracking data collected by MarkTag.

• GET /v1/partners/events - Get filtered event data with pagination

Request Headers

All requests require authentication:

Authorization: Bearer mp_live_YOUR_TOKEN
Content-Type: application/json

Response Format

All responses are returned in JSON format:

{
  "field": "value",
  "nested": {
    "data": "example"
  }
}

Error Response Format

All error responses follow a consistent format:

{
  "message": "Human-readable error message",
  "code": "ERROR_CODE",
  "statusCode": 400
}

Example authentication error:

{
  "message": "Authentication required",
  "code": "AUTHENTICATION_ERROR",
  "statusCode": 401
}

HTTP Status Codes

The API uses standard HTTP status codes:

Code	Description
200	Success - Request completed successfully
201	Created - Resource created successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Authentication failed
403	Forbidden - Access denied to resource
404	Not Found - Resource doesn't exist
409	Conflict - Resource already exists
422	Unprocessable Entity - DNS verification pending
500	Internal Server Error - Server error

Standardized Error Codes

The API uses these standardized error codes:

Code	HTTP Status	Description
VALIDATION_ERROR	400, 409, 422	Invalid parameters, domain already registered, or DNS pending
AUTHENTICATION_ERROR	401	Missing or invalid Bearer token
FORBIDDEN	403	Access denied to resource
NOT_FOUND	404	Resource doesn't exist
SERVICE_ERROR	500	Unable to process request

For detailed error handling information, see the Error Handling Guide.

Pagination

List endpoints support pagination using query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number (min: 1)
limit	integer	10-12	Items per page (max: 100)

Paginated responses include metadata:

{
  "data": [...],
  "pagination": {
    "currentPage": 1,
    "itemsPerPage": 10,
    "totalItems": 100,
    "totalPages": 10,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Date Formats

All dates use ISO 8601 format in UTC:

2025-01-25T10:30:00Z

When filtering by date range:

• startDate: Beginning of range (inclusive)
• endDate: End of range (inclusive)

Domain Validation

Different endpoints have different domain requirements:

Generate MarkTag

Requires root domain only:

• ✅ example.com
• ❌ https://example.com
• ❌ www.example.com
• ❌ shop.example.com

Verify MarkTag

Accepts full subdomain:

• ✅ shop.example.com
• ✅ api.shop.example.com
• ❌ https://shop.example.com

Partner Isolation

All API operations are isolated to your partner account:

• You can only access merchants you created
• Attempting to access other partners' resources returns 404
• All operations verify partner ownership

Quick Start Examples

Test Authentication

curl -X GET "https://api-alpha.markopolo.ai/v1/partners/merchant?limit=1" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

Complete MarkTag Setup

# 1. Create merchant
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": "My Store"}'

# 2. Generate MarkTag
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": "MERCHANT_ID", "domain": "example.com"}'

# 3. Verify installation
curl -X POST "https://api-alpha.markopolo.ai/v1/partners/marktag/verify" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"merchantId": "MERCHANT_ID", "subdomain": "shop.example.com"}'

# 4. Get events
curl -X GET "https://api-alpha.markopolo.ai/v1/partners/events?merchantId=MERCHANT_ID" \
  -H "Authorization: Bearer mp_live_YOUR_TOKEN"

SDK Support

While official SDKs are in development, you can use any HTTP client library:

• JavaScript: fetch, axios, node-fetch
• Python: requests, httpx, aiohttp
• PHP: Guzzle, cURL
• Ruby: Net::HTTP, HTTParty
• Go: net/http
• Java: HttpClient, OkHttp

Next Steps

Explore the detailed documentation for each endpoint:

1. Merchants API - Create and manage merchants
2. MarkTag API - Generate and verify tracking
3. Events API - Retrieve tracking data