Server-side events · Setup reference
TikTok Events API (Official) tag template for server GTM: events, fields and dedup rules
TikTok's official server-container template 'TikTok Events API (Official)' converts GA4 events claimed by your tagging server into TikTok events and POSTs them to the Events API. It hashes email, phone and external_id, and picks up ttclid from the URL or cookie and _ttp from the cookie. TikTok's Events Manager setup flow configures an event_id variable for Pixel/Events API dedup; manual installs must add one themselves.
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/
Tag fields Pixel ID and Access Token; sent as the Access-Token header
Standard event names
Spelled exactly as Server-side GTM + TikTok expects them. A near miss is treated as a different event.
| Event | Use it for |
|---|---|
| Pageview | from GA4 page_view |
| ViewContent | from GA4 view_item |
| Search | from GA4 search |
| AddToWishlist | from GA4 add_to_wishlist |
| AddToCart | from GA4 add_to_cart |
| InitiateCheckout | from GA4 begin_checkout |
| AddPaymentInfo | from GA4 add_payment_info |
| CompletePayment | from GA4 purchase |
| CompleteRegistration | from GA4 sign_up |
Required and recommended fields
| Field | What it needs |
|---|---|
| pixel_code (Pixel ID) | tag field; sent as event_source_id |
| access_token (Access Token) | tag field; Access-Token header |
| event | GA4 event name mapped as above; unmapped names pass through unchanged, or override with the Event Name field |
| event_id | De-duplication Configurations > Event ID field, or the GA4 event's event_id parameter |
| Prerequisites | GA4, a GCP account with billing for the tagging server, web + server containers, Publish/Approve/Edit/Read permissions. The template works only in a Server container. |
Match keys and hashing
| Key | Normalise and hash |
|---|---|
| Template lowercases, trims and SHA-256 hashes unless already a 64-character hex hash. Source: tag field, or user_data.email_address / sha256_email_address. | |
| phone | Template lowercases, trims and SHA-256 hashes (no digit normalisation). Source: user_data.phone_number / sha256_phone_number. |
| external_id | Template trims and SHA-256 hashes (case preserved). Falls back to tt_external_id or user_id. |
| ip / user_agent | not hashed; from ip_override and user_agent on the event |
Click ids
| Click id | Where it comes from |
|---|---|
| ttclid | Read from ?ttclid= on page_location (or a same-host referrer), then the ttclid cookie. The template re-sets a first-party ttclid cookie for 30 days. |
| _ttp | Read from the _ttp cookie and sent as user.ttp |
Deduplication
- Send the same event and event_id through both the Pixel and the Events API; TikTok records the first event received for measurement and reporting.
- Pixel-only or Events API-only repeats with identical event + event_id are deduplicated within a 48-hour window from the first event.
- Pixel + Events API overlaps with identical event + event_id are merged or deduplicated when they arrive after 5 minutes and within a 48-hour window from the first event.
- No dedup is needed if Pixel and Events API send different events with no overlap (e.g. AddToCart via Pixel, Purchase via Events API).
- With TikTok's Events Manager GTM setup flow, 'An event_id variable is automatically configured during setup'. With manual setups, configure a custom JavaScript variable as event_id and use it in both the pixel and this tag.
Time limits and batch sizes
- The template sets event_time to the server's current time in Unix seconds when the tag runs.
- Events Manager is not real-time; allow for latency before judging volumes.
How to test before you trust it
- Test Event Code field: Template field under Test Event Configurations; sent as test_event_code. Remove it before going live.
- TikTok Events Manager > Test events tab: Live test environment; filter between browser and server test events. The Overview tab shows the Connection Method ('browser only', 'server only', 'server & browser') and dedup info under Event Details.
- GTM server container Preview: Confirm the tag fired; the template also has optional request/response logging to the console
Why events arrive but don't attribute
- Pixel and Events API not sharing event_id (common in manual installs) means CompletePayment double counts.
- GA4 'purchase' becomes CompletePayment and 'page_view' becomes 'Pageview'; custom GA4 event names are sent unchanged and will not match TikTok standard events.
- Phone numbers are only lowercased/trimmed before hashing, so format them consistently (e.g. with country code) upstream.
- If you install Events API only, TikTok says to delete the 'TikTok Pixel' and 'Custom HTML' tags from the web container; leaving half of them in place is a common mismatch.
- Test Event Code left filled after launch.
- The template only works in a Server container; it cannot be imported into a web container.
Sources
- GitHub tiktok/gtm-template-eapi (TikTok Events API (Official) template)
- TikTok Business Help Center: How to set up Events API for server-side tagging in GTM
- TikTok Business Help Center: About event deduplication
- TikTok Business Help Center: Diagnostic and monitoring tools in Events Manager
Platforms change these rules without notice. If a source says something different from this page, the source wins.