Server-side events · Platform reference
TikTok Events API: events, fields and dedup rules
TikTok Events API 2.0 sends events from your server to an event source (for a website, your Pixel code), usually alongside the TikTok Pixel. Events tend to arrive but not attribute when the ttclid click ID or _ttp cookie isn't captured, when IP and user agent are left out (the Pixel shares them by default, the Events API doesn't), or when event_id doesn't match the Pixel so the two copies don't deduplicate.
Read from the official documentation on 9 November 2026. Sources are listed at the end.
Endpoint and authentication
POST https://business-api.tiktok.com/open_api/v1.3/event/track/
Access token for Events API 2.0, generated in TikTok Events Manager (Settings > Generate Access Token)
Standard event names
Spelled exactly as TikTok expects them. A near miss is treated as a different event.
| Event | Use it for |
|---|---|
| Purchase | renamed from CompletePayment; the legacy name still works and is supported indefinitely, but reports show Purchase. Send value + currency |
| Lead | renamed from SubmitForm; the legacy name is supported indefinitely |
| CompleteRegistration | sign-up completed |
| InitiateCheckout | checkout started |
| AddToCart | recommended params: content_type, quantity, description, content_ids, currency, value |
| AddPaymentInfo | payment details added |
| ViewContent | recommended params as AddToCart |
| Subscribe | subscription |
| StartTrial | new event; recommended params content_ids, currency, value |
| SubmitApplication | new event: application submitted |
| ApplicationApproval | new event: application finally confirmed |
| Contact | contact made |
| Schedule | appointment booked |
| Search | recommended param search_string |
| Download | download |
| AddToWishlist | wishlist add |
| PlaceAnOrder | soft-deprecated: still fully supported, sunset in 2027; historical data can't move to a new event |
| ClickButton | soft-deprecated: still fully supported, sunset in 2027 |
Required and recommended fields
| Field | What it needs |
|---|---|
| event_source | Which kind of event source. For a website Pixel it is "web" (TikTok's own server GTM template sends event_source: "web" with the Pixel code as event_source_id) |
| event_source_id | For web, the Pixel code; for offline, the offline event set ID; for app, the TikTok App ID |
| event | Standard or custom event name |
| event_time | Time the event happened |
| event_id | Must be shared through both Pixel and Events API, with the identical event name, for deduplication |
| user (email, phone, external_id, ttclid, ttp, ip, user_agent) | Match keys; IP and user agent need manual configuration for the Events API |
| properties.value + properties.currency | Recommended for Purchase, AddToCart, ViewContent and StartTrial |
Match keys and hashing
| Key | Normalise and hash |
|---|---|
| Hashing required (SHA-256 per partner integration docs) | |
| phone | Hashing required (SHA-256) |
| external_id | Hashing required (SHA-256). Advertiser IDs such as loyalty IDs, customer IDs or your own cookie IDs |
| ip | Not hashed. The Pixel shares it by default; the Events API needs it configured manually |
| user_agent | Not hashed. The Pixel shares it by default; the Events API needs it configured manually |
| ttp | First-party _ttp cookie value, limited to the advertiser's domain; send the cookie value as read |
| ttclid | Not hashed |
Click ids
| Click id | Where it comes from |
|---|---|
| ttclid | TikTok Click ID appended to the landing page URL when someone clicks a TikTok ad. The Pixel also keeps it as a first-party cookie named ttclid. Each Click ID follows the CTA window set in Attribution Manager |
| _ttp | First-party cookie the Pixel sets on your domain (on by default, can be turned off in pixel settings); used to match website visitors to TikTok ads. Cookies expire 13 months after they were set or last used |
Deduplication
- Send the same event_id through both the Pixel and the Events API; events with an identical event and event_id are treated as duplicates.
- TikTok keeps the first event it receives for measurement and reporting.
- Pixel-only duplicates, and Events API-only duplicates, are deduplicated within 48 hours of the first event.
- Pixel and Events API copies with the identical event and event_id are merged or deduplicated when they arrive "after 5 minutes and within a 48-hour window from the first event" (TikTok's help article wording). Send the same event_id on both whatever the timing.
- Deduplication only matters when the same events go through both Pixel and Events API. If each channel sends different events, there is nothing to deduplicate.
Time limits and batch sizes
- Events Manager shows 'No recent activity' when an event hasn't been shared with TikTok in the last 7 days.
- Event data in Events Manager is not shown in real time.
- Click IDs follow the CTA (click-through) attribution window set in Attribution Manager; conversions outside that window aren't credited to the click.
How to test before you trust it
- Test Events tab (Events Manager): Copy the test_event_code from the Pixel's Test Events tab and send it as test_event_code in the request body (TikTok's server GTM template sets it at the top level). Remove it for live traffic.
- Diagnostics tab: Lists event quality issues with severity, affected dataset and impacted ads, plus fix instructions and sample affected events.
- Event Match Quality score: A weighted average of your match-key coverage, shown in Events Manager.
Why events arrive but don't attribute
- IP address and user agent missing from server events. The Pixel shares them automatically but the Events API needs them configured manually, so server-only events match far less often.
- ttclid not captured: a redirect or form step drops the ?ttclid= parameter, or first-party cookies are turned off in the pixel settings so the ttclid/_ttp cookies are never written.
- Pixel and server send different event_id values (or different event names), so both copies are counted. Matching only works on the identical event and event_id pair, within 48 hours of the first event.
- Email, phone or external_id sent in plain text. TikTok's help centre marks all three as 'hashing required'.
- Optimising on a renamed or deprecated event. CompletePayment and SubmitForm now report as Purchase and Lead, while PlaceAnOrder and ClickButton sunset in 2027 and their history can't be moved to a new event.
- test_event_code left in production. Test events are kept out of production data, so real conversions vanish from reporting.
- Conversion happens after the CTA window set in Attribution Manager, so the click ID no longer earns credit.
Sources
- TikTok Business Help: About event deduplication
- TikTok Business Help: Standard events and parameters
- TikTok Business Help: Monitor and diagnose events in Events Manager
- TikTok Business Help: How to adopt TikTok's updated standard events
- TikTok Business Help: How to set up matching events with Events API
- TikTok Business Help: Use cookies with TikTok Pixel / About TikTok Click ID
- TikTok's official Events API template for server GTM (template.tpl: endpoint, event_source, test_event_code)
Platforms change these rules without notice. If a source says something different from this page, the source wins.