Add TikTok

TikTok setup is a pixel code and an Events API access token. The important part is not the setup — it is that TikTok wants the same customer data as Meta in a different shape, and sending Meta’s version to TikTok silently matches nobody. PixelCapi normalises per platform rather than once, so you do not have to think about it.

The hashing differences that matter

Phone numbers. Both platforms want an E.164 number, but they disagree about the plus sign. Meta wants it stripped; TikTok wants it kept. The same Romanian mobile becomes:

Meta    sha256("40722123456")
TikTok  sha256("+40722123456")

A single normalisation sent to both is wrong for at least one of them. PixelCapi derives the country code from the order’s billing country, and if a number is in national format with no determinable country, it is omitted rather than guessed. A wrong hash is worse than a missing field: it matches nobody and tells you nothing.

Case folding. Names and cities are lowercased with a multibyte-aware function. Both platforms are affected by this identically, because they share the same event builder — which is also why getting it wrong once broke both at the same time. See Match quality dropped.

Event names

TikTok renamed several standard events. PixelCapi sends the current names — Purchase and Lead — rather than the Events API 1.0 names CompletePayment and SubmitForm.

If you have historical data under the old names, nothing is lost: TikTok auto-converts legacy names on its side and shows the updated names in reporting, audience creation and optimisation, and has said the old names will be supported indefinitely.

Batching

Events are sent in chunks of 500. TikTok rejects an entire request if it carries more than 1000 events, so the request size is deliberately decoupled from the internal queue’s batch size — raising one cannot push the other over that cliff. If TikTok rejects a batch as a whole, the plugin bisects it and retries, which isolates the one bad row in a handful of extra requests instead of failing every row until they burn their retry budget.

What is verified live, and what is not

The error and authentication paths are verified against TikTok’s live API. When credentials are wrong or a request is rejected, the response the plugin receives — and the way it reports that back to you — have been checked against the real service, not against a mock.

The successful-delivery path has not been live-verified yet. Request bodies are real output from the plugin and match TikTok’s published specification, but a real accepted event has not yet been observed arriving. In practice that means: if your TikTok setup is broken, you will be told so correctly. If it is working, that is expected rather than confirmed.

That is an unusual distinction for documentation to draw. It is here because the alternative is you finding out on your own campaign.

Next

• Verify your first event
• Duplicate events