curl --request POST \
  --url https://api.upstackdata.com/tr/api/events \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-pixel-id: <api-key>' \
  --data '
{
  "events": [
    {
      "name": "purchase",
      "eventId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "identityId": "01HXYZ_BROWSER_ADTIK",
      "userProperties": {
        "emails": [
          "jane@example.com"
        ],
        "userIds": [
          "cust_889"
        ],
        "shopifyYIds": [
          "y-abc"
        ]
      },
      "ipAddress": "203.0.113.5",
      "page": {
        "url": "https://shop.com/checkout"
      },
      "click": {
        "fbc": "fb.1.abc",
        "gclid": "xyz",
        "fbclid": "IwAR…"
      },
      "viewport": {
        "viewportWidth": 1440,
        "viewportHeight": 900,
        "pageHeight": 3200,
        "devicePixelRatio": 2
      },
      "eventProperties": {
        "orderId": "10421",
        "value": 99.9,
        "currency": "USD",
        "items": [
          {
            "id": "SKU1",
            "name": "Tee",
            "price": 49.95,
            "quantity": 2
          }
        ]
      }
    }
  ]
}
'

{
  "requestId": "18d90656-34fd-4b87-b1e2-9607943d97a9",
  "eventsIngested": 3
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

EVENTS

Send events via Upstack Conversion API

Upstack Conversion API (CAPI) — send a batch of tracking events from your server. Events enter the same collect queue and consumer as browser pixel events (identity resolution, enrichment, analytics, and destination forwarding). Session handling and edge enrichment still differ from the Cloudflare pixel path.

Match quality. Send the end user’s ipAddress yourself — the API never invents it from the gateway connection. Prefer sending userAgent and locale in the body; if omitted or blank, the API fills them from the User-Agent and Accept-Language request headers when present. Extra JSON keys are accepted and passed through where they map onto the TrackingEvent envelope (e.g. nested under userProperties or click).

You always send an array of events (send one event as an array of one). Each event needs a name. An eventId is optional but strongly recommended — it makes the event idempotent (safe retries and de-duplication); everything else is optional.

Deduplication. eventId is your idempotency key. If the same eventId is received again for a pixel within the dedup window, the duplicate is skipped during processing — so retries and webhook loops are safe. Use the same eventId you send from your browser Pixel for the same event so they de-duplicate across sources (e.g. Facebook).

Limits. Up to 100 events per request; request body up to 128 KB. Curated string fields (emails, URLs, click ids, userAgent, …) have no per-field character max — the request-body size cap is the backstop. eventProperties follows the TrackingEvent data contract (TrackingEventData); known fields are typed when present, and additional keys are allowed. page.qsp remains an open object. Trait/address arrays are capped at 100 items.

Required scope: events:write.

Field naming (CAPI body → TrackingEvent envelope). userProperties → context.identity.traits; eventProperties → data; eventId → id; identityId → context.identity.identityId; top-level ipAddress / userAgent / sessionId / locale / timezone / page / campaign / click / viewport → context.properties.*.

Dual-fire with the browser Pixel. Use the same eventId (and preferably the same identityId / _adtik) for the browser and server copies of one conversion so downstream dedup and destination match quality treat them as one event.

POST

api

events

curl --request POST \
  --url https://api.upstackdata.com/tr/api/events \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-pixel-id: <api-key>' \
  --data '
{
  "events": [
    {
      "name": "purchase",
      "eventId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "identityId": "01HXYZ_BROWSER_ADTIK",
      "userProperties": {
        "emails": [
          "jane@example.com"
        ],
        "userIds": [
          "cust_889"
        ],
        "shopifyYIds": [
          "y-abc"
        ]
      },
      "ipAddress": "203.0.113.5",
      "page": {
        "url": "https://shop.com/checkout"
      },
      "click": {
        "fbc": "fb.1.abc",
        "gclid": "xyz",
        "fbclid": "IwAR…"
      },
      "viewport": {
        "viewportWidth": 1440,
        "viewportHeight": 900,
        "pageHeight": 3200,
        "devicePixelRatio": 2
      },
      "eventProperties": {
        "orderId": "10421",
        "value": 99.9,
        "currency": "USD",
        "items": [
          {
            "id": "SKU1",
            "name": "Tee",
            "price": 49.95,
            "quantity": 2
          }
        ]
      }
    }
  ]
}
'

{
  "requestId": "18d90656-34fd-4b87-b1e2-9607943d97a9",
  "eventsIngested": 3
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

Authorizations

x-api-key

string

header

required

Your Upstack API key. Starts with upstack_.

x-pixel-id

string

header

required

The pixel id the request targets.

Body

application/json

events

object[]

required

The events to ingest. At least 1, at most 100 per request.

Required array length: 1 - 100 elements

Show child attributes

Response

Events accepted for processing. eventsIngested is the number queued.

requestId

string

required

Unique id for this request (also the x-request-id header).

eventsIngested

integer

required

Number of events accepted and queued for processing.

Delete a COG line

⌘I