Twitter Conversions API tag for sGTM

The Twitter Conversions API allows you to send information from your server directly to Twitter servers, which can be used to measure campaign success.

With Twitter CAPI, you make tracking more secure and accurate. Like Facebook, Twitter allows and recommends using a hybrid method of tracking, web+server. When combining web and server tracking, deduplication is required. To match users in events to Twitter profiles, they use customer data: email and twclid.

This guide will discuss how the Twitter conversion API works and how to set up the Twitter CAPI tag in sGTM.

A person clicks on an ad on X (Twitter). X assigns identifiers to this interaction, such as:

• Click ID (twclid) – a unique identifier added to the landing page URL after an ad click.
• Other available user identifiers (for example, hashed email or phone number) can also be used for matching.

The visitor completes a conversion event (e.g., product click, add to cart, purchase). Instead of sending data from the browser, your server sends a direct API request to X. In this way, you get more precise data that is less affected by ad blockers and browser restrictions.

The API authenticates the request using credentials generated in your X Ads account.

After receiving the event, X tries to match it with previous ad engagement.

Matching can happen using:

• twclid
• Hashed email
• Hashed phone number
• Other supported identifiers

If X finds a match, it attributes the conversion to the corresponding ad campaign.

To complete this setup, you will need to create a server GTM container and send data from the web to the server GTM container. Here are the configuration guides:

• How to set up the server GTM container.
• How to send data from the web to the server GTM container using GA4 or using Data tag/Data Client.

1. Add “X (Twitter) Conversion API tag” to the server GTM container.

In the server GTM container, go to the section “Templates” → next to “Tag Templates”, click “Search Gallery” → search for “X (Twitter) Conversion API” → add the tag to your container.

2. Create a new tag.

In the section “Tags,” click “New” → as tag configuration, select “X (Twitter) Conversion API” tag.

3. Configure the tag.

3.1 Pixel ID - this is your Twitter ad account's Universal Website Tag (UWT) ID. 

To find the Pixel ID, log in to X Business Manager → Tools section of the menu → Events Manager → copy Pixel ID.

3.2 Event ID - you can find it when creating a conversion API event in the Twitter events manager.

The Event ID can be found next to each event you create.

3.3 Select Auth Method.

The X (Twitter) Conversion API tag by Stape provides two auth methods:

• Access Token (recommended) – a simple, recommended authentication using an Access Token generated from your X Ads Manager.
• OAuth – legacy OAuth 1.0a authentication is still supported but will be removed in December 2026. 

If you opt for the Access Token method, generate the Pixel Access Token. 

To do it, go to Events Manager → click on Install Pixel → select Manual on Installation Method → click Continue → select Conversion API → click Continue → click Generate access token.

Here is an example of tag configuration with Access Token as auth method:

If you opt for the OAuth method, click on the collapse element below for detailed guidelines:

3.4 Use HttpOnly cookies - this option forbids JavaScript from accessing the cookie if enabled.

3.5 Use Optimistic Scenario - if selected, the tag will call gtmOnSuccess() without waiting for a response from the API. This will speed up sGTM response time; however, your tag will always return the status fired successfully even in case it is not.

3.6 Server Event Data Override - Manually override or add server event data parameters. Available properties: 

• Conversion Time
• Number Items
• Currency
• Value
• Conversion ID
• Description
• Contents
• Search String. 

See X’s documentation for more details on what data parameters you can override.

3.7 User Data - add user data: email, phone, click ID, IP address, User Agent.

Note: At least one identifier must always be sent.

Twitter supports event deduplication. Combining web and server tracking requires sending a deduplication key with both web and server events. 

Use the Conversion ID (for deduplication) that can be found in the Server Event Data Override to send the deduplication key in the server GTM tag.

Find the corresponding parameter in the web GTM tag or pixel code (Conversion ID, if using the Twitter tag template, or conversion_id if using the pixel code).  Deduplication happens only if events were received within 48 hours.

To create a server-only event, use the Twitter events manager to create a new event and select Install with Conversion API on the third step. 

4. Add a trigger for a tag.

Specify the condition when the tag should fire (e.g., add to cart, purchase events).

Unfortunately, X (Twitter) doesn't provide a real-time event testing tool for Conversion API events.

To verify that your implementation is working:

• Use the server GTM Preview mode to confirm that the X Conversion API tag fires correctly and that requests are sent to X.

• If you use Stape Logs, check the outgoing requests to verify that events are successfully sent to the X endpoint in real time.

• In X Ads Manager, go to Conversion Tracking and check the status of your event. Once X starts receiving events, the event status will change to Active. You can also click View activity to see the events received by X.

Keep in mind that it may take 12–24 hours for the event status and activity to appear in X Ads Manager after the first events are sent.

Combining X Pixel with Conversion API creates a more complete tracking setup. It allows you to capture both browser and server-side events.

With the X (Twitter) Conversion API tag for sGTM, you can simplify server-side tracking implementation, automatically map conversion data, securely send user identifiers, and gain better control over the collected data.