pixellint

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

Hosts
business-api.tiktok.com
Paths
Full path expression: /open_api/v1\.3/pixel/(?:track|batch)/?, Full path expression: /open_api/v1\.2/pixel/track/?
Vendor docs
ads.tiktok.com/marketing_api/docs?id=1739584855420929

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.missing
vendor.tiktok-events-api.body.pixel_code.empty
vendor.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.missing
vendor.tiktok-events-api.body.event.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.missing
vendor.tiktok-events-api.http.content_type.empty
vendor.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.missing
vendor.tiktok-events-api.http.headers.access-token.empty
vendor.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.missing
vendor.tiktok-events-api.http.body_encoding.empty
vendor.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