Web Conversions

conversions

Web Conversions

POST version/measurement/conversions/:pixel_id

Send website conversion events for a single Universal Website Tag pixel 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 of error codes are returned.

The rate limit will be 60,000 request per 15 minute interval (each request allows 500 events).

Resource URL

https://ads-api.x.com/11/measurement/conversions/:pixel_id

Parameters

Name Description
pixel_id
required
 The Universal Website Tag (UWT) ID for an ad account. This represents that base36 encoded value for an ad account’s UWT id.

Type: string

Example: o5h34
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":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"tw-o5h34-o9p5x", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]

conversions object

Name Description
conversion_time
required

The time, expressed in ISO 8601.

Type: string

Example: 2017-10-05T00:00:00Z
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 Single Event Website Tag in Ads Manager and Ads API.

Type: string

Example: tw-o5h34-o9p5x
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 (twclid or email) is required.

Type: array

Example: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items
optional

The number of items being purchased in the event. Must be a positive number greater than zero.

Type: integer

Example: 4
price_currency
optional

The currency of items being purchased in the event, expressed in ISO-4217. See Currency for detailed information.

Type: string

Default: USD

Example: JPY
value
optional

The price value of items being purchased in the event, represented in price_currency currency.

Type: double

Example: 100.00
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: 23294827
description
optional

Description with any additional information on the conversions.

Type: string

Example: test conversion
search_string
optional

Text that was searched for on the advertiser’s website.

Type: string

Example: milk
contents
optional

List of details relating to a specific product/content to provide granular information. See table below for supported fields.

Type: array

Example: contents": [{"content_id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.00, "num_items": 1, "content_group_id": "123"}, {"content_id": "2", "content_price": 50.00}]

identifiers object (at least one of the identifiers is required)

Name Description
twclid
sometimes required

Twitter Click ID as parsed from the click-through URL. It's required if hashed_email identifier is not added.

Type: string

Example: 26l6412g5p4iyj65a2oic2ayg2
hashed_email
sometimes required

A hashed email address (SHA256). The text must be lowercase, remove any trailing or leading spaces before hashing. It's required if twclid identifier is not added.

Type: string

Example: For test-email@test.com = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8

contents object

Name Description
content_id
optional

SKU or GTIN; identifier that represents the content.

Type: string

Example: jhp
content_group_id
optional

ID associated with a group of product variants

Type: integer

Example: group 1
content_name
optional

Name of the product or service.

Type: string

Example: radio flyer
content_price
optional

Price of the product or service.

Type: double

Example: 5.00
content_type
optional

Category for the product that was purchased.

Type: string

Example: clothes
num_items
optional

Number of products purchased

Type: integer

Example: 1

Response Parameters

Name Description
conversions_processed

Number of conversions successfully processed

Type: integer

Example: 1
debug_id

A debug UUID that can be used for subsequent investigations

Type: string

Example: ff02e052-36e4-47d6-bdf0-6d8986446562

Example Request

twurl -H 'ads-api.x.com' -X POST '/11/measurement/conversions/o5h34' --data '
{
   "conversions":[
      {
         "conversion_time":"2022-02-18T01:14:00.603Z",
         "event_id":"tw-o5h34-o9p5x",
         "identifiers":[
            {
               "twclid":"23opevjt88psuo13lu8d020qkn"
            },
            {
               "hashed_email":"63dc92389e3326e3ee3d7e6e715fda270977b9d293d97760f89105c86b3e2f11"
            }
         ],
         "value":250.00,
         "number_items":3,
         "conversion_id":"23294827",
         "description":"Pet supply purchases",
         "contents":[
            {
               "content_id":"1",
               "content_price":50.00,
               "num_items":1
            },
            {
               "content_id":"2",
               "content_price":100.00,
               "num_items":2

            }
         ]
      }
   ]
}' --header 'Content-Type: application/json'

 

Example Response

{
   "request":{
      "params":{
         "account_id":"18ce552mlaq"
      }
   },
   "data":{
      "conversions_processed":1,
      "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"
   }
}