TikTok Ads

When you finish, one Datalyr event reaches the TikTok Events API and appears in TikTok Events Manager.

Before you start

Requirement	Detail
TikTok login	Has access to the advertiser in TikTok Business Center
Pixel code	TikTok Events Manager → Web events, the pixel code under the pixel name
Test Events code	TikTok Events Manager → Test events, the `TEST…` string
A live event	The trigger event exists in Events

Connect TikTok

Open Sources

Open Sources. Find the TikTok Ads card.

Authorize

Select connect. Complete TikTok authorization. Approve every requested permission.

Pick the advertiser

Choose the advertiser account that runs the campaigns. Select set as primary.

The card reads needs primary account until you finish step 3. To change advertisers, select disconnect, then reconnect. Disconnecting clears the synced TikTok campaign data.

Create the rule

Open the editor

Open Conversions. Select manage rules. Select new rule.

Set the trigger

Fill rule name. Pick the trigger event. Pick TikTok as target platform.

Pick the pixel

Pick the pixel under TikTok Pixel / App. Select next.

Map the event

Pick the platform standard event. Set value to dynamic for revenue events. Set currency.

Save

Select save. Enable the rule.

Reference

We post to POST https://business-api.tiktok.com/open_api/v1.3/event/track/ in the Events API 2.0 shape. Each request carries exactly one event.

Standard events

Asset type	Event names we send
Pixel (web, server)	`AddPaymentInfo`, `AddToCart`, `AddToWishlist`, `CompletePayment`, `CompleteRegistration`, `Contact`, `InitiateCheckout`, `PlaceAnOrder`, `Search`, `StartTrial`, `SubmitForm`, `Subscribe`, `ViewContent`
App	`AddToCart`, `Checkout`, `InstallApp`, `LaunchAPP`, `Login`, `Purchase`, `Subscribe`, `ViewContent`

event_source is app for iOS, Android, and React Native events. It is web for everything else, including Stripe and Shopify webhooks.

Matching fields in `user`

Field	Channel	Normalization before SHA-256
`email`	web and app	lowercase, trim; rejected unless it matches `[email protected]`
`phone`	web and app	E.164 with the leading `+` kept
`external_id`	web only	lowercase, trim
`first_name`, `last_name`	web only	lowercase, trim
`city`	web only	lowercase, every character outside `a-z` removed
`state`	web only	2-letter lowercase code
`zip_code`	web only	lowercase, spaces and dashes removed, first 5 characters for `us`
`country`	web only	lowercase ISO alpha-2; omitted when unmappable
`ttclid`	web only	not hashed
`ttp`	web only	not hashed. This is the `_ttp` first-party cookie
`ip`	web and app	not hashed
`user_agent`	web and app	not hashed; dropped when it starts with `node`, `undici`, `axios`, `got`, `curl`, `python`, `java`, `go-http-client`, or `wget`
`locale`	web and app	not hashed
`idfa`, `idfv`, `gaid`	app only	not hashed
`att_status`	app only	not hashed. Defaults to `NOT_APPLICABLE`

We drop an external_id that starts with $SuperwallAlias:, $RCAnonymousID:, or stripe_, because TikTok can never match those. We fall back to the distinct id instead.

Value and `properties`

Field	Rule
`value`	The rule’s `value_path`, else `value_static`, else `value` / `revenue` / `total` / `amount` in the event
`currency`	The rule’s currency. Datalyr writes `USD` if the rule sets none
Other fields	`content_ids`, `content_type`, `content_name`, `content_category`, `contents`, `num_items`, `price`, `quantity`, `order_id`, `shop_id`, `search_string`, `description`

We add a page object with url and referrer for web events. We add app and ad objects for app events.

Deduplication

We send event_id, the same UUID the browser TikTok Pixel fires with, and TikTok collapses the pair into one conversion. App events carry it too, so a retry cannot double-count.

Verify

Set a Test Events code before you select send test event. TikTok has no validate-only mode, so a test without a code creates a real billable conversion.

Open Conversions. Select manage rules. Open your rule.
Select send test event.
Open TikTok Events Manager → Test events.
Confirm the event name, value, and currency match the rule.
Return to Datalyr. Confirm the rule’s sent count went up by 1.

When it does not work

Symptom	Cause	Check	Fix
Rule detail shows `skipped`, reason `test_event_code_required`	The rule has no Test Events code	The rule’s `config.test_event_code`	Contact support to set the Test Events code
Delivery `skipped`, reason `zero_value_purchase`	A `CompletePayment` resolved to a value of 0	The `value_path` against a real event payload	Point `value_path` at the amount field
Body `code: 40001`	The TikTok token expired or was revoked	The card state in Sources	Select disconnect, then reconnect
Body `code: 40002`	TikTok throttled the request	The delivery row’s response body	Nothing. We retry through the dead-letter queue
Body `code` between `40100` and `40199`	A temporary TikTok fault	The delivery row’s response body	Nothing. We retry
Any other `code` in the `4xxxx` range	A parameter TikTok rejected	The response `message` on the delivery row	Fix the named field in the rule. We do not retry these
Body `code` at `50000` or above	A TikTok server fault	The delivery row’s response body	Nothing. We retry
HTTP 200 and `code: 0`, nothing in Events Manager	The event landed under a different pixel code	`event_source_id` in the request payload	Repick the asset in the rule
Card reads `needs primary account`	Authorization finished, no advertiser chosen	The TikTok Ads card	Select select account

Conversion delivery: retry, dedup, and status rules for every platform.
Conversions: read one delivery row and its response body.
Attribution: how ttclid reaches a server-side purchase.

Get started

Installation

Revenue

Using Datalyr

Advanced

Integrations

Account & billing

Troubleshooting

Before you start

Connect TikTok

Create the rule

Reference

Standard events

Matching fields in `user`

Value and `properties`

Deduplication

Verify

When it does not work

Next

​Before you start

​Connect TikTok

​Create the rule

​Reference

​Standard events

​Matching fields in user

​Value and properties

​Deduplication

​Verify

​When it does not work

​Next

Before you start

Connect TikTok

Create the rule

Reference

Standard events

Matching fields in `user`

Value and `properties`

Deduplication

Verify

When it does not work

Next