Server-side events · Platform reference
X Conversion API checker
X's Conversion API posts web conversions to an X Pixel (event source) ID. Each conversion names an Events Manager event_id and carries identifiers such as twclid, hashed email or hashed phone. When the X Pixel sends the same conversion, it needs a shared conversion_id. Conversions most often fail to attribute because there is no usable identifier (twclid wasn't captured, or only IP/user agent was sent), the event_id belongs to a different pixel, or Pixel and API used different conversion_id values.
Read from the official documentation on 9 November 2026. Sources are listed at the end.
Check your own setup
twclid rides on your landing URL. Paste the curl -sIL output of your ad's tracking link into our redirect chain checker and it shows whether twclid survives every hop, because a stripped twclid is a common reason server conversions don't match. It doesn't validate the X Conversion API JSON, the event_id-to-pixel mapping or the hashing. Our CAPI event checker reads Meta payloads only.
Open the Redirect Chain CheckerEndpoint and authentication
POST https://ads-api.x.com/12/measurement/conversions/{pixel_id}
X Ads API user access token for a handle with AD_MANAGER or ACCOUNT_ADMIN access (3-legged OAuth for other handles). The server-side GTM tag instead sends a Conversion API token generated in Events Manager in the X-Pixel-Token header
Conversion types
The API doesn't take an event name: each conversion carries the Event ID of a conversion event you create in Events Manager. X's server-side GTM guide lists these common conversions, with the GA4 event name that maps to each.
| Name | What it is |
|---|---|
| Purchase | GA4 event name: purchase |
| Add to cart | GA4 event name: add_to_cart |
| Begin checkout | GA4 event name: begin_checkout |
| Lead | GA4 event name: generate_lead |
| Sign up | GA4 event name: sign_up |
| Search | GA4 event name: search |
| View content | GA4 event name: view_item |
| Add payment info | GA4 event name: add_payment_info |
| Page view | GA4 event name: page_view |
Required and recommended fields
| Field | What it needs |
|---|---|
| conversions[] | Array of conversion objects |
| conversion_time | ISO 8601 UTC timestamp, e.g. 2022-02-18T01:14:00.603Z |
| event_id | The Events Manager Event ID for the conversion type (it identifies the type, not the occurrence). It must belong to the pixel in the URL |
| identifiers[] | At least one of twclid, hashed_email or hashed_phone_number. ip_address and user_agent count only alongside another identifier |
| conversion_id | Per-occurrence dedup key (order ID or UUID), the same value the Pixel sends |
| value / price_currency / number_items / contents[] | Optional commerce fields. contents items take content_id, content_name, content_type, content_price, num_items, content_group_id |
Match keys and hashing
| Key | Normalise and hash |
|---|---|
| hashed_email | SHA-256 with no salt. X's server-side GTM guide says to trim whitespace and lowercase before hashing (the X tag does both for plain values) |
| hashed_phone_number | Normalise to E.164, then SHA-256 with no salt |
| ip_address | Dotted-decimal, not hashed. Can't be the only identifier |
| user_agent | Trim leading and trailing spaces, not hashed. Can't be the only identifier |
Click ids
| Click id | Where it comes from |
|---|---|
| twclid | X adds twclid to the landing URL after an ad click. Parse it from the query string and send it unhashed in identifiers. The server-side GTM tag stores it in a first-party _twclid cookie, which lasts about 390 days |
| _twpid | First-party cookie usually set by the X Pixel. The server-side GTM tag reads it. Not hashed |
Deduplication
- When the Pixel and the Conversion API report the same conversion, send the same conversion_id in both. It is the dedup key.
- Also send the same Events Manager event_id on both. The event_id identifies the conversion type and the conversion_id identifies one occurrence.
- No dedup is needed when the Pixel and the API send different events.
Time limits and batch sizes
- Rate limit: 60,000 events per ad account per 15-minute interval.
- conversion_time is ISO 8601 UTC.
How to test before you trust it
- Events Manager: Send a test conversion and confirm it appears under the event in Events Manager after a short delay
- GTM Preview (server container): For server-side GTM: run Preview on the web and server containers, trigger a test conversion, and check that the X tag fired and its POST to /12/measurement/conversions/{pixel_id} returned 2xx
- API response: A successful call returns 200 with conversions_processed and a debug_id
Why events arrive but don't attribute
- Only IP address and user agent with no twclid, email or phone isn't enough. X needs at least one real identifier.
- twclid gets lost when redirects or link shorteners strip query parameters, or when the first-party cookie is blocked. The API call then has nothing click-level to match.
- An event_id that belongs to a different pixel than the one in the URL path is rejected, so the conversion never lands on the right event.
- Pixel and API sending different conversion_id values (or none) for the same order means double counting instead of dedup.
- Phone numbers that aren't E.164 before hashing produce hashes that never match. The GTM tag doesn't reformat phone numbers for you.
- If the GTM tag gets no Event ID and no event name, it drops the conversion. It only falls back to gtm_{event_name} when a name exists.
- Users who opted out of tracking or sale of personal information should be filtered out before sending.
Sources
- X Developer Platform: Conversion API for Web (web conversions)
- X Developer Platform: Set up the Conversion API with Google Tag Manager (server-side)
Platforms change these rules without notice. If a source says something different from this page, the source wins.