Twitter conversion API tag
Updated Jul 27, 2026
The X (Twitter) Conversion API allows you to send conversion events from your server directly to X Ads API servers. This helps you measure campaign performance, improve attribution, and track conversions even when browser-based tracking is limited.
This guide focuses on how to configure the X (Twitter) Conversion API tag.
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.
Was this article helpful?
Comments