TikTok Events API

A TikTok Events API destination sends every matching conversion to your TikTok pixel from the server. It is set up on Integrations → Conversion APIs (/app/integrations?tab=conversion-apis) and needs the Admin role.

Before you start#

• Pixel code — TikTok Ads Manager → Events → Web events → your pixel (for example C4ABCD1234).
• Events API access token — the pixel's settings → Events API → Generate access token.
• TikTok clicks should carry ttclid. TikTok appends it to the ad's landing URL; the tracker stores it from the tracking link or from the landing page in url=. You can also send it with the postback as ttclid=.

Add a destination#

1. Open Integrations → Conversion APIs.
2. On the TikTok Events API tile click Add.
3. Fill in the form:

4. Save.

Default event names#

Any other code without a line in Event names is sent as the code itself, so map custom codes explicitly:

deposit = CompletePayment
trial = Subscribe

Test it#

1. Copy a test event code from TikTok Events Manager and enter it as Test event code.
2. Choose Send test event in the destination's menu. One synthetic event (the default event name, value 1 USD) is sent with the test code; the result shows TikTok's answer. The test is refused while no test event code is set.
3. Clear the test event code to go live.

What is sent#

Each conversion becomes one POST to https://business-api.tiktok.com/open_api/v1.3/event/track/ with the header Access-Token: <token>:

{
  "event_source": "web",
  "event_source_id": "C4ABCD1234",
  "data": [{
    "event": "CompletePayment",
    "event_time": 1791624662,
    "event_id": "8a6a2d0e-3c55-4c7e-9a43-0c1c2d8f0b11",
    "user": {
      "ttclid": "E.C.P.v3Xyz…",
      "ip": "198.51.100.20",
      "user_agent": "Mozilla/5.0 …",
      "email": "<sha256>",
      "phone": "<sha256>",
      "external_id": "<sha256 of the click ID>"
    },
    "properties": { "value": 49.9, "currency": "USD", "order_id": "ORDER-1001" },
    "page": { "url": "https://shop.example.com/sale" }
  }],
  "test_event_code": "TEST12345"
}

Delivery, retries and the log#

• The worker sends conversions within seconds of approval (or creation, with Approved and pending).
• TikTok answers errors with HTTP 200 and a non-zero code; TrackCrown treats those as failures. Codes 40000–49999 are permanent; others are retried.
• 429, 5xx and network errors are retried after 1 min, 5 min, 30 min, 2 h and 6 h; other 4xx answers fail immediately.
• The postback log keeps every payload (without the token) and TikTok's response. Each destination shows Sent 7 d and Failed 7 d.

Manage a destination#

Destination menu: Edit, Send test event, Pause / Resume, Delete. These destinations are not exposed through the REST API's /postbacks endpoints.

Troubleshooting#

See also: Meta Conversions API · Ad costs & ROAS.