API Reference

Build custom integrations with the CreatorScore Attribution API.

Authentication

All API requests require an API key passed in the x-api-key header.

header

x-api-key: cs_live_your_api_key_here

Generate API keys at /brand/attribution/setup. Keys start with cs_live_.

Base URL

url

https://creatorscore.io/api/v1

Endpoints

POST

/track

Record a tracking event (page view, add to cart, purchase).

Headers

Header	Required	Description
x-api-key	Yes	Your API key
Content-Type	Yes	application/json

Request Body

json

{
  "event_type": "purchase",
  "pv_id": "550e8400-e29b-41d4-a716-446655440000",
  "page_url": "https://yourstore.com/thank-you",
  "product_id": "PROD_456",
  "order_id": "ORDER_123",
  "revenue": 49.99,
  "currency": "USD",
  "promo_code_used": "CREATOR20",
  "is_new_customer": true,
  "event_data": {}
}

Field Reference

Field	Type	Required	Description
event_type	string	Yes	One of: page_view, add_to_cart, checkout_start, purchase
pv_id	string (UUID)	Yes	Page view session ID (from the pixel's _cs_pv cookie)
page_url	string	No	Current page URL
product_id	string	No	Product identifier
order_id	string	No	Order/transaction ID (required for purchase events)
revenue	number	No	Order total (required for purchase events)
currency	string	No	ISO 4217 currency code (default: USD)
promo_code_used	string	No	Discount code used at checkout
is_new_customer	boolean	No	Whether this is a first-time buyer
event_data	object	No	Additional custom data (stored as JSON)

Responses

Success (200)

json

{ "ok": true }

Invalid API key (401)

json

{ "error": "Invalid API key" }

Validation error (400)

json

{ "error": "Invalid event data", "details": ["event_type is required"] }

GET

/track/pixel.js

Serve the JavaScript tracking pixel.

Parameters

Parameter	Required	Description
key	Yes	Your API key (query parameter)

Response: JavaScript file (text/javascript)

Usage

html

<script src="https://creatorscore.io/api/v1/track/pixel.js?key=YOUR_API_KEY" async></script>

The pixel automatically exposes window.CreatorScore with these methods:

Method	Description
CreatorScore.track(eventType, data)	Send a custom tracking event
CreatorScore.getPvId()	Get the current page view session ID
CreatorScore.getRef()	Get the tracking link reference code

GET

/track/click

Fallback click redirect (when Cloudflare Worker is unavailable).

Parameters

Parameter	Required	Description
code	Yes	Tracking link short code

Response: 302 redirect to destination URL

Webhook Endpoints

POST

/api/webhooks/shopify

Receive Shopify order webhooks.

Headers (sent by Shopify)

Header	Description
x-shopify-hmac-sha256	HMAC signature for verification
x-shopify-topic	Event type (orders/create or app/uninstalled)
x-shopify-shop-domain	Store domain

This endpoint is called automatically by Shopify. You don't need to call it directly.

POST

/api/webhooks/fairing

Receive Fairing post-purchase survey responses.

Headers

Header	Description
x-fairing-signature	API key for verification

Request Body

json

{
  "order_id": "123",
  "question": "How did you hear about us?",
  "answer": "jessica_styles",
  "shop_domain": "mystore.myshopify.com"
}

Rate Limits

Currently no rate limits enforced. We recommend keeping event ingestion under 100 requests/second per API key.

CORS

The /api/v1/track endpoint supports CORS from all origins, allowing browser-side tracking.

Error Codes

Status	Meaning
200	Success
400	Invalid request body or missing required fields
401	Invalid or missing API key
404	Resource not found (invalid short code, etc.)
500	Internal server error

Code Examples

cURL

bash

curl -X POST https://creatorscore.io/api/v1/track \
  -H "Content-Type: application/json" \
  -H "x-api-key: cs_live_your_key" \
  -d '{
    "event_type": "purchase",
    "pv_id": "550e8400-e29b-41d4-a716-446655440000",
    "order_id": "ORDER_123",
    "revenue": 49.99
  }'

JavaScript (fetch)

javascript

await fetch('https://creatorscore.io/api/v1/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'cs_live_your_key'
  },
  body: JSON.stringify({
    event_type: 'purchase',
    pv_id: document.cookie.match(/_cs_pv=([^;]+)/)?.[1],
    order_id: 'ORDER_123',
    revenue: 49.99
  })
})

Python

python

import requests

requests.post(
    'https://creatorscore.io/api/v1/track',
    headers={'x-api-key': 'cs_live_your_key'},
    json={
        'event_type': 'purchase',
        'pv_id': '550e8400-e29b-41d4-a716-446655440000',
        'order_id': 'ORDER_123',
        'revenue': 49.99
    }
)