vendor/tiktok-events-2 · vendor documented

TikTok Events API 2.0 event_time is seconds, not milliseconds

The 2.0 envelope posts data[] to /event/track. event_source is web, app, offline, or crm. event_source_id is the Pixel Code on web. event_time is Unix seconds.

user.email, phone, and external_id are SHA-256 hex. user.ip and user.user_agent stay unhashed. Purchase, CompletePayment, and PlaceAnOrder need properties.value and properties.currency.

event_time is seconds, not Date.now()

A 13-digit value is milliseconds. TikTok documents seconds. The event then sits far in the future and does not attribute.

Rule: vendor.tiktok-events-2.body.event_time.invalid

What this pack matches

Hosts: business-api.tiktok.com
Paths: …/event/track…
Vendor docs: business-api.tiktok.com/portal/docs/report-app-web-offline-or-crm-events/v1.3

Rules

Codes are stable. A finding in CI, MCP, or the playground lands on the same id.

Field	Required	What it checks	Rule ids	Source
`event_source`	required	It names the channel. TikTok documents `web`, `app`, `offline`, and `crm`. Fix: Set `event_source` to `web` for Pixel-measured website events.	`vendor.tiktok-events-2.body.event_source.missing` `vendor.tiktok-events-2.body.event_source.empty` `vendor.tiktok-events-2.body.event_source.invalid`	docs
`event_source_id`	required	It is the Pixel Code when `event_source` is `web`, or the matching event-set ID for app, offline, and CRM. Fix: Set `event_source_id` to the Pixel Code from Events Manager for web events.	`vendor.tiktok-events-2.body.event_source_id.missing` `vendor.tiktok-events-2.body.event_source_id.empty`	docs
`data`	required	TikTok documents `data` as the array of events to report, at most 1,000. Fix: Send one event object, or a batch, under `data`.	`vendor.tiktok-events-2.body.data.missing`	docs
`event`	required	It is the conversion event name. TikTok documents it as required on every Events 2.0 event. Fix: Set `event` to a documented standard name such as `Purchase` or `ViewContent`.	`vendor.tiktok-events-2.body.event.missing` `vendor.tiktok-events-2.body.event.empty`	docs
`event_time`	required	TikTok documents `event_time` as Unix time in seconds, UTC. A 13-digit value is milliseconds. Fix: Send seconds since epoch, a 10-digit integer.	`vendor.tiktok-events-2.body.event_time.missing` `vendor.tiktok-events-2.body.event_time.empty` `vendor.tiktok-events-2.body.event_time.invalid`	docs
`event_id`	recommended	TikTok documents `event_id` as required when the same conversion is also sent from the browser Pixel. Fix: Send the same `event_id` the Pixel fired.	`vendor.tiktok-events-2.body.event_id.missing` `vendor.tiktok-events-2.body.event_id.empty`	docs
`page.url`	recommended	TikTok documents `page.url` as required on web events. Fix: Send the absolute page URL in `page.url`.	`vendor.tiktok-events-2.body.page.url.missing` `vendor.tiktok-events-2.body.page.url.empty` `vendor.tiktok-events-2.body.page.url.invalid`	docs
`user.email`	optional	Email must be SHA-256 hashed after trim and lowercase. Fix: Trim, lowercase, SHA-256, send the hex digest.	`vendor.tiktok-events-2.body.user.email.empty` `vendor.tiktok-events-2.body.user.email.invalid`	docs
`user.phone`	optional	Phone must be E.164 then SHA-256 hashed. Fix: Normalize to E.164, hash with SHA-256, send the hex digest.	`vendor.tiktok-events-2.body.user.phone.empty` `vendor.tiktok-events-2.body.user.phone.invalid`	docs
`user.external_id`	optional	Advertiser-side identifiers must be SHA-256 hashed.	`vendor.tiktok-events-2.body.user.external_id.empty` `vendor.tiktok-events-2.body.user.external_id.invalid`	docs
`user.ttclid`	optional	It is the TikTok click id. TikTok documents it as a web match key.	`vendor.tiktok-events-2.body.user.ttclid.empty`	docs
`user.ip`	optional	It is the visitor IP, sent unhashed.	`vendor.tiktok-events-2.body.user.ip.empty`	docs
`user.user_agent`	optional	It is the visitor user agent, sent unhashed.	`vendor.tiktok-events-2.body.user.user_agent.empty`	docs
`properties.currency`	optional	It is an ISO 4217 currency code. TikTok documents it as required for ROAS events. Fix: Use the three-letter code, such as `USD`.	`vendor.tiktok-events-2.body.properties.currency.empty` `vendor.tiktok-events-2.body.properties.currency.invalid`	docs
`properties.value`	optional	It is the total order value. TikTok documents it as required for ROAS events.		docs
`body.unhashed_email`	required	A field carries what looks like a raw email address. TikTok requires SHA-256 hashed email on Events API 2.0. Fix: Trim, lowercase, hash with SHA-256, and send the hex digest.	`vendor.tiktok-events-2.body.unhashed_email`	docs
`body.hashed_plaintext_field`	required	This field looks like a SHA-256 digest, but TikTok documents `user.ip` and `user.user_agent` as unhashed. Fix: Send the raw IP address or user agent.	`vendor.tiktok-events-2.body.hashed_plaintext_field`	docs
`body.user_needs_an_identifier`	recommended	The event has no match key. TikTok documents hashed email, phone, external_id, ttclid, or IP as the identifiers that attach the conversion to a person. Fix: Send hashed `user.email`, `phone`, or `external_id`, or `ttclid` or `user.ip`.	`vendor.tiktok-events-2.body.user_needs_an_identifier`	docs
`body.purchase_requires_value_and_currency`	required	A revenue event is missing `properties.value` or `properties.currency`. TikTok documents both for ROAS events. Fix: Set `properties.value` to the order total and `properties.currency` to a three-letter ISO 4217 code.	`vendor.tiktok-events-2.body.purchase_requires_value_and_currency`	docs

Validate a payload

pixellint validate json @payload.json --rulepack vendor/tiktok-events-2

Try this failing payload in the playground. TikTok Events API 2.0 with millisecond event_time.

{"event_source":"web","event_source_id":"C3ABCDEF1234567890","data":[{"event":"ViewContent","event_time":1770000000000,"event_id":"view-88","page":{"url":"https://example.com/p/sku"},"user":{"ip":"203.0.113.42"}}]}

cargo install pixellint · npm install pixellint