Set up the Conversion API with Google Tag Manager

Use the official X Ads Conversion API tag in a Google Tag Manager (GTM) server container to send website conversion events to X. The tag reads events that reach your tagging server and forwards them to the X Ads Conversion API. You do not need to write request code. Sharing server-side conversions with X helps you:

Measure ad performance when browser-based tracking is limited
Optimize campaign delivery
Deduplicate the same conversion when you also use the X Pixel

The official template is X Ads Conversion API (Official) and is published in the Google Tag Manager Community Template Gallery. It can be added only to a Server container.

This guide is for advertisers using Google Tag Manager. If you are building a custom server integration, use the Web conversions API reference instead.

How the integration works

A typical setup uses both a web container and a server container:

The web container (or gtag.js) sends events from the browser to your tagging server. Most advertisers use a Google Analytics 4 (GA4) configuration tag for this.
The GA4 Client in the server container receives those events.
The X Ads Conversion API (Official) tag fires on those events and POSTs them to https://ads-api.x.com/12/measurement/conversions/{pixel_id} with your Pixel access token.

Website  →  GTM web container / gtag.js  →  Your tagging server  →  X Conversion API
                 (optional X Pixel)              (GA4 Client + X CAPI tag)

We recommend running the X Pixel and the Conversion API for the same events (a redundant setup), then sending a shared Conversion ID so X can deduplicate.

Prerequisites

Before you start, you need:

Requirement	Details
X Ads account	Access to Ads Manager with permission to manage Events Manager
X Pixel (event source)	An Event Source in Events Manager. The Event Source ID is your Pixel ID
Conversion API access token	Generated in Events Manager for Conversion API access
Conversion events	Existing Pixel events, or new events created with Install with Conversion API
GTM web container	Installed on your website. See Set up and install Tag Manager
GTM server container	A tagging server URL. See Server-side tagging
Event stream into the server	Usually GA4 Configuration plus GA4 Event tags, or `gtag.js` with `server_container_url`

Recommended: Map a first-party custom domain to your tagging server. First-party serving improves cookie durability for the X Click ID (twclid) and other identifiers.

Step 1: Collect your Pixel ID, Event IDs, and access token

Pixel ID

Go to ads.x.com.
Open Tools → Events Manager.
If you do not already have an X Pixel event source, select Add event source and add one.
Copy the Pixel ID from the event source. You will paste this into the GTM tag.

Conversion events (Event IDs)

Each conversion you want to optimize or report on should exist in Events Manager. Option A — Reuse an existing Pixel event (recommended for Pixel + Conversion API) If the event is already firing from the X Pixel, copy that event’s Event ID. Using the same Event ID on both the Pixel and the Conversion API is required for deduplication. Option B — Create a Conversion API event

Open the X Pixel event source.
Select Add events.
Choose Install with Conversion API.
Copy the Pixel ID and Event ID, then save.

Event ID in Events Manager is the conversion type (for example a Purchase event). It is not the per-occurrence deduplication key. The per-occurrence key is Conversion ID. See Deduplication.

Access token

The official GTM tag authenticates with the X-Pixel-Token header. Generate a Conversion API access token in Events Manager:

In Events Manager, open Install Pixel.
Select Manual as the installation method, then continue.
Select Conversion API, then continue.
Select Generate access token and copy the token.

Store the token in a GTM variable (Constant, or a secret manager your tagging server supports). Do not hard-code it in multiple tags or commit it to source control.

The GTM template uses this Pixel access token. You do not need to implement OAuth 1.0a or call the Ads API from GTM. OAuth credentials are only required for custom Conversion API integrations.

Step 2: Create a GTM server container

If you already have a server container and tagging server URL, skip to Step 3.

