{"id":10128,"date":"2026-09-20T08:31:00","date_gmt":"2026-09-20T06:31:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=10128"},"modified":"2026-09-09T13:23:04","modified_gmt":"2026-09-09T11:23:04","slug":"tutorial-implementing-the-tiktok-events-api-for-online-shops","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/digital-marketing\/tutorials-en-digital-marketing\/tutorial-implementing-the-tiktok-events-api-for-online-shops\/","title":{"rendered":"Tutorial: Implementing the TikTok Events API for Online Shops"},"content":{"rendered":"
A TikTok pixel on its own reports fewer purchases than a shop actually processes. Ad blockers, tracking protection in the browser, and visitors who close the tab before the confirmation page finishes rendering all remove events that did happen. Sending the same purchases a second time from the server closes that gap \u2014 and creates a new problem, because TikTok now receives two reports of one purchase.<\/p>\n
The mechanism that resolves it is a shared event_id<\/code>: one value generated per purchase and sent unchanged along both paths. The following walkthrough builds that architecture end to end for a shop \u2014 the browser event, the identifiers the server cannot see by itself, the server request, and the verification that deduplication is actually working.<\/p>\n\nThe pixel supplies the browser context, the server supplies the reliability – the shared event_id keeps them one conversion.<\/figcaption><\/figure>\n
Step 1: Generating the Event ID Once<\/h2>\n
The event_id<\/code> has to be generated in one place and reused, which rules out generating it independently on each side \u2014 two random values describe two separate conversions as far as TikTok is concerned. For a shop, the order identifier is the natural source: it already exists at the moment of purchase, it is stable, and it is available to both the confirmation page and the backend.<\/p>\n
A prefix keeps event types apart, since a single order can produce more than one tracked event. An event_id<\/code> of purchase-10432<\/code> for the purchase and checkout-10432<\/code> for the checkout start keeps each pair matched to its own counterpart. As a side effect, a visitor refreshing the confirmation page produces the same event_id<\/code> again and is deduplicated rather than counted twice.<\/p>\n
Step 2: The Browser Event<\/h2>\n
In the TikTok pixel, the identifier travels in the third argument of ttq.track<\/code>, separate from the event properties:<\/p>\n
The event name must match on both sides as well. TikTok pairs the two reports on the combination of event name and event_id<\/code>, so CompletePayment<\/code> in the browser and Purchase<\/code> on the server are two different events that will never deduplicate against each other, no matter how carefully the identifier is matched.<\/p>\n
Step 3: Capturing the Identifiers the Server Cannot See<\/h2>\n
Two values exist only in the browser. ttclid<\/code> arrives as a URL parameter when a visitor lands from a TikTok ad, and _ttp<\/code> is the first-party cookie the pixel sets. Both improve attribution on the server request, and both have to be persisted at landing time \u2014 the confirmation page is usually several navigations later, by which time the URL parameter is long gone:<\/p>\n
\/\/ On landing: persist the click id for the rest of the visit\nconst ttclid = new URLSearchParams(window.location.search).get('ttclid');\nif (ttclid) {\n document.cookie = 'shop_ttclid=' + encodeURIComponent(ttclid) +\n ';max-age=2592000;path=\/;secure;samesite=Lax';\n}<\/code><\/pre>\n
At checkout, both values are read out of the cookies and stored on the order record, so the backend has them when it builds the server event. The visitor’s IP address and user agent come from the original HTTP request and belong in the same record \u2014 a request sent later from a server has neither of its own.<\/p>\n
Step 4: The Server Request<\/h2>\n
The Events API takes a POST to the event\/track\/<\/code> endpoint of the TikTok Business API, authenticated with an access token from TikTok Events Manager and addressed to a pixel through event_source_id<\/code>. Identifying fields are normalised and then SHA-256 hashed; nothing identifying leaves in plain text:<\/p>\n
Normalisation before hashing decides whether the identifiers match anything: email trimmed and lowercased, phone reduced to digits in international E.164 form. The same value hashed from Anna@Example.com <\/code> and from anna@example.com<\/code> produces two unrelated digests, and only one of them can match. event_time<\/code> is a Unix timestamp in seconds, and the request belongs immediately after order confirmation rather than in a nightly batch. TikTok rejects events that arrive too late, and a batch job discovers that only once the window has already closed.<\/p>\n
Step 5: Verifying That Deduplication Works<\/h2>\n
The test_event_code<\/code> field, taken from the Test Events tab in Events Manager, routes a request into the test view without touching reporting \u2014 enough to confirm that the payload is accepted and that the hashed fields are recognised.<\/p>\n
Deduplication itself only shows up in live data. In Events Manager, an event receiving both channels reports its browser and server counts separately, and the difference between their sum and the deduplicated total is the evidence that pairing is working. A total that equals the sum of both channels means nothing is being matched \u2014 usually a mismatched event name, or an event_id<\/code> generated separately on each side. Comparing the deduplicated count against actual orders in the shop backend is the check that matters; TikTok’s own numbers cannot reveal a purchase that neither channel reported.<\/p>\n
Staying Inside the Guardrails<\/h2>\n
Both channels belong behind the same advertising-consent signal. A server-side request is not exempt from consent because it originates in a backend: it carries the same customer data, and the lawful basis for sending it is the one collected in the browser. That means the consent state has to be stored with the order and checked before the request is built. Raw email addresses and phone numbers exist only long enough to be normalised and hashed, and the access token belongs in a secrets store rather than in application code, since it authorises writing conversions into the ad account.<\/p>\n
![\"Two-lane](\"https:\/\/www.lukaswojcik.com\/blog\/wp-content\/uploads\/diagrams\/tiktok-events-api-en.png\")