Home
Integrations
TikTok Events API

TikTok Events API integration: identity-resolved conversions, sent server-side

Forward resolved conversions to the TikTok Events API so the algorithm optimizes on customers, not sessions.

Request a demo Start free trial

Role: Destination
Category: Ad platforms
Pre-built connectors: 12 sources
Plans: All plans
Spend in: TikTok Ads

What Upstack sends

Every conversion reaches TikTok Events API with the identifiers it matches on. Captured on the server, resolved to a person, then sent.

In: from Shopify1 of 12 sources

order_idShopify order and checkout token
email / phonecustomer contact from checkout
customer_idShopify customer record, if they have one
line_itemsproducts, variants and quantities
total / subtotal / discountorder economics

Storefront events from the Upstack Pixel, orders directly from Shopify.

Resolved before it is sent

IdentityMatched against a 750M+ device graph, so a phone browse and a desktop checkout resolve to one customer.
customer_typeNew or returning, resolved before send.
DeduplicationBrowser and server copies of the same purchase collapse on event ID, so nothing is counted twice.
Bot and fraud filteringAutomated traffic never reaches the model, because what you keep out of the training set matters as much as what goes in.

Out: to TikTok Events APIOn every event

email / phone (hashed)Events API matching
ttclid / ttpattribute the click
event_idbrowser and server dedupe
value / currencyoptimize on revenue

Events API with a resolved customer attached.

See the set-up reference See all 12 sources How resolution works

About TikTok Events API

TikTok’s algorithm needs volume and match quality to learn.

Upstack raises both: conversions captured server-side survive the ad blockers and in-app browsers that cost you events, and each one carries hashed identifiers and a restored ttclid. Deduplication on event ID keeps the pixel running alongside without inflating results, so you can compare the two feeds before committing.

What TikTok Events API is

TikTok Ads is a primary prospecting channel for brands with strong creative, where the algorithm does more of the targeting work than the advertiser does.

That makes conversion signal unusually important: TikTok’s Events API is how the platform learns which of the people it showed your ad to actually bought.

How TikTok Events API works

TikTok’s algorithm does an unusually large share of the targeting work, which makes the conversion feed the main lever an advertiser controls. The Events API accepts server-side events with hashed identifiers and a click ID (ttclid), and pairs them with browser pixel events using a shared event ID so a purchase is counted once. Match rate (the share of events TikTok can tie to a user) determines how much of what you send actually contributes to optimization.

What you can do with it

Three jobs this connector does inside TikTok Events API.

Send complete conversions

Conversions reach TikTok through its server-side API with restored click IDs and hashed identifiers attached, so more of what you send is matched on arrival, and the conversions you never saw stop being invisible.

Optimize on the customer you want

Map any order attribute to the conversion TikTok receives (profit rather than revenue, new customers rather than repeat buyers, high-value orders rather than every checkout), so the platform learns from the buyers worth acquiring.

Signal the algorithm can learn from

TikTok does more of the targeting work than most channels, so the quality of the conversion feed has an outsized effect on what it learns to look for.

How it works

How the TikTok Events API integration works.

Upstack sends your storefront events to the TikTok Events API with hashed identifiers, the ttclid click ID and a shared event_id, alongside the TikTok Pixel.

Standard events

PageView is sent as Pageview, and ViewContent, AddToCart, InitiateCheckout and Purchase keep their names, with content_id, value, currency and order_id where they apply. TikTok event names are case-sensitive.

Match keys

Email, phone and external_id are sent when available, hashed with SHA-256 as the Events API requires, plus the ttclid click ID captured by the Upstack Pixel for deterministic matching.

Deduplication on event_id

Browser + Server is the default: Upstack loads the TikTok Pixel and sends server events with the same event_id, and TikTok keeps one copy when both use the same Pixel ID. Choose Server to skip the browser pixel.

Paid-click purchase events

TikTok receives Upstack’s first paid click, last paid click and first-and-only paid click purchase events as custom events, such as FpcTiktokPurchase. Each carries the full order value, so pick one as your optimization event.

What to expect

Gains show mainly on PageView, ViewContent and AddToCart. The Purchase match isn’t expected to change, because checkout already sends customer data. A test purchase appears in Events Manager within a few minutes.

Delivery

Events are queued with automatic retries and backoff. If TikTok rate-limits with HTTP 429, most events still arrive within 30 minutes, and your TikTok rep can raise the API quota.

Events and the data they carry

Upstack event	Sent as	Data on the event
PageView	Pageview	url, referrer
ViewContent	ViewContent	content_id, content_type, value, currency
AddToCart	AddToCart	content_id, content_type, value, currency
InitiateCheckout	InitiateCheckout	value, currency, quantity
Purchase	Purchase	content_id, value, currency, order_id

