TikTok Conversions API Setup: Pixel, Events API & Deduplication (2026)
Attribution settings and event delivery are two separate controls. This guide shows how to set up the second one correctly.
TikTok’s Conversions API (called Events API in its documentation) sends conversion events from your server and works best alongside the Pixel, with a shared event_id so overlapping events deduplicate. It improves how events reach TikTok. It does not change which interactions earn credit; that is set separately in Attribution Manager. Set up and verify both layers, and keep them separate when you reconcile TikTok reporting with your backend.
Three measurement layers, three different questions
Event delivery
Did TikTok receive the event? Pixel and Events API control this.
Event matching
Can TikTok associate the event with a person or an ad click? Match keys such as ttclid, hashed email and phone control this.
Attribution
Does TikTok credit an ad interaction within the configured window? Attribution Manager controls this.
TikTok recommends Pixel and Events API together for web. Default attribution for Pixel and Events API setups is 7-day click and 1-day view; click options are 1, 7, 14 and 28 days, view options are off, 1 and 7 days. Duplicates match on pixel ID, event name and event_id: copies within 5 minutes are merged, later copies up to 48 hours are deduplicated. Purchase replaced CompletePayment as the standard name in 2025; legacy names still work. The ttclid is attached to ad landing URLs, so your site must store it before checkout. Events API 2.0 posts to /open_api/v1.3/event/track/. EMQ is a match-key coverage diagnostic with no universal target.
Estimate the gap before you build
Not sure the setup is worth it for your account? The TikTok CAPI Recovery Calculator models how much conversion signal might be missing. This guide covers the implementation.
Video walkthrough
A walkthrough of attribution settings versus event delivery, and a server-side integration built in Make.com.
TikTok attribution windows vs. event delivery
Two settings often get blamed for the same symptom: TikTok reporting more or fewer conversions than your backend. They are different controls, and fixing one does not touch the other.
| Control | What it decides | Where you change it |
|---|---|---|
| Attribution windows | Which ad interactions can receive credit: clicks within a click-through window, and views within a view-through window | Attribution Manager in TikTok Ads Manager |
| Event delivery | Whether conversion events reach TikTok, with which match keys, and whether duplicates are merged | Pixel and Events API implementation; checked in Events Manager |
For web conversion setups using the Pixel or Events API, TikTok documents 7-day click and 1-day view as the default. Click-through can be set to 1, 7, 14 or 28 days. View-through can be set to off, 1 or 7 days. TikTok’s guidance is to match the window to your conversion journey: longer for considered purchases, shorter for quick ones.
View-through is a defined category, not an error
A view-through conversion means a person saw the ad, did not click, and converted inside the view window. It is how TikTok defines that kind of credit. Whether it belongs in the numbers you use to judge a campaign depends on your measurement goal. If you want reporting based on clicked ads only, view-through can be set to off where that option is available. Review the window against your objective rather than switching it for every account.
Events API does not alter any of this. It changes how events are delivered, and each ttclid still follows the click window configured in Attribution Manager. Review both when you reconcile TikTok against your own records.
What the Events API actually changes
TikTok describes Events API as a server-to-server interface for sharing marketing data across web, app and offline sources. For websites it recommends running it alongside your existing Pixel, with deduplication. Pixel or Events API setup is also a prerequisite for the Web Conversions objective in Ads Manager.
When you connect Events API to an order system, you send events from server-side data instead of relying only on the browser to execute. That helps when browser-side restrictions keep a Pixel call from completing. It is also only as good as its source: the event is as reliable as the backend record and the implementation behind it, and it can carry only the identifiers you actually collected. It also sends more than purchases; lead, registration, checkout and other standard events can all go through it.
TikTok has published one reference figure: on average, advertisers using Pixel and Events API together saw 19% more events captured and a 15% improvement in cost per action, in an analysis covering November 2022 to February 2023. That is a TikTok-run average from a past period, not a prediction for your account.
Pixel vs. Events API
| Factor | Browser Pixel | Events API |
|---|---|---|
| Where the event starts | Visitor’s browser | Your backend, order system, CRM or other server-side source |
| Browser-side restrictions | Ad blockers, privacy controls and consent choices can affect whether the call completes | Delivery does not depend on the browser firing the same request; consent and privacy rules still apply |
| Identifiers available | Whatever the browser exposes, including the _ttp cookie and ttclid | Whatever your system stored, such as ttclid, hashed email and phone |
| Changes attribution windows | No | No. Attribution Manager controls this separately |
| Setup effort | Low: install a tag or use a partner integration | Medium: needs a trigger, stored identifiers, hashing and a shared event_id |
They are meant to run together. The Pixel supplies browser context; Events API supplies a server-side path. With matching event names and event_id values, TikTok merges them into one event.
Preserve the ttclid and the conversion ID
This is where most server-side builds go wrong. A Stripe or Shopify payment webhook does not contain the TikTok click
ID unless you put it there. TikTok attaches the ttclid to the landing-page URL when
someone clicks an ad, so your site has to read it on arrival and keep it until the order completes.
Capture on the landing page
Read ttclid from the URL, and the _ttp cookie where consent allows, when the visitor arrives. TikTok attaches the click ID automatically; the code that reads and stores it is yours.
Persist it against the session, customer or order
Attach the values to the checkout, for example as order metadata or cart attributes, and create the event_id now, at order creation, so both channels can use it.
Fire the Pixel with that event_id
The browser event for the same order carries the same event_id and the same event name.
On the confirmed order, send the server event
When the payment webhook arrives, retrieve the stored identifiers, normalize and hash email and phone, and POST to Events API with the stored event_id.
One rule for event_id
The same conversion must use the same event_id in Pixel and Events API. The ID should
originate in your order architecture and be stored, not created fresh by whichever step runs last. A server-side step
that invents its own ID after the browser event has fired cannot match it.
Deduplication with event_id
Deduplication is required when the same conversion goes through both Pixel and Events API. It is not required if the two channels send different events with no overlap. Without it, one purchase can be counted twice and your reported volume moves in the opposite direction from the gap you were trying to close.
TikTok matches on three values: the pixel ID (event_source_id in the API), the event
name, and event_id. All three must be identical across the two copies.
| Scenario | What TikTok does |
|---|---|
| Pixel and API copies arrive within 5 minutes of each other | Merged into the first event; extra match keys and parameters from the later copy are combined in |
| A copy arrives after 5 minutes, within 48 hours of the first | Deduplicated; the first event received is the one recorded |
| Pixel-to-Pixel or API-to-API repeats | Deduplicated within 48 hours of the first event |
| API event has no event_id but _ttp is present | TikTok attempts browser-to-server deduplication using the _ttp value |
The merge behavior is why the pairing works: a browser event with few identifiers and a server event carrying hashed email, hashed phone and ttclid can combine into one richer event, as long as the three dedup values match.
What not to do
- Do not generate one ID in the browser and a different one on the server.
- Do not send different event names for the same conversion, such as Pixel
CompletePaymentand APIPurchase. - Do not treat an HTTP 200 as proof of deduplication; confirm it in Events Manager.
- Do not switch off the Pixel because Events API is live.
Event names and payload fields to validate
Use the standard event your integration supports
In May 2025 TikTok renamed CompletePayment to Purchase and SubmitForm to Lead. Legacy names are converted automatically and appear under the new names in reporting, audiences and optimization, and TikTok says existing setups keep working with no code changes. For a new pixel, use Purchase. For a live pixel already optimizing on CompletePayment there is no urgent need to rename. Some partner integrations and older guides still use CompletePayment, so check the documentation for the connection method you are using, and send the same name from both channels. Event names are case-sensitive.
Fields to include
Include the parameters TikTok requires or recommends for your event and reporting goal. For purchase-value
measurement that normally means value and currency
(a decimal and a three-letter ISO 4217 code), alongside event_id, a timestamp and your
match keys. TikTok’s Payload Helper and developer reference are the authority on exact fields for your event source.
Normalize before hashing
TikTok documents SHA-256 hashing for identifiers such as email and phone. Lowercase the email and trim whitespace before hashing, and normalize phone numbers as TikTok’s current documentation specifies. A hash of badly formatted input will not match.
Illustrative web-event payload
This is an illustrative structure, not a copy-paste production payload. Validate fields and nesting against TikTok’s
Events API 2.0 documentation and Payload Helper. Use a test_event_code from Events
Manager while testing, and remove it before launch.
POST https://business-api.tiktok.com/open_api/v1.3/event/track/
Access-Token: YOUR_EVENTS_API_TOKEN{
"event_source": "web",
"event_source_id": "YOUR_PIXEL_CODE",
"test_event_code": "TEST_CODE_FROM_EVENTS_MANAGER",
"data": [{
"event": "Purchase",
"event_time": 1767225600,
"event_id": "ORDER-12345",
"user": {
"email": "SHA256_OF_NORMALIZED_EMAIL",
"phone": "SHA256_OF_NORMALIZED_PHONE",
"ttclid": "STORED_TTCLID",
"ttp": "STORED_TTP_COOKIE",
"ip": "END_USER_IP",
"user_agent": "END_USER_USER_AGENT"
},
"properties": { "currency": "USD", "value": 149.00 },
"page": { "url": "https://example.com/thank-you" }
}]
}
Events API 2.0 is TikTok’s recommended endpoint for web, app, offline and CRM events. The product is “2.0” and the
URL version is “v1.3”; they are not competing versions. The older /pixel/track/ and
/app/track/ endpoints belong to Events API 1.0. Pass the end user’s IP and user agent, not
your server’s, and keep the access token server-side.
If a payload is invalid or mapped incorrectly, check the API response and Events Manager diagnostics. Do not assume a rejection will be obvious.
EMQ and match keys
Event Match Quality is a diagnostic based on match-key coverage. It is not a pass mark and it does not convert into a recovery percentage. Use it to find gaps in the keys you send, improve the coverage and quality of the keys you are permitted to share, then watch how matching and reporting change.
| Match key | Note |
|---|---|
| ttclid | Links the event to a TikTok ad click. Must be captured on landing and stored. Follows the click window set in Attribution Manager. |
| Email, phone | Normalize, then hash with SHA-256. |
| External ID | Your own identifier; hash where TikTok’s guidance requires. |
| IP address, user agent | Supplemental context. Use the end user’s values. |
| _ttp cookie | TikTok documents that passing first-party cookies through a dual Pixel and Events API setup enables better matching. Persists 13 months from last use; depends on cookie settings and consent. |
Testing in Events Manager
TikTok’s Events Manager provides Test Events, event details, matching information, deduplication information, EMQ and Diagnostics. Use them before you trust the data.
| Test | What to verify |
|---|---|
| Event received | The server event appears in Test Events |
| Correct event | Purchase (or legacy CompletePayment) is recognized, with value and currency |
| Matching | The match keys you sent show as received |
| Deduplication | Browser and server copies of one order collapse into one |
| Diagnostics | No material configuration errors |
| Production | test_event_code removed before launch |
Choosing an implementation path
TikTok lists commerce partners, data partners and direct API integration as supported paths, and suggests deciding which events, parameters and match keys support your marketing objective before choosing one.
| Path | Best fit | Trade-off |
|---|---|---|
| Native commerce integration | Store platform already has a suitable TikTok integration | Least control over mapping and routing |
| Direct Events API | An engineering team wants full control | You build and maintain it |
| Server-side tag management | You already run server-side Google Tag Manager | Infrastructure and upkeep |
| Make + HTTP | An operator needs webhook routing, transformation or several destinations | An extra layer to monitor |
When Make.com is the right implementation layer
Make fits when the workflow has to receive a webhook from an order system, transform or normalize the data, preserve identifiers, and route the same conversion to more than one destination, such as TikTok, Meta, a CRM and reporting. Make supports custom webhook triggers and HTTP requests, so a scenario can accept a confirmed order, look up the stored identifiers, hash customer data and POST to Events API without custom server code.
When you may not need Make
If your Shopify, WooCommerce or other native integration already sends the events, identifiers and event_id deduplication you need, an automation layer can add complexity without enough benefit.
Prerequisite
The flow starts from a working webhook. If you have not set that up, start with configuring a Make.com Stripe webhook.
Order confirmed (webhook carries order ID + stored ttclid / event_id)
↓
Make.com: retrieve stored identifiers → normalize → hash email/phone
↓
HTTP: POST to TikTok Events API (event_id reused, never regenerated)
↓
Optional: same conversion routed to Meta, CRM, reportingOffline and CRM events
Events API also handles offline conversions such as in-store purchases and CRM outcomes. TikTok documents three ways to get offline events in: send them through Events API directly, use a partner integration, or upload them manually in Events Manager. Offline conversions use their own attribution windows: click-through of 1, 7, 14 or 28 days and view-through of 1 or 7 days.
LiveRamp documents a related route, the TikTok Events API Program for Offline Conversions, formerly the TikTok Offline Tracking Program. It runs through LiveRamp’s Conversions API, uses OAuth authorization, and has a maximum 28-day lookback for an offline conversion rule. Access involves LiveRamp or TikTok approval. For most digital-first stores the online path above is the relevant one.
Consent and data governance
Your responsibility
Events API is a data-delivery mechanism, not a consent-management system. Your implementation decides which events and identifiers are sent, based on your consent framework, applicable law and TikTok’s data terms. If a visitor has not given consent for marketing data sharing, the server-side call needs to respect that just as the browser call does. TikTok offers Pixel cookie consent modes and Limited Data Use controls, and advises involving marketing, legal and technical teams before deciding what to share. This is not legal advice.
TikTok CAPI troubleshooting checklist
| Symptom | Check first |
|---|---|
| Server event not appearing | Access token, endpoint, event_source_id (pixel code), Test Events |
| Event appears but matching is weak | Availability and formatting of email, phone, external ID, ttclid, IP and user agent |
| Purchases double-count | Same pixel ID, event name and event_id across Pixel and API |
| ttclid missing | Captured on landing and persisted to order or customer data before the webhook |
| Purchase value wrong | Currency code, decimal value, order mapping, refunds |
| Event arrives but is not attributed | Attribution windows, click ID age against the click window, match keys, event timing |
| Diagnostics show issues | Events Manager Diagnostics for the specific event |
Frequently asked questions
Does the TikTok Conversions API fix view-through attribution by itself?
No. Events API changes how conversion events are delivered to TikTok. View-through and click-through credit is controlled separately by the attribution windows set in Attribution Manager. Review both when reconciling TikTok reporting with your backend or other measurement systems.
What are TikTok’s default attribution windows?
For web conversion setups using the Pixel or Events API, TikTok’s Attribution Manager documents 7-day click-through and 1-day view-through as the default. Click-through options are 1, 7, 14 and 28 days; view-through options are off, 1 and 7 days. Windows can be configured to match your campaign and measurement objective.
Why might TikTok-reported conversions differ from my backend totals?
Several things can cause a gap: the attribution windows (including view-through), events that never reached TikTok, events that reached TikTok but did not match, duplicate or missing event_id values, and differences in how refunds, currency and time zones are handled. Check delivery, matching and attribution separately.
What is the TikTok Conversions API?
TikTok’s Conversions API is commonly called Events API. It is a server-to-server interface for sharing web, app, offline and CRM events with TikTok. TikTok recommends using it alongside the Pixel for web conversion measurement.
Do I need event_id deduplication if I run the Pixel and Events API together?
Yes, when both channels send the same conversion. TikTok matches on pixel ID, event name and event_id. Pixel and API copies arriving within 5 minutes are merged; later copies within 48 hours of the first are deduplicated.
Which event name should I use for a purchase?
Use Purchase for new setups. TikTok renamed CompletePayment to Purchase in 2025 and converts legacy names automatically. Some partner integrations and older documentation still use CompletePayment, so check the documentation for your connection method and send the same name from Pixel and Events API.
Why does my payment webhook not contain the ttclid?
A payment webhook only contains what you attached to the order. The ttclid arrives on the landing-page URL, so your site must capture it and store it against the session, customer or order, for example in order metadata, before the webhook fires.
What EMQ score should I aim for?
There is no universal target. EMQ is a diagnostic based on match-key coverage. Improve the coverage and quality of the keys you are permitted to send, then watch how matching and reporting change in Events Manager.
Can Make.com handle the TikTok Events API setup?
Yes. Make supports custom webhook triggers and HTTP requests, so a scenario can receive a confirmed order, retrieve stored identifiers, hash customer data and POST to TikTok’s Events API. It is most useful when the event must be transformed or routed to several destinations; a native integration may be enough otherwise.
Does Events API remove the need for consent?
No. Events API is a data-delivery mechanism, not a consent system. Your implementation decides which events and identifiers are sent based on your consent framework, applicable law and TikTok’s data terms. TikTok also offers Pixel cookie consent modes and Limited Data Use controls.
Can I send offline conversions to TikTok?
Yes. TikTok documents three routes for offline events: sending them through Events API directly, using a partner integration, or uploading manually in Events Manager. LiveRamp documents a related program, formerly called the TikTok Offline Tracking Program, with a maximum 28-day lookback for offline conversion rules.
Build the server-side path
Capture the ttclid, store one event_id per order, send matching events from Pixel and Events API, and verify in Events Manager. If the workflow needs routing or transformation, Make.com is one way to build it.
Related guides
Official documentation used for this guide
TikTok’s interface, event names and API references change. Check these before deploying or updating a production setup.
Pixel + Events API recommendation and integration methods.
Dedup keys, 5-minute merge and 48-hour window.
Default and configurable click-through and view-through windows.
How ttclid is attached to landing URLs and tied to the click window.
Purchase and Lead renames and legacy-name support.
_ttp and ttclid cookie details, cookie consent mode.
Offline upload routes and offline attribution windows.
The /event/track/ endpoint and request structure.
OAuth setup and the 28-day lookback for offline rules.
Source of the 19% more events and 15% CPA average (Nov 2022 – Feb 2023).