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.
How Twitter Conversions API works
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.
Before you begin
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 send data from the web to the server GTM container using GA4 or using Data tag/Data Client.
How to set up X (Twitter) Conversion API tag in sGTM
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.
Note:
If you are currently using OAuth as an authentication method, be sure to migrate to Access Token before 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:
OAuth method configuration
To use this method, do the following:
- Create or sign into an X Developer Portal account.
Come up with an account name, and describe the use cases of X’s data and API.
For our case, it can be something like:
“I need to configure data conversions tracking and optimize ad performance on X using X CAPI and server GTM, as this type of configuration ensures precise data tracking. For this setup, I need to request access to the conversion API and generate an access token.”
Click “Submit”.
- Consumer Key and Consumer Secret - both are required to send requests to the Conversion API. They can be found in the X Developer dashboard → click on the key symbol next to your Project App.
Click “Regenerate” in the section “Consumer Keys”.
Copy the generated keys and paste them into the tag configuration. The first value stands for “Consumer Key” and the second for “Consumer Secret”.
- OAuth Token and OAuth Token Secret can be generated in the same place as Consumer Key and Consumer Secret - in the X dashboard → key symbol next to Project App.
To get them, just click on “Regenerate” in the section “Authentication Tokens”. Use an Access Token that belongs to a user with ads-account rights. Without these permissions, Conversion API calls may be rejected.
Here is an example of tag configuration with OAuth method:
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.
Event deduplication
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).
How to test X (Twitter) CAPI
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.
Conclusion
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.
Need help with setting up server-side tagging?
All it takes is a few simple questions. Click Get A Quote, fill-up the form, and we will send you a quote.
Comments