Pixels
Read, create and configure TikTok Pixels, manage their events, share them through Business Center and install them on Shopify or WordPress.
Manage TikTok Pixels through the platform-neutral tracking tags API on your tiktokads connection. Read, create and configure a pixel, manage its events and counts, share it, and install it.
Before you start
A connection authorized before TikTok's Pixel Management permission answers every pixel call with 403. Reconnect TikTok Ads to grant it.
Read the tag
GET /v1/accounts/{accountId}/tracking-tags lists the pixels of every advertiser on the connection. GET .../tracking-tags/{tagId} reads one, with its install code and its events.
const { data } = await zernio.trackingtags.getTrackingTag({
path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d', tagId: '7412345678901234567' }
});Response (200), trimmed:
{
"platform": "tiktokads",
"tag": {
"id": "7412345678901234567",
"siteTagId": "D00IKHRC77UE0J0RTNHG",
"name": "Storefront pixel",
"platform": "tiktokads",
"kind": "pixel",
"status": "active",
"ownerAdAccountId": "7301234567890123456",
"code": "<script>!function (w, d, t) {...}</script>",
"events": [
{ "id": "e1", "name": "Purchase", "type": "SHOPPING", "siteEvent": "purchase", "siteEventId": "Purchase", "status": "active" }
]
}
}| Field | Value |
|---|---|
id | The numeric pixel_id: what promotedObject.pixelId takes on conversion campaigns |
siteTagId | The alphanumeric pixel_code that ttq.load() and Events Manager use |
events | TikTok's type, the matching siteEvent, and siteEventId, the name ttq.track() fires |
adAccountId, the advertiser id, is optional on per-pixel calls. Without it, Zernio searches every advertiser on the connection, and a pixel shared into several advertisers resolves to its owner's copy.
Create a pixel
POST /v1/accounts/{accountId}/tracking-tags creates a pixel on one advertiser. Names are at most 40 characters, with no emojis.
const { data } = await zernio.trackingtags.createTrackingTag({
path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d' },
body: { adAccountId: '7301234567890123456', name: 'Storefront pixel' }
});Response (201):
{
"platform": "tiktokads",
"tag": {
"id": "7412345678901234567",
"siteTagId": "D00IKHRC77UE0J0RTNHG",
"name": "Storefront pixel",
"platform": "tiktokads",
"kind": "pixel",
"status": "active",
"creationTime": 1804064400,
"ownerAdAccountId": "7301234567890123456",
"code": "<script>!function (w, d, t) {...}</script>",
"events": []
}
}The create is not idempotent and TikTok has no pixel delete, so never retry it blindly. List the pixels after a timeout.
Creating an event is not idempotent either. TikTok returns no id for it, and refreshes a pixel's event list only every few hours.
When the new event is not listed yet, the response carries id: "" and status: "pending". Read the events again later for its id.
Pixel operations
| Operation | Behavior |
|---|---|
Update (PATCH .../tracking-tags/{tagId}) | name, enableAutomaticMatching, automaticMatchingFields (Meta's codes folded onto TikTok's email, phone, name, address and external id switches; gender and date of birth answer 400), and first-party cookies as enableFirstPartyCookies (boolean) or firstPartyCookieStatus. Other fields answer 400. |
Stats (GET .../stats) | Per-event counts from TikTok's /pixel/event/stats, 7 days by default and at most 30 per request, bucketed by whole UTC days. TikTok reports no last-fired time. |
Share (.../shared-accounts) | Business Center pixel links: list, link and unlink advertisers. The pixel must be an asset of a Business Center the connection manages (its owner Business Center, or one of the connection's). sharedAccounts[].businessId is the Business Center. |
Conversion events (.../events) | List, create and update the pixel's events. Create takes type (TikTok's event type) or siteEvent, plus optional name, defaultValue and currency (USD, JPY or INR). Update changes name, defaultValue and currency only: TikTok cannot change an event's type, so create a new event instead. |
| Diagnostics | 501: TikTok has no pixel diagnostics endpoint (/pixel/diagnostic/, /pixel/diagnostics/ and /pixel/health/ answer 404). Use the stats or Events Manager. |
| Users and partners | 501. |
| Delete | Not offered: TikTok has no pixel delete endpoint (/pixel/delete/ answers 404, and it is not in TikTok's SDK specs). |
| Install | Shopify and WordPress. WordPress gets TikTok's base code (ttq.load plus ttq.page); Shopify sends each storefront event to analytics.tiktok.com/api/v2/pixel, the endpoint TikTok's own pixel script calls (undocumented), with the ttclid click id kept first-party, the _ttp browser id reused and an event id for dedup with the Events API. |
Install targets: a connected Shopify store or WordPress site.
If it fails
| Error | Cause | Fix |
|---|---|---|
403 on every pixel call | The connection predates TikTok's Pixel Management permission | Reconnect TikTok Ads to grant it. |
400 on a share | The pixel is not an asset of a Business Center the connection manages | Transfer it into Business Center (Assets, Events), then retry. |
400 on an update | A field TikTok does not store, or gender and date of birth in automaticMatchingFields | Send only the fields in the update row above. |
501 platform_not_supported on an event DELETE | TikTok's delete call reports success without removing the event | Delete the event in TikTok Events Manager. |
| A second pixel after a retry | The create is not idempotent | List the pixels after a timeout instead of retrying. |
Related
- Pixels and tracking tags: the tag API across platforms.
- Create a campaign: the conversion campaign that uses the pixel id.
- Shopify tracking pixels: the storefront install.
- Offline conversions: events the pixel cannot see.