Open Google Tag Manager.
Select your account, then Create Container.
Name the container and set the target platform to Server.
Create the container and provision a tagging server. Google Cloud is the default path; other clouds use the manual server setup.
Copy the tagging server URL (for example https://sgtm.example.com).

Server containers include a GA4 Client by default. Keep it enabled. It listens for GA4 requests (typically on /g/collect) and turns them into events the X tag can read.

Step 3: Send website events to the server container

Configure the web container so conversion events reach the server.

GA4 Configuration tag

In the web container, open your Google Analytics: GA4 Configuration tag (or create one):

If the tag supports Send to server container, enable it and set Server Container URL to your tagging server URL.
Otherwise, under Fields to Set, add:
- Field name: transport_url
- Field value: your tagging server URL

To pass hashed user data into server-side GTM, also set:

Field name: first_party_collection
Field value: true

If this GA4 Configuration tag currently sends production traffic to Google Analytics, adding a server URL starts sending that traffic to the server container. To keep sending events to GA4 as well, add a GA4 tag in the server container that fires on the same events.

GA4 Event tags

For each conversion (Purchase, Lead, Sign up, and so on), add or update a Google Analytics: GA4 Event tag:

Set Event Name to a stable value (purchase, generate_lead, sign_up, and so on).
Under Event Parameters, map value, currency, items, and user data. See Event parameter mapping.
If you use both Pixel and Conversion API, add event_id and set it to a unique per-conversion value. The official X tag uses this as Conversion ID unless you override it.

Example gtag.js event:

gtag('event', 'purchase', {
  event_id: generateConversionId(), // unique per conversion; used for deduplication
  transaction_id: 't_12345',
  currency: 'USD',
  value: 19.99,
  user_data: {
    email_address: userEmail,      // plain or SHA-256; the X tag hashes plain values
    phone_number: userPhoneE164    // E.164 format recommended, e.g. +11234567890
  },
  items: [
    {
      item_id: 'sku-1',
      item_name: 'Blue sneakers',
      price: 19.99,
      quantity: 1
    }
  ]
});

You can keep using your existing GA4 event names. If you leave the X tag’s Event ID empty, the template sends event_name as gtm_ plus the incoming name, lowercased (for example purchase → gtm_purchase). For Pixel + Conversion API deduplication, set Event ID to the Events Manager Event ID instead.

Step 4: Install the official X tag in the server container

Open your server container.
Go to Templates.
Under Tag Templates, select Search Gallery.
Search for X Ads Conversion API (Official) and add it to the workspace.

Use X Ads Conversion API (Official). Community templates with similar names (for example third-party “X (Twitter) Conversion API” tags) are not this integration and may require different authentication.

Step 5: Create and configure the Conversion API tag

In the server container, go to Tags → New.
Choose X Ads Conversion API (Official) as the tag type.

Required configuration

Field	Required	What to enter
Pixel ID	Yes	Pixel ID from Events Manager
Access Token	Yes	Conversion API access token. Prefer a GTM variable
Event ID	Recommended	Events Manager Event ID for this conversion. If empty, the tag sends `gtm_{event_name}` from the incoming event. If both Event ID and event name are missing, the conversion is not sent
Set first-party cookies	No (on by default)	When enabled, the tag writes a first-party `_twclid` cookie if `twclid` is present on the page URL

Event data overrides (optional)

Use these only when the incoming event does not already contain the value, or when you need to replace it.

Field	Default if empty	Notes
Conversion ID	Incoming event `event_id`	Per-conversion deduplication key. Must match the Pixel `conversion_id` when both fire
Email	`user_data.email_address`, `user_data.sha256_email_address`, or `email`	Plain or SHA-256. Plain values are trimmed, lowercased, and hashed
Phone	`user_data.phone_number`, `user_data.sha256_phone_number`, or `phone`	Plain or SHA-256. Send E.164 (for example `+11234567890`) before hashing
IP Address	`ip_override` or `ip`	Not hashed. Do not send IP or user agent as the only identifiers
User Agent	`user_agent`	Not hashed. Do not send IP or user agent as the only identifiers

Logs settings

Option	When to use
Do not log	Production, once the integration is verified
Log to console during debug and preview (default)	Testing in GTM Preview
Always log to console	Temporary troubleshooting only. Avoid in production; logs can include identifiers

Step 6: Choose a trigger

Create a trigger that fires when the GA4 Client has claimed the event. One tag per conversion (recommended when you set Event ID in the tag)

Trigger type: Custom
Condition: Event Name equals purchase (or generate_lead, sign_up, and so on)

Create a separate X tag for each Events Manager Event ID. Single tag for all events (when Event ID is left empty)

Trigger: All Events, or a regex of the event names you want to send
The template will send gtm_purchase, gtm_generate_lead, and so on

Do not fire the X tag on GTM’s internal clients-only requests. Confirm in Preview that the GA4 Client claimed the request before the X tag fires.

Step 7: Send identifiers for matching

X needs at least one strong identifier to match the conversion to an X user. Include as many as you can.

Identifier	How the official tag finds it	Hashing
X Click ID (`twclid`)	Query parameter on `page_location`, first-party `_twclid` cookie, or event field `twclid`	None
Pixel cookie (`_twpid`)	First-party `_twpid` cookie (usually set by the X Pixel)	None
Email	Override, `user_data.email_address` / `sha256_email_address`, or `email`	SHA-256 (automatic for plain values)
Phone	Override, `user_data.phone_number` / `sha256_phone_number`, or `phone`	SHA-256 (automatic for plain values)
IP address	Override, `ip_override`, or `ip`	None. Must be paired with another identifier
User agent	Override or `user_agent`	None. Must be paired with another identifier

Click ID (`twclid`)

Always pass Click ID when it is available.

Website click-throughs from X ads append twclid to the landing-page URL.
With Set first-party cookies enabled, the server tag stores that value in _twclid (about 390 days) so later conversions on the same domain can still send it.
A first-party tagging domain makes this cookie more reliable.

If you use the X Pixel on the page, keep it installed. The Pixel can set _twpid, which the server tag also reads.

Email and phone

Do not salt hashes.
Email: trim whitespace; the tag lowercases before hashing.
Phone: normalize to E.164 on your site or in GTM before the event reaches the server. The tag hashes but does not reformat numbers.
Already-hashed 64-character hex values are sent as-is.

IP address or user agent alone is not enough. Send Click ID, email, or phone whenever possible. More identifiers improve match rate.

Respect user consent and applicable privacy law. Do not send Conversion API events for users who have opted out of this type of tracking.

Event parameter mapping

The tag maps GA4-style event data to the Conversion API automatically.

Conversion API field	Incoming event field	Notes
`event_id`	Tag Event ID	Events Manager Event ID. If unset, `event_name` is sent as `gtm_{name}`
`conversion_id`	Tag Conversion ID, else event `event_id`	Deduplication key
`event_source_url`	`page_location`	Page that produced the event
`value`	`value`	Numeric
`price_currency`	`currency`	Uppercased
`contents[].content_id`	`items[].item_id` or `items[].id`
`contents[].content_name`	`items[].item_name` or `items[].name`
`contents[].content_price`	`items[].price`
`contents[].num_items`	`items[].quantity`
`number_items`	Sum of item quantities

Suggested GA4 event names

These names work well if you leave Event ID empty (gtm_{name}) or if you trigger one X tag per name:

Common conversion	GA4 event name
Purchase	`purchase`
Add to cart	`add_to_cart`
Begin checkout	`begin_checkout`
Lead	`generate_lead`
Sign up	`sign_up`
Search	`search`
View content	`view_item`
Add payment info	`add_payment_info`
Page view	`page_view`

For Pixel + Conversion API, prefer the Events Manager Event ID on the X tag over relying on gtm_{name}.

Deduplication

If the same conversion is sent by the X Pixel and the Conversion API, send both of the following on both channels:

The same Events Manager Event ID
The same Conversion ID for that occurrence (order ID, UUID, or the GA4 event_id)

On the Pixel, this is the deduplication key in the snippet (conversion_id). On the GTM Conversion API tag, set Conversion ID, or send event_id on the GA4 event and let the tag use it. Use the same trigger in the web container for the Pixel tag and the GA4 Event tag so both sides fire together with the same ID. You do not need deduplication if Pixel and Conversion API send different events.

Step 8: Test in Preview

Use GTM Preview on both containers before you publish.

In the server container, select Preview. If you use a custom domain, preview against that URL.
In the web container, select Preview and connect your website.
Trigger a test conversion (for example complete a test purchase).
In the web debugger, confirm the GA4 Event tag fired and that event_id, value, currency, and user data are present.
In the server debugger:
- Confirm the GA4 Client claimed the request.
- Confirm X Ads Conversion API (Official) fired.
- Open the tag → Request and verify an outgoing POST to https://ads-api.x.com/12/measurement/conversions/{your_pixel_id}.
- Confirm the response status is 2xx.
In Events Manager, confirm the test conversion appears on the event (allow a short delay).

If the tag does not fire

The web GA4 Event tag did not fire, or is not sending to the server URL.
The server trigger does not match event_name.
Preview was started before the latest workspace changes; restart Preview.

If the tag fires and fails

Open the outgoing request in the server debugger and inspect the response body. Common causes:

Invalid Pixel ID or access token
Missing Event ID and missing event name
No usable identifier (no twclid, email, or phone)
Event ID that does not belong to that Pixel

Set Logs Settings to debug while testing. Switch to Do not log before production traffic.

Step 9: Publish

Remove any test-only overrides.
Set logs to Do not log (or keep debug-only).
Submit and publish the server container.
Submit and publish the web container if you changed it.
After go-live, confirm Events Manager is receiving production events and that duplicate Pixel + API events are collapsing when Conversion IDs match.

Conversion API traffic is rate-limited to 60,000 events per ad account per 15 minutes. See Web conversions.

Checklist

Pixel ID and Conversion API access token stored in GTM variables
Each conversion has an Events Manager Event ID (especially for Pixel + API)
Web container sends events to the server container URL
GA4 Client is enabled in the server container
Official tag installed (X Ads Conversion API (Official))
Triggers match the events you intend to send
twclid captured (URL and/or _twclid cookie)
Email and/or E.164 phone included when available
Pixel and API share Conversion ID when both fire
Preview shows HTTP 2xx to ads-api.x.com
Events Manager shows the events
Server container published; first-party domain used in production

Frequently asked questions

Do I still need the X Pixel? The Conversion API can run on its own. We recommend Pixel + Conversion API with shared Event ID and Conversion ID so you keep coverage when one channel drops events. Does this require Ads API access or OAuth? Not for this GTM template. The tag sends X-Pixel-Token with the Events Manager access token. Custom code integrations still use the Web conversions authentication flow. Can I host the tagging server outside Google Cloud? Yes. GTM server-side supports manual provisioning on other clouds. Why is Click ID missing in Preview? The test page URL may not include twclid, the _twclid cookie may be blocked on the default tagging domain, or Set first-party cookies is off. Load a URL that includes ?twclid=... and use a first-party server domain. Can one server tag send every event? Yes, if you leave Event ID empty and trigger on multiple event names. The API then receives gtm_{event_name}. For named Events Manager events and Pixel deduplication, use one tag (or a lookup table variable) per Event ID. How is this different from third-party X/Twitter GTM tags? The official tag is X Ads Conversion API (Official), available in the Google Tag Manager Community Template Gallery. It authenticates with a Pixel access token and is supported for this Conversion API integration.

Overview

Fundamentals

Resources

Measurement

Set up the Conversion API with Google Tag Manager

How the integration works

Prerequisites

Step 1: Collect your Pixel ID, Event IDs, and access token

Pixel ID

Conversion events (Event IDs)

Access token

Step 2: Create a GTM server container

Step 3: Send website events to the server container

GA4 Configuration tag

GA4 Event tags

Step 4: Install the official X tag in the server container

Step 5: Create and configure the Conversion API tag

Required configuration

Event data overrides (optional)

Logs settings

Step 6: Choose a trigger

Step 7: Send identifiers for matching

Click ID (`twclid`)

Email and phone

Event parameter mapping

Suggested GA4 event names

Deduplication

Step 8: Test in Preview

If the tag does not fire

If the tag fires and fails

Step 9: Publish

Checklist

Frequently asked questions

​How the integration works

​Prerequisites

​Step 1: Collect your Pixel ID, Event IDs, and access token

​Pixel ID

​Conversion events (Event IDs)

​Access token

​Step 2: Create a GTM server container

​Step 3: Send website events to the server container

​GA4 Configuration tag

​GA4 Event tags

​Step 4: Install the official X tag in the server container

​Step 5: Create and configure the Conversion API tag

​Required configuration

​Event data overrides (optional)

​Logs settings

​Step 6: Choose a trigger

​Step 7: Send identifiers for matching

​Click ID (twclid)

​Email and phone

​Event parameter mapping

​Suggested GA4 event names

​Deduplication

​Step 8: Test in Preview

​If the tag does not fire

​If the tag fires and fails

​Step 9: Publish

​Checklist

​Frequently asked questions

​Related resources

How the integration works

Prerequisites

Step 1: Collect your Pixel ID, Event IDs, and access token

Pixel ID

Conversion events (Event IDs)

Access token

Step 2: Create a GTM server container

Step 3: Send website events to the server container

GA4 Configuration tag

GA4 Event tags

Step 4: Install the official X tag in the server container

Step 5: Create and configure the Conversion API tag

Required configuration

Event data overrides (optional)

Logs settings

Step 6: Choose a trigger

Step 7: Send identifiers for matching

Click ID (`twclid`)

Email and phone

Event parameter mapping

Suggested GA4 event names

Deduplication

Step 8: Test in Preview

If the tag does not fire

If the tag fires and fails

Step 9: Publish

Checklist

Frequently asked questions

Related resources