Setup

Set up the TikTok Events API integration.

What you need

Admin access to your TikTok Business Center, with a TikTok Pixel in Events Manager.
The Pixel ID, also called the Dataset ID: a 20-character alphanumeric string.
An Events API access token generated in Events Manager. It is shown only once.
Access to your Shopify admin to turn off TikTok data sharing.

Complete TikTok onboarding guide

Step 1

Find or create the pixel

In TikTok Events Manager, open Tools, Events, Data sources and copy the Pixel ID next to the pixel’s name. To start fresh, connect a new Web data source named UpstackData.
Step 2

Generate the access token

Open the pixel’s Settings tab, find the Events API section, click Generate access token and copy it straight away.
Step 3

Add the TikTok destination

In Upstack, open Destinations, click New Destination, choose TikTok, enter the Pixel ID and access token and save. The destination shows Healthy.
Step 4

Disconnect Shopify’s TikTok data sharing

In Shopify, open Sales channels, TikTok, Settings, Data sharing and disconnect Customer Data Sharing. Remove TikTok pixel apps and theme snippets too: Shopify’s native integration sends no matching event_id.

Check it

How to verify it’s working, and common fixes.

How to verify it’s working

Upstack’s Destinations page shows TikTok as Healthy.
TikTok Events Manager shows events arriving through both Browser and Server, with a Server badge on server events.
A test order produces exactly one Purchase event.
“Update Recommended” warnings in Events Manager are normal and need no action.

Common problems and fixes

No events after 10 minutes of traffic.: Check the Pixel ID and access token for spaces or truncation and confirm the destination is Healthy. If the token was revoked or expired, generate a new one.
The destination is Unhealthy.: The Pixel ID must be exactly 20 characters, and the token must come from the same pixel, copied right after it was generated.
Duplicate events.: The Pixel ID in Upstack differs from the pixel on your store, or another sender is active: Shopify’s TikTok data sharing, a TikTok pixel app or a snippet in your theme. Remove it and watch for 24 hours.
Low match quality.: Link TikTok ads straight to your storefront so the ttclid reaches the URL, and make sure checkout collects email and phone.
Events delivered but zero conversions.: Check the Event Mapping tab. Events need event_time, event_source_url and at least one identity field.

Pre-built connectors

12 sources connect to TikTok Events API. Whichever of these you run, TikTok Events API is one switch away.

See all connectors

Documentation

Set-up reference.

Set-up, event schema and field mapping for TikTok Events API as a destination, next to the TikTok Events API developer docs.

FAQ

TikTok Events API integration questions.

What does Upstack send to the TikTok Events API?

Page views, product views, add-to-carts, checkouts and purchases, mapped to TikTok’s event names, with hashed email, phone and external_id when available, the ttclid click ID and a shared event_id.

Will I see duplicate conversions if I run both the TikTok Pixel and the Events API?

No, as long as the Pixel ID in Upstack matches the pixel on your store. Upstack sends the same event_id with each server event and TikTok keeps one copy. If you see duplicates, the Pixel IDs almost always differ.

Do I need to turn off Shopify’s TikTok data sharing?

Yes. Shopify’s native TikTok integration doesn’t send a matching event_id, so TikTok can’t deduplicate its events against Upstack’s.

What do I need to connect TikTok to Upstack?

Admin access to TikTok Business Center, your Pixel ID (a 20-character string, also called the Dataset ID) and an Events API access token generated in the pixel’s settings.

Can I use the Events API without the TikTok Pixel in the browser?

Yes. Set the destination’s Tracking Method to Server and Upstack stops loading the TikTok Pixel on your store.

Why is my TikTok match rate low?

Match rate depends on the identity data each event carries. Link ads straight to your storefront so the ttclid lands in the URL, and make sure checkout collects email and phone. Anonymous visitors have fewer keys to match.

Will my Purchase match score improve?

Little change is expected there, because checkout already sends customer data. The improvement shows on page views, product views and add-to-carts.

Can I send only some event types to TikTok?

Yes. Event filtering can forward only purchases, only standard events or any subset. Excluded events are dropped, not retried.

Which plans include the TikTok Events API integration?

All plans. Upstack has three plans that scale with your order volume, and the same integrations are on every plan.

Can Upstack also pull spend from TikTok Ads?

Yes, through the TikTok Ads integration. Pull TikTok cost and delivery data into Upstack alongside your orders, so blended ROAS and true CAC are computed from both halves of the equation rather than one.