Events API Payload Builder for TikTok: Parameters Checked

How to set the TikTok Events API parameters

The TikTok Events API parameters decide whether an event is accepted and whether TikTok can match it to the person who saw your ad. This builder follows TikTok's Events API 2.0 parameters and /event/track/ reference, and turns your values into a payload you can send or hand to a developer.

1. Pick the event source. web for website events, offline for store sales, crm for lead stages. Paste the matching ID from Events Manager.
2. Choose the event and time. Use a standard event where you can. The time is converted to Unix seconds in UTC.
3. Add customer details. Email, phone and IDs are normalized and hashed with SHA-256 right in your browser. For web events, add the click ID, IP address and user agent too.
4. Add value and products. A value with a supported currency lets TikTok report return on ad spend.
5. Copy the result. You get the JSON body, a curl command and, for web events, the matching Pixel call with the same event_id. Switch to batch mode to turn spreadsheet rows into requests of up to 1,000 events.

TikTok also has its own payload helper inside Events Manager, which needs a login. This builder works without one, explains each problem in plain English and handles a whole batch of rows at once.

Send and verify your Events API events

1. Create an access token. Generate it in Events Manager for your pixel or event set. Keep it on your server; never put it in website code.
2. Test first. Open your pixel in Events Manager, go to the Test Events tab, copy the code under Test Server Events and add it as test_event_code. Send the payload and watch it arrive in Event Activity.
3. Go live. Remove test_event_code and send events as they happen. TikTok recommends real time, one event at a time, rather than daily batches.
4. Check the connection. The pixel overview should show the connection method as Server, or Server & Browser when the Pixel sends the same events.

TikTok Events API errors and fixes

40002: invalid payload

The most common error. It covers broken JSON, a missing required field, a wrong type, an unhashed value in a field that must be SHA-256 hashed, or more than 1,000 events. In a batch, the message names the first bad event by its position, counting from zero: data.2.event_id is the third event.

40104: access token is empty

The Access-Token header is missing or blank. It goes in the header, not in the JSON body.

40001: no permission

The token belongs to a user who is not an admin or operator on the ad account or the pixel. Ask the account owner for access, or create the token from the right account.

40100: too many requests

TikTok allows 1,000 queries per second. Slow down and retry, or send fewer, larger requests.

Events counted twice

The Pixel and the Events API sent the same purchase with different or missing event_id values. Use one ID, such as the order number, in both.

Event time in milliseconds

A 13-digit event_time puts the event thousands of years in the future. TikTok wants seconds: divide by 1,000.