X Pixel
Read and create the X Pixel, manage its conversion events, check they are tracking and install it on Shopify or WordPress.
The X Pixel is the ad account's universal website tag, managed through the platform-neutral tracking tags API on your xads account. X allows one per ad account.
Read the tag
GET /v1/accounts/{accountId}/tracking-tags/{tagId} returns the pixel, its base code and its conversion events. tagId is the X ad account id.
| Field | Value |
|---|---|
tagId | The X ad account id (for example 18ce54d4x5t) |
siteTagId | The pixel id (the universal website tag's id), what twq('config') loads |
events | The account's conversion events (web event tags), without the ones X auto-creates with the pixel |
Each event has type (PURCHASE, ADD_TO_CART, ...), status, clickWindowDays, viewWindowDays and siteEventId. siteEventId is tw-<pixel>-<event>, the id twq('event') and the Conversions API send.
const { data } = await zernio.trackingtags.getTrackingTag({
path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d', tagId: '18ce54d4x5t' }
});Response (200):
{
"platform": "xads",
"tag": {
"id": "18ce54d4x5t",
"siteTagId": "o8z1q",
"name": "X Pixel o8z1q",
"platform": "xads",
"kind": "pixel",
"status": "active",
"code": "<!-- X conversion tracking base code -->\n<script>...twq('config','o8z1q');</script>",
"lastFiredTime": 1804150800,
"installed": true,
"ownerAdAccountId": "18ce54d4x5t",
"events": [
{ "id": "14cgjq", "siteEventId": "tw-o8z1q-rg1cq", "name": "Purchase", "type": "PURCHASE", "status": "TRACKING", "siteEvent": "purchase", "clickWindowDays": 30, "viewWindowDays": 1 }
]
}
}status is active when any of the account's web event tags is TRACKING. lastFiredTime is the most recent last_tracked_at across them.
Pixel operations
| Operation | Behavior |
|---|---|
| List | One pixel per ad account on the connection; adAccountId scopes it to one. |
Stats (GET .../stats) | One row per web event tag with eventId, name, type, autoCreated, status and lastTrackedTime. |
Create (POST .../tracking-tags) | Creates the ad account's pixel (adAccountId = the X ad account id) with first-party cookies on. name is not stored, since X pixels have no name. |
Update (PATCH .../tracking-tags/{tagId}) | firstPartyCookieStatus only: first_party_cookie_enabled or first_party_cookie_disabled (the pixel's allow_1p_cookie). |
| Share | 501: an X Pixel belongs to exactly one ad account, and X has no share endpoint. |
| Diagnostics, users and partners | 501. |
| Delete | Not offered: DELETE on a website tag answers 405 at X. |
X exposes no per-pixel or per-event counts, only WEB_CONVERSION metrics on each ad.
Conversion events
.../tracking-tags/{tagId}/events lists, creates, updates and deletes the conversion events.
| Field | Values |
|---|---|
name | The event's name |
type or siteEvent | X's event type, such as PURCHASE, SIGN_UP or CUSTOM, or the site event it maps from |
clickWindowDays | 1, 7, 14, 30, 60 or 90 |
viewWindowDays | 0, 1, 7, 14, 30, 60 or 90, no longer than the click window when both are sent |
A create defaults to 30 and 1 days with retargeting on, as Events Manager does, and is not idempotent. Delete is permanent.
Install on a site
POST .../tracking-tags/{tagId}/install puts the pixel on a connected Shopify store or WordPress site.
WordPress gets X's uwt.js base code, whose twq('config') is the page view.
Shopify sends the page view and each event that has a matching conversion event to analytics.twitter.com/1/i/adsct. When several match a type, the most recently tracked one wins.
Shopify events use uwt.js's own request shape, which is reverse-engineered: X documents only the legacy image pixel. conversion_id is the event id, so X deduplicates against the Conversions API, and the twclid click id stays first-party.
If it fails
| Error | Cause | Fix |
|---|---|---|
400 on a per-tag call | The ad account has no pixel | Create one with POST .../tracking-tags. |
409 on a create | The ad account already has a pixel; X allows one and cannot delete it | Read the existing pixel instead. |
400 on an event update or delete | The event is one X auto-created with the pixel | Leave it; create your own event instead. |
501 with code platform_not_supported | Share, diagnostics, users or partners | The message names the alternative. |
Related
- Pixels and tracking tags: the pixel API across platforms.
- Get tracking tag and Get tracking tag stats.
- Create tracking tag event: every field of an event.
- Shopify tracking pixels: what the Shopify pixel sends.
- Read ad analytics: per-ad
WEB_CONVERSIONmetrics.