Web Conversions
POST version/measurement/conversions/:pixel_id¶
Send website conversion events for a single Event Tag ID.
The response code should be checked for success (HTTP 200 OK). It is recommended to have a retry mechanism and basic logging in place in case error codes are returned.
The rate limit will be 100,000 request per 15 minute interval per account (each request allows 500 events).
Resource URL¶
https://ads-api.x.com/12/measurement/conversions/:pixel_id
Request URL Parameters¶
| Name | Description |
|---|---|
pixel_id
required |
The Base Tag ID for an ad account. This represents that base36 encoded value for an ad account’s Base Tag ID. Type: string Example: |
conversions
required |
The object in POST body of the API request. List of conversion events. Up to 500 conversion events may be provided. See the table below for supported fields. Type: array Example: |
conversions object
| Name | Description |
|---|---|
conversion_time
required |
The time, expressed in ISO 8601. Type: string Example: |
event_id
required |
The base-36 ID of a specific event. It matches a pre-configured event contained within this ad account. This is called ID in the corresponding event in Events Manager. Type: string Example: |
identifiers
required |
A list of identifier objects to match the conversion event to. Supported fields are listed in a table below. At least one of the identifier objects is required. If using IP address or user agent, a second identifier must be sent for proper conversion matching. Type: array Example: |
number_items
optional |
The number of items being purchased in the event. Must be a positive number greater than zero. Type: integer Example: |
price_currency
optional |
The currency of items being purchased in the event, expressed in ISO-4217. See Currency for detailed information. Type: string Default: Example: |
value
optional |
The price value of items being purchased in the event, represented in Type: double Example: |
conversion_id
optional |
For deduplication between pixel and conversion API conversions. An identifier for a conversion event that can be used for de-duplication between Web Pixel and Conversion API conversions in the same event tag. See the Conversions Guide's Testing Events and Deduplication section for more information. Type: string Example: |
description
optional |
Description with any additional information on the conversions. Type: string Example: |
contents
optional |
List of details relating to a specific product/content to provide granular information. See table below for supported fields. Type: array Example: |
identifiers object
| Name | Description |
|---|---|
twclid
sometimes required |
Click ID as parsed from the click-through URL. It's required if no other identifier is added. Type: string Example: |
hashed_email
sometimes required |
An email address hashed with SHA256. The text must be lowercase, remove any trailing or leading spaces before hashing. It's required if no other identifier is added. Type: string Example: For |
hashed_phone_number
sometimes required |
A phone number with E164 format and hashed with SHA256. The phone number must be in E164 format before hashing. It's required if no other identifier is added. Type: string Example: For |
| ip_address sometimes required |
This value is written in dotted-decimal notation, with four numbers separated by periods. IP address is required to be passed in conjunction with another identifier (twclid, email address, phone number or user agent). Type: string Example: 8.25.197.25 |
| user_agent sometimes required |
This identifier allows the server to identify the application, operating system, vendor, and/or version of the requesting user agent. User Agent is required to be passed in conjunction with another identifier (twclid, email address, phone number or IP address). Type: string Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36. |
contents object
| Name | Description |
|---|---|
content_id
optional |
SKU or GTIN; identifier that represents the content. Type: string Example: |
content_group_id
optional |
ID associated with a group of product variants Type: integer Example: |
content_name
optional |
Name of the product or service. Type: string Example: |
content_price
optional |
Price of the product or service. Type: double Example: |
content_type
optional |
Category for the product that was purchased. Type: string Example: |
num_items
optional |
Number of products purchased Type: integer Example: |
Response Parameters¶
| Name | Description |
|---|---|
conversions_processed
|
Number of conversions successfully processed Type: integer Example: |
debug_id
|
A debug UUID that can be used for subsequent investigations Type: string Example: |
Example Request¶
twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
{
"conversions":[
{
"conversion_time":"2022-02-18T01:14:00.603Z",
"event_id":"ol288",
"identifiers":[
{
"twclid":"23opevjt88psuo13lu8d020qkn"
},
{
"hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
},
{
"hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
},
{
"ip_address":"1.0.0.0",
"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
}
],
"value":"20.00",
"number_items":3,
"conversion_id":"23294827",
"description":"Pet supply purchases",
"contents":[
{
"content_id":"1",
"content_name":"Blankets",
"content_type":"Pet supplies",
"content_price":100.99,
"num_items":1,
"content_group_id":"123"
}
]
}
]
}' --header 'Content-Type: application/json'
Example Request¶
{
"request":{
"params":{
"account_id":"18ce552mlaq"
}
},
"data":{
"conversions_processed":1,
"debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"
}
}