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.
What this pack matches
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`. Native JSON type: string. Fix: Set `event_source` to `web` for Pixel-measured website events. | vendor.tiktok-events-2.body.event_source.missingvendor.tiktok-events-2.body.event_source.emptyvendor.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. Native JSON type: string. Fix: Set `event_source_id` to the Pixel Code from Events Manager for web events. | vendor.tiktok-events-2.body.event_source_id.missingvendor.tiktok-events-2.body.event_source_id.emptyvendor.tiktok-events-2.body.event_source_id.invalid |
docs |
data |
required | TikTok documents `data` as the array of events to report, at most 1,000. Native JSON type: array. Minimum array items: 1. Maximum array items: 1000. Fix: Send one event object, or a batch, under `data`. | vendor.tiktok-events-2.body.data.missingvendor.tiktok-events-2.body.data.invalid |
docs |
root |
optional | The cited primary model documents this field representation. Native JSON type: object. | vendor.tiktok-events-2.body.root.invalid |
docs |
data[] |
optional | The cited primary model documents this field representation. Native JSON type: object. | vendor.tiktok-events-2.body.data[].invalid |
docs |
event |
required | It is the conversion event name. TikTok documents it as required on every Events 2.0 event. Body scope: data[]. Native JSON type: string. Fix: Set `event` to a documented standard name such as `Purchase` or `ViewContent`. | vendor.tiktok-events-2.body.event.missingvendor.tiktok-events-2.body.event.emptyvendor.tiktok-events-2.body.event.invalid |
docs |
event_time |
required | TikTok documents `event_time` as Unix time in seconds, UTC. A 13-digit value is milliseconds. Body scope: data[]. Native JSON type: integer. Fix: Send seconds since epoch, a 10-digit integer. | vendor.tiktok-events-2.body.event_time.missingvendor.tiktok-events-2.body.event_time.emptyvendor.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. Body scope: data[]. Native JSON type: string. Fix: Send the same `event_id` the Pixel fired. | vendor.tiktok-events-2.body.event_id.missingvendor.tiktok-events-2.body.event_id.emptyvendor.tiktok-events-2.body.event_id.invalid |
docs |
page.url |
recommended | TikTok documents `page.url` as required on web events. Body scope: data[]. Applies when {"kind":"value_in","param":"event_source","values":["web"]}. Fix: Send the absolute page URL in `page.url`. | vendor.tiktok-events-2.body.page.url.missingvendor.tiktok-events-2.body.page.url.emptyvendor.tiktok-events-2.body.page.url.invalid |
docs |
page.referrer |
optional | It is the referrer URL. TikTok documents the full URL, including query, as `document.referrer` or the Referer header. Body scope: data[]. Fix: Send an absolute URL in `page.referrer`, including the scheme. | vendor.tiktok-events-2.body.page.referrer.emptyvendor.tiktok-events-2.body.page.referrer.invalid |
docs |
user.email |
optional | Email must be SHA-256 hashed after trim and lowercase. Body scope: data[]. Fix: Trim, lowercase, SHA-256, send the hex digest. | vendor.tiktok-events-2.body.user.email.emptyvendor.tiktok-events-2.body.user.email.invalid |
docs |
user.phone |
optional | Phone must be E.164 then SHA-256 hashed. Body scope: data[]. Fix: Normalize to E.164, hash with SHA-256, send the hex digest. | vendor.tiktok-events-2.body.user.phone.emptyvendor.tiktok-events-2.body.user.phone.invalid |
docs |
user.external_id |
optional | Advertiser-side identifiers must be SHA-256 hashed. Body scope: data[]. | vendor.tiktok-events-2.body.user.external_id.emptyvendor.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. Body scope: data[]. | vendor.tiktok-events-2.body.user.ttclid.empty |
docs |
user.ttp |
optional | It is the `_ttp` cookie Pixel SDK writes. TikTok documents it as an unhashed web match key. Body scope: data[]. Fix: Read `_ttp` under your domain into `user.ttp`, or drop the empty pair. | vendor.tiktok-events-2.body.user.ttp.empty |
docs |
user.ip |
optional | It is the visitor IP, sent unhashed. Body scope: data[]. | vendor.tiktok-events-2.body.user.ip.empty |
docs |
user.user_agent |
optional | It is the visitor user agent, sent unhashed. Body scope: data[]. | vendor.tiktok-events-2.body.user.user_agent.empty |
docs |
user.locale |
optional | It is the BCP 47 language identifier. TikTok documents tags such as `en-US` and `zh-CN`, and samples also use `en_US`. Body scope: data[]. Fix: Send a tag such as `en-US` or `en_US`. | vendor.tiktok-events-2.body.user.locale.emptyvendor.tiktok-events-2.body.user.locale.invalid |
docs |
properties.currency |
optional | It is an ISO 4217 currency code. TikTok documents it as required for ROAS events. Body scope: data[]. Fix: Use the three-letter code, such as `USD`. | vendor.tiktok-events-2.body.properties.currency.emptyvendor.tiktok-events-2.body.properties.currency.invalid |
docs |
properties.value |
optional | It is the total order value. TikTok documents a float with no currency symbol, such as `10.00`. Body scope: data[]. Fix: Send a number such as `20`, with no currency symbol. | vendor.tiktok-events-2.body.properties.value.emptyvendor.tiktok-events-2.body.properties.value.invalid |
docs |
properties.content_type |
optional | It is how catalog ids map. TikTok documents `product` when `content_id` is a sku, or `product_group` when it is an item group. Body scope: data[]. Fix: Set `properties.content_type` to `product` or `product_group`. | vendor.tiktok-events-2.body.properties.content_type.emptyvendor.tiktok-events-2.body.properties.content_type.invalid |
docs |
properties.contents[].content_id |
optional | It is the product or content id on a contents row. TikTok documents matching catalog `sku_id` or `item_group_id`. Body scope: data[]. Fix: Set `properties.contents[].content_id` to the catalog item ID, or drop the empty pair. | vendor.tiktok-events-2.body.properties.contents[].content_id.empty |
docs |
properties.contents[].price |
optional | It is the unit price of one item. TikTok documents `price` as the single-item price, not the order total. Body scope: data[]. Fix: Send `properties.contents[].price` as a number, such as `10`. Put the order total in `properties.value`. | vendor.tiktok-events-2.body.properties.contents[].price.emptyvendor.tiktok-events-2.body.properties.contents[].price.invalid |
docs |
event_source |
optional | The cited primary model documents this field representation. Body scope: data[]. | docs | |
root |
optional | The cited primary model documents this field representation. Body scope: data[]. | docs | |
user |
optional | The cited primary model documents this field representation. Body scope: data[]. Native JSON type: object. | vendor.tiktok-events-2.body.user.invalid |
docs |
properties |
optional | The cited primary model documents this field representation. Body scope: data[]. Native JSON type: object. | vendor.tiktok-events-2.body.properties.invalid |
docs |
page |
optional | The cited primary model documents this field representation. Body scope: data[]. Native JSON type: object. | vendor.tiktok-events-2.body.page.invalid |
docs |
app |
optional | The cited primary model documents this field representation. Body scope: data[]. Native JSON type: object. | vendor.tiktok-events-2.body.app.invalid |
docs |
ad |
optional | The cited primary model documents this field representation. Body scope: data[]. Native JSON type: object. | vendor.tiktok-events-2.body.ad.invalid |
docs |
lead |
optional | The cited primary model documents this field representation. Body scope: data[]. Native JSON type: object. | vendor.tiktok-events-2.body.lead.invalid |
docs |
limited_data_use |
optional | The cited primary model documents this field representation. Body scope: data[]. Native JSON type: boolean. | vendor.tiktok-events-2.body.limited_data_use.invalid |
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. Body scope: data[]. 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`, `user.user_agent`, and `user.ttp` as unhashed. Body scope: data[]. Fix: Send the raw IP address, user agent, or `_ttp` cookie. | 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, ttp, or IP as the identifiers that attach the conversion to a person. Body scope: data[]. Fix: Send hashed `user.email`, `phone`, or `external_id`, or `ttclid`, `ttp`, 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. Body scope: data[]. 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 |
body.web_requires_page |
required | TikTok requires page for web events. Body scope: data[]. | vendor.tiktok-events-2.body.web_requires_page |
docs |
body.app_requires_app |
required | TikTok requires app for app events. Body scope: data[]. | vendor.tiktok-events-2.body.app_requires_app |
docs |
body.crm_requires_lead |
required | TikTok requires lead for crm events. Body scope: data[]. | vendor.tiktok-events-2.body.crm_requires_lead |
docs |
body.limited_data_use_unsupported_source |
required | TikTok does not support limited_data_use for the selected event source. Body scope: data[]. | vendor.tiktok-events-2.body.limited_data_use_unsupported_source |
docs |
body.ad_unsupported_source |
required | TikTok does not support ad for the selected event source. Body scope: data[]. | vendor.tiktok-events-2.body.ad_unsupported_source |
docs |
page.url |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.page.url.invalid |
docs |
page.referrer |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.page.referrer.invalid |
docs |
user.email |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.email.invalid |
docs |
user.phone |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.phone.invalid |
docs |
user.external_id |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.external_id.invalid |
docs |
user.ttclid |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.ttclid.invalid |
docs |
user.ttp |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.ttp.invalid |
docs |
user.ip |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.ip.invalid |
docs |
user.user_agent |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.user_agent.invalid |
docs |
user.locale |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.locale.invalid |
docs |
properties.currency |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.properties.currency.invalid |
docs |
properties.content_type |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.properties.content_type.invalid |
docs |
properties.contents[].content_id |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.properties.contents[].content_id.invalid |
docs |
properties.contents |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: array. | vendor.tiktok-events-2.body.properties.contents.invalid |
docs |
properties.contents[] |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: object. | vendor.tiktok-events-2.body.properties.contents[].invalid |
docs |
user.first_name |
optional | The official GTM mapping hashes this optional customer field before serializing it. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.first_name.emptyvendor.tiktok-events-2.body.user.first_name.invalid |
docs |
user.last_name |
optional | The official GTM mapping hashes this optional customer field before serializing it. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.last_name.emptyvendor.tiktok-events-2.body.user.last_name.invalid |
docs |
user.zip_code |
optional | The official GTM mapping hashes this optional customer field before serializing it. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.zip_code.emptyvendor.tiktok-events-2.body.user.zip_code.invalid |
docs |
user.city |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.city.invalid |
docs |
user.state |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.state.invalid |
docs |
user.country |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.user.country.invalid |
docs |
properties.contents[].content_name |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.properties.contents[].content_name.invalid |
docs |
properties.contents[].content_category |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.properties.contents[].content_category.invalid |
docs |
properties.contents[].brand |
optional | The cited primary model documents this field representation. Body scope: data[]. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.body.properties.contents[].brand.invalid |
docs |
method |
optional | The cited primary model documents this field representation. Complete HTTP capture contract. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.http.method.emptyvendor.tiktok-events-2.http.method.invalid |
docs |
content_type |
recommended | The cited primary model documents this field representation. Complete HTTP capture contract. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.http.content_type.missingvendor.tiktok-events-2.http.content_type.emptyvendor.tiktok-events-2.http.content_type.invalid |
docs |
headers.access-token |
recommended | The official Events API 2.0 curl template sends the authentication token in the Access-Token header. Token necessity is explicit; header-only requiredness is not established by the accessible reference. Complete HTTP capture contract. Presence diagnostic severity: warning. Value diagnostic severity: warning. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-2.http.headers.access-token.missingvendor.tiktok-events-2.http.headers.access-token.emptyvendor.tiktok-events-2.http.headers.access-token.invalid |
docs |
body |
required | The cited primary model documents this field representation. Complete HTTP capture contract. Native JSON type: object. | vendor.tiktok-events-2.http.body.missingvendor.tiktok-events-2.http.body.invalid |
docs |
Validate a payload
pixellint validate json @payload.json --rulepack vendor/tiktok-events-2Try 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