TikTok Events API migration: Unified Endpoint Guide

The Name Untangled: 2.0 Is the Product, v1.3 Is the Version

The TikTok Events API migration conversation stumbles on naming before it reaches code - and on the phrase itself. "Events API 2.0" is TikTok's name for the unified endpoint - /event/track/ - that reports events from all sources: web, app, offline, and CRM. The v1.3 in documentation URLs and endpoint paths is a different axis entirely: the Marketing API version that the path carries. TikTok's own overview page lives at a URL containing both, and its curl example posts to https://business-api.tiktok.com/open_api/v1.3/event/track/ - a 2.0 endpoint whose path contains v1.3. Reading "2.0" and "v1.3" as competing versions is the fastest way to confuse a migration plan; one is the product generation, the other is the API version string.

For an affiliate funnel, target the documented unified endpoint and check the Marketing API version in its path. Do not infer a future endpoint path from the product's generation number.

Interpret the Historical Endpoint List

The overview names six 1.0 routes: /pixel/track/, /pixel/batch/, /offline/track/, /offline/batch/, /app/track/, and /app/batch/. Its statement about H2 2024 must be read as a dated migration notice. Plan around the recommended unified endpoint without using that wording alone to infer the present status of an old route.

The events API route supports different sources through event_source, but the remaining fields and requirements are source-specific. A postback is not automatically an offline event. Classify the actual action, then check its specification and integration errors.

Check the Envelope and Source Specification

event_source accepts web, app, offline, or crm. event_source_id identifies the source, and data contains events. Check the source-specific specification for required and recommended event fields rather than treating the overview example as a universal schema.

The overview's example uses user.email, user.phone, user.ip, and user.user_agent, showing hashed email and phone alongside raw IP and user agent. Exact normalization and hashing requirements belong to the field specification; see CAPI user data hashing for the broader concept without copying Meta's field names.

For web delivery through Pixel and API, check event identity and the documented deduplication conditions. event_id alone does not prove matching or attribution. The Meta pixel and CAPI deduplication guide describes a separate platform contract. Verify source-specific objects, value and currency rules, and privacy fields directly in the relevant TikTok specification before including them.

Endpoint, Authentication, and Request Rate

The endpoint is https://business-api.tiktok.com/open_api/v1.3/event/track/, with an Access-Token header. A token can come from Events Manager or a developer app. See the pixel ID and access token guide.

The overview states 1,000 QPS per advertiser account for an Events Manager token, or per developer app for that app's token. It recommends sending one event at a time as soon as received. Do not derive a maximum events-per-request count from the QPS limit; verify any batching design against its current specification.

A minimal web-event request combines the top-level fields with one event:

{
  "event_source": "web",
  "event_source_id": "<pixel-code>",
  "data": [
    {
      "event": "Purchase",
      "event_time": 1769000000,
      "event_id": "Purchase_1769000000_a1b2c3d4",
      "user": { "ip": "<visitor-ip>", "user_agent": "<visitor-ua>" },
      "properties": { "value": 12.5, "currency": "USD" }
    }
  ]
}

This shape follows the documented request structure; the values are placeholders. page.url is omitted because a website is not part of the request itself, and event_time is Unix seconds. A receipt answer looks like {"code": 0, "message": "OK", "request_id": "..."}.

HTTP 200 together with body code: 0 indicates successful API receipt. Inspect the response body as well as the HTTP status. Receipt does not establish matching, deduplication, attribution, or campaign reporting.

Migration Steps for an Existing Funnel

Inventory each old integration before directing it to /event/track/. Choose the documented event_source value for the real action, preserve the intended event_source_id, and build data using that source's required and recommended fields. Do not classify a tracker postback as offline merely because it comes from a server.

TikTok allows standalone Events API setup or pairing with Pixel. For websites it recommends Pixel plus API as two channels; that is not a universal Pixel requirement for app, offline, or CRM sources. When sending two copies of a web action, preserve event identity and apply TikTok's deduplication contract.

Send a controlled test and inspect both the HTTP response and code: 0, then check the intended source's diagnostics. Verify production receipt, matching, deduplication, and reporting separately before treating migration as complete. Related workflows are TikTok delivery and Events API Gateway.

Sources