TikTok legacy conversions check track and batch requests.
Legacy TikTok pixel track and batch profiles gain captured transport and route-specific envelope advice. Current official SDK v1.3 routes and the published v1.2 track profile are scoped separately from Events API 2.0.
The published legacy track and batch routes receive transport and envelope advice. Current Events API routes have a separate pack. Missing capture evidence remains unknown.
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 |
|---|---|---|---|---|
pixel_code |
required | It is the Pixel ID from Events Manager. TikTok documents it as required on both the single-event track call and the batch call. Native JSON type: string. Fix: Set `pixel_code` to the Pixel ID shown in Events Manager. | vendor.tiktok-events-api.body.pixel_code.missingvendor.tiktok-events-api.body.pixel_code.emptyvendor.tiktok-events-api.body.pixel_code.invalid |
docs |
batch |
optional | The batch endpoint posts events under `batch`. The track endpoint posts a single event at the root instead. Evidence: vendor template. Native JSON type: array. Minimum array items: 1. | vendor.tiktok-events-api.body.batch.invalid |
docs |
root |
optional | Each event is a JSON object, rather than a scalar or list. Native JSON type: object. | vendor.tiktok-events-api.body.root.invalid |
docs |
batch[] |
optional | The vendor documents the JSON shape or value type of this field. Evidence: vendor template. Native JSON type: object. | vendor.tiktok-events-api.body.batch[].invalid |
docs |
event |
required | It is the conversion event name. TikTok documents it as required on every track payload. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Set `event` to a documented web event name, such as `CompletePayment` or `ViewContent`. | vendor.tiktok-events-api.body.event.missingvendor.tiktok-events-api.body.event.emptyvendor.tiktok-events-api.body.event.invalid |
docs |
event_id |
optional | It identifies the event for deduplication against the browser pixel. TikTok documents it as required when the same conversion is sent from both. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Send the same `event_id` the Pixel fired, so the pair collapses to one conversion. | vendor.tiktok-events-api.body.event_id.emptyvendor.tiktok-events-api.body.event_id.invalid |
docs |
timestamp |
optional | TikTok documents the event time as an ISO 8601 timestamp. An epoch number is not that format, and TikTok then stamps the event with the time it arrived. Body scope: ["batch[]",""]. Fix: Send an ISO 8601 timestamp, such as `2026-07-26T06:00:00Z`. | vendor.tiktok-events-api.body.timestamp.emptyvendor.tiktok-events-api.body.timestamp.invalid |
docs |
context.ip |
optional | It is the visitor's public IP address, sent unhashed. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Send the browser's public IP, not a SHA-256 digest and not your server's address. | vendor.tiktok-events-api.body.context.ip.emptyvendor.tiktok-events-api.body.context.ip.invalid |
docs |
context.user_agent |
optional | It is the visitor's user agent, sent unhashed. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Send the browser's user agent string, not a digest. | vendor.tiktok-events-api.body.context.user_agent.emptyvendor.tiktok-events-api.body.context.user_agent.invalid |
docs |
context.ad.callback |
optional | It is the TikTok Click ID (`ttclid`) from the landing URL. TikTok documents it as unhashed on `context.ad.callback`. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Copy `ttclid` from the landing URL into `context.ad.callback`, or drop the empty pair. | vendor.tiktok-events-api.body.context.ad.callback.emptyvendor.tiktok-events-api.body.context.ad.callback.invalid |
docs |
context.page.url |
optional | It is the page URL when the event happened. TikTok documents it on `context.page`. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Send an absolute URL in `context.page.url`, including the scheme. | vendor.tiktok-events-api.body.context.page.url.emptyvendor.tiktok-events-api.body.context.page.url.invalid |
docs |
context.page.referrer |
optional | It is the page referrer. TikTok documents it on `context.page`. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Send an absolute referrer URL, or drop the empty pair. | vendor.tiktok-events-api.body.context.page.referrer.emptyvendor.tiktok-events-api.body.context.page.referrer.invalid |
docs |
context.user.email |
optional | Email must be SHA-256 hashed on the client side before it is sent. Body scope: ["batch[]",""]. Fix: Trim and lowercase the address, hash it with SHA-256, and send the hex digest. | vendor.tiktok-events-api.body.context.user.email.emptyvendor.tiktok-events-api.body.context.user.email.invalid |
docs |
context.user.phone_number |
optional | Phone must be SHA-256 hashed on the client side before it is sent. Body scope: ["batch[]",""]. Fix: Normalize the number, hash it with SHA-256, and send the hex digest. | vendor.tiktok-events-api.body.context.user.phone_number.emptyvendor.tiktok-events-api.body.context.user.phone_number.invalid |
docs |
context.user.external_id |
optional | Advertiser-side identifiers must be SHA-256 hashed on the client side. Body scope: ["batch[]",""]. Fix: Hash the identifier with SHA-256 and send the hex digest. | vendor.tiktok-events-api.body.context.user.external_id.emptyvendor.tiktok-events-api.body.context.user.external_id.invalid |
docs |
context.user.ttp |
optional | It is the first-party `_ttp` cookie. TikTok documents it as unhashed on `context.user.ttp`. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Read `_ttp` under your domain into `context.user.ttp`, or drop the empty pair. | vendor.tiktok-events-api.body.context.user.ttp.emptyvendor.tiktok-events-api.body.context.user.ttp.invalid |
docs |
properties.currency |
optional | TikTok's Events API SDK lists the currencies it currently supports. A three-letter code outside that list warns. The list can grow. Body scope: ["batch[]",""]. Value diagnostic severity: warning. Fix: Use a code from the current TikTok list, such as `USD`. | vendor.tiktok-events-api.body.properties.currency.emptyvendor.tiktok-events-api.body.properties.currency.invalid |
docs |
properties.value |
optional | It is the total value of the order or items, not the unit price. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: number. | vendor.tiktok-events-api.body.properties.value.invalid |
docs |
properties.contents[].content_id |
optional | It is the product item ID on a contents row. TikTok's Events API SDK documents `content_id` on each `PixelContent` object, not on `properties`. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Set `properties.contents[].content_id` to the catalog item ID, or drop the empty pair. | vendor.tiktok-events-api.body.properties.contents[].content_id.emptyvendor.tiktok-events-api.body.properties.contents[].content_id.invalid |
docs |
properties.contents[].content_type |
optional | It is how the row maps to the catalog. TikTok's Events API SDK documents `product` or `product_group` on each contents object. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Set `properties.contents[].content_type` to `product` or `product_group`. Do not put `content_type` on `properties`. | vendor.tiktok-events-api.body.properties.contents[].content_type.emptyvendor.tiktok-events-api.body.properties.contents[].content_type.invalid |
docs |
properties.contents[].quantity |
optional | It is the item count on a contents row. TikTok's Events API SDK documents `quantity` as a number. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: integer. Fix: Send `properties.contents[].quantity` as a number, such as `2`. | vendor.tiktok-events-api.body.properties.contents[].quantity.emptyvendor.tiktok-events-api.body.properties.contents[].quantity.invalid |
docs |
properties.contents[].price |
optional | It is the unit price of one item. TikTok's Events API SDK documents `price` as the single-item price, not the order total. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: number. Fix: Send `properties.contents[].price` as a number, such as `10`. Put the order total in `properties.value`. | vendor.tiktok-events-api.body.properties.contents[].price.invalid |
docs |
properties.contents[].content_name |
optional | It is the name of the page or product on a contents row. TikTok's Events API SDK documents `content_name` on each `PixelContent` object. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Set `properties.contents[].content_name` to the page or product name, or drop the empty pair. | vendor.tiktok-events-api.body.properties.contents[].content_name.emptyvendor.tiktok-events-api.body.properties.contents[].content_name.invalid |
docs |
properties.contents[].content_category |
optional | It is the category of the page or product on a contents row. TikTok's Events API SDK documents `content_category` on each `PixelContent` object. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Set `properties.contents[].content_category` to the category, or drop the empty pair. | vendor.tiktok-events-api.body.properties.contents[].content_category.emptyvendor.tiktok-events-api.body.properties.contents[].content_category.invalid |
docs |
properties.contents[].status |
optional | It is the status of an order, item, or service on a contents row. TikTok's Events API SDK documents `status` as a string with no enumerated values. Body scope: ["batch[]",""]. Native JSON type: string. Fix: Set `properties.contents[].status` to the order or item status, or drop the empty pair. | vendor.tiktok-events-api.body.properties.contents[].status.emptyvendor.tiktok-events-api.body.properties.contents[].status.invalid |
docs |
root |
optional | Each event is a JSON object, rather than a scalar or list. Body scope: ["batch[]",""]. Native JSON type: object. | vendor.tiktok-events-api.body.root.invalid |
docs |
context |
optional | The vendor documents the JSON shape or value type of this field. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: object. | vendor.tiktok-events-api.body.context.invalid |
docs |
context.user |
optional | The vendor documents the JSON shape or value type of this field. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: object. | vendor.tiktok-events-api.body.context.user.invalid |
docs |
context.page |
optional | The vendor documents the JSON shape or value type of this field. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: object. | vendor.tiktok-events-api.body.context.page.invalid |
docs |
context.ad |
optional | The vendor documents the JSON shape or value type of this field. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: object. | vendor.tiktok-events-api.body.context.ad.invalid |
docs |
properties |
optional | The vendor documents the JSON shape or value type of this field. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: object. | vendor.tiktok-events-api.body.properties.invalid |
docs |
properties.contents |
optional | The vendor documents the JSON shape or value type of this field. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: array. | vendor.tiktok-events-api.body.properties.contents.invalid |
docs |
properties.contents[] |
optional | The vendor documents the JSON shape or value type of this field. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: object. | vendor.tiktok-events-api.body.properties.contents[].invalid |
docs |
properties.description |
optional | The vendor documents the JSON shape or value type of this field. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-api.body.properties.description.invalid |
docs |
properties.query |
optional | The vendor documents the JSON shape or value type of this field. Body scope: ["batch[]",""]. Evidence: vendor template. Native JSON type: string. | vendor.tiktok-events-api.body.properties.query.invalid |
docs |
body.unhashed_email |
required | A field carries what looks like a raw email address. TikTok requires customer email to be SHA-256 hashed on the client side. Body scope: ["batch[]",""]. Fix: Trim the address, lowercase it, hash it with SHA-256, and send the hex digest. | vendor.tiktok-events-api.body.unhashed_email |
docs |
body.hashed_plaintext_field |
required | This field looks like a SHA-256 digest, but TikTok documents `context.ip`, `context.user_agent`, `context.ad.callback`, and `context.user.ttp` as unhashed. Body scope: ["batch[]",""]. Fix: Send the raw IP address, user agent, click ID, or `_ttp` cookie. Hashing it makes the event unmatchable. | vendor.tiktok-events-api.body.hashed_plaintext_field |
docs |
body.user_needs_an_identifier |
recommended | The event has no user identifier. TikTok documents hashed email, phone, external_id, the `_ttp` cookie, click ID, or IP as the match keys that attach the conversion to a person. Body scope: ["batch[]",""]. Fix: Send hashed `context.user.email`, `phone_number`, or `external_id`, or unhashed `context.user.ttp`, `context.ad.callback`, or `context.ip`. | vendor.tiktok-events-api.body.user_needs_an_identifier |
docs |
body.complete_payment_requires_value_and_currency |
required | A `CompletePayment` or `PlaceAnOrder` event is missing `properties.value` or `properties.currency`. TikTok documents both on those revenue events. Body scope: ["batch[]",""]. Fix: Set `properties.value` to the order total and `properties.currency` to a three-letter ISO 4217 code. | vendor.tiktok-events-api.body.complete_payment_requires_value_and_currency |
docs |
method |
optional | The pinned official EventCallback sender uses POST. Other methods receive producer-profile advice rather than a universal receiver rejection claim. Complete HTTP capture contract. Presence diagnostic severity: warning. Native JSON type: string. | vendor.tiktok-events-api.http.method.emptyvendor.tiktok-events-api.http.method.invalid |
docs |
content_type |
recommended | The pinned sender selects application/json; MIME parameters are normalized by the capture layer. Complete HTTP capture contract. Presence diagnostic severity: warning. Native JSON type: string. | vendor.tiktok-events-api.http.content_type.missingvendor.tiktok-events-api.http.content_type.emptyvendor.tiktok-events-api.http.content_type.invalid |
docs |
headers.access-token |
recommended | The actual SDK writes its required access_token parameter into Access-Token. The generated No authorization required section describes Swagger auth settings, not the absence of this custom token header. Complete HTTP capture contract. Presence diagnostic severity: warning. Native JSON type: string. | vendor.tiktok-events-api.http.headers.access-token.missingvendor.tiktok-events-api.http.headers.access-token.emptyvendor.tiktok-events-api.http.headers.access-token.invalid |
docs |
body_encoding |
recommended | The producer normally sends a JSON entity. Its optional body argument can emit no body, so absence is advice. Opaque encodings remain unverified. Complete HTTP capture contract. Applies when {"kind":"all","conditions":[{"kind":"not","condition":{"kind":"value_in","param":"body_encoding","values":["unsupported"]}},{"kind":"any","conditions":[{"kind":"value_in","param":"body_encoding","values":["none"]},{"kind":"value_in","param":"content_type","values":["application/json"]}]}]}. Presence diagnostic severity: warning. | vendor.tiktok-events-api.http.body_encoding.missingvendor.tiktok-events-api.http.body_encoding.emptyvendor.tiktok-events-api.http.body_encoding.invalid |
docs |
path |
optional | Captured normalized path supplies the track-versus-batch discriminator. Complete HTTP capture contract. Native JSON type: string. | vendor.tiktok-events-api.http.path.invalid |
docs |
body |
optional | Parsed capture body supplies scope only; existing body contracts retain native type errors. Complete HTTP capture contract. | docs | |
body.batch |
recommended | The batch model requires a batch member. Advice applies only to captured batch-route objects; existing array type and length checks retain ownership of supplied values. Complete HTTP capture contract. Applies when {"kind":"all","conditions":[{"kind":"value_pattern","param":"path","pattern":"^/open_api/v1\\.3/pixel/batch/?$"},{"kind":"json_type","param":"body","json_type":"object"}]}. Presence diagnostic severity: warning. | vendor.tiktok-events-api.http.body.batch.missing |
docs |
body.event |
recommended | The single-track model requires the root event member. A batch object does not establish a valid single-track envelope. Complete HTTP capture contract. Applies when {"kind":"all","conditions":[{"kind":"value_pattern","param":"path","pattern":"^/open_api/v1\\.(?:2|3)/pixel/track/?$"},{"kind":"json_type","param":"body","json_type":"object"}]}. Presence diagnostic severity: warning. | vendor.tiktok-events-api.http.body.event.missing |
docs |
Validate a payload
pixellint validate request @request.json --rulepack vendor/tiktok-events-api
Try this failing payload in the playground. An example with a validation finding.
{
"url": "https://business-api.tiktok.com/open_api/v1.3/pixel/track/",
"method": "GET",
"headers": {
"Content-Type": "application/json",
"Access-Token": "synthetic-token"
},
"body": "{\"pixel_code\":\"synthetic-pixel\",\"event\":\"ViewContent\",\"context\":{\"user\":{\"email\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}}}"
}
cargo install pixellint
·
npm install pixellint