Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.x.com/llms.txt

Use this file to discover all available pages before exploring further.

​
API Reference

This is the full technical reference. For an overview of Catalog Management concepts, product feeds, and Dynamic Product Ads, see the Catalog Management Overview.
These endpoints are currently available via early-access only. To apply for access, please fill out this form or reach out to your X representative.

​
Product Catalogs

​
GET product_catalogs

Retrieve details for some or all product catalogs associated with the authenticated user (default) or the user specified in the user_id parameter. Resource URL https://ads-api.x.com/12/product_catalogs
​
user_id
long
A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name.
Example Request 
GET https://ads-api.x.com/12/product_catalogs
Example Response 
{
  "request": {
    "params": {}
  },
  "next_cursor": null,
  "data": [
    {
      "id": "1547080201384865792",
      "name": "Catalog Name"
    }
  ]
}

​
POST product_catalogs

Create a product catalog. One user can only create one catalog that holds all products. X merchants need to create a catalog before uploading products. Resource URL https://ads-api.x.com/12/product_catalogs
​
name
string
required
Name of your product catalog.
​
user_id
long
A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name.
Example Request 
POST https://ads-api.x.com/12/product_catalogs?name=catalog_123_abc_def
Example Response 
{
  "request": {
    "params": {
      "name": "catalog_123_abc_def"
    }
  },
  "data": {
    "id": "1559934724822351872",
    "name": "catalog_123_abc_def"
  }
}

​
PUT product_catalogs/:product_catalog_id

Update a product catalog. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id
​
id
string
required
Identifier of your product catalog.
​
name
string
required
Name of your product catalog.
Example Request 
PUT https://ads-api.x.com/12/product_catalogs/1547080201384865792?name=My Catalog
Example Response 
{
  "request": {
    "params": {
      "id": "1547080201384865792",
      "name": "My Catalog"
    }
  },
  "data": {
    "id": "1547080201384865792",
    "name": "My Catalog"
  }
}

​
DELETE product_catalogs/:product_catalog_id

Delete a product catalog. This is a permanent deletion. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id
​
id
string
required
Identifier of your product catalog.
Example Request 
DELETE https://ads-api.x.com/12/product_catalogs/1559919496399204352
Example Response 
{
  "request": {
    "params": {
      "id": "1559919496399204352"
    }
  },
  "data": {
    "id": "1559919496399204352",
    "name": "catalog dos"
  }
}

​
Products

X merchants are able to send a synchronous batch request to view, create, edit, and delete products, instead of having to upload a feed file. There are two types of products: individual products vs product groups. A product group is a group of multiple variants and is created when the user provides an item_group_id and has multiple variants for the product. When you call a fetch endpoint for products that includes grouped products, only the product that you submitted first will be returned.

​
GET product_catalogs/:product_catalog_id/products

Retrieve details for some or all products associated with the specified Product Catalog. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/products
​
item_group_key
string
This is a X-generated item group identifier.
​
count
int
default:"100"
Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 100
​
cursor
string
Specifies a cursor to get the next page of results. See Pagination for more information.
Please refer to the product specifications guide for details about responses. Example Request 
GET https://ads-api.x.com/12/product_catalogs/1547080201384865792/products?count=1
Example Response 
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "count": 1
    }
  },
  "next_cursor": "1547080787865939970",
  "data": [
    {
      "inventory": 5,
      "custom_label_2": null,
      "item_group_key": null,
      "additional_image_link": null,
      "size": null,
      "mobile_link": null,
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
      "price": "20.00 USD",
      "gtin": null,
      "age_group": "teen",
      "availability": "in stock",
      "product_type": "",
      "color": null,
      "custom_label_3": null,
      "item_group_id": null,
      "brand": "X",
      "product_key": "1547080787865939969",
      "mpn": null,
      "id": "123abc",
      "custom_label_4": null,
      "condition": "new",
      "custom_label_0": null,
      "sale_price": null,
      "custom_label_1": null,
      "link": "https://www.x.com/twtr_blue",
      "sale_price_effective_date": null,
      "image_link": "https://t.co/jeans_1.jpg",
      "title": "My shoes",
      "google_product_category": "Apparel & Accessories > Shoes",
      "gender": "female"
    }
  ]
}

​
PUT product_catalogs/:product_catalog_id/products

Add new products or update existing ones via a batch request. In a single request, up to 25 products can be supported. A PUT request needs all of the required fields from the attribute list below. If we do not recognize the id, we create a new product. If we recognize the id in your catalog, we update the corresponding existing product. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/products Request Attributes (JSON body)
​
id
string
required
Unique ID for the item. Use the SKU if possible. If there are multiple instances of the same ID, all instances will be ignored.
​
product_key
string
required
Unique product object identifier generated by X.
​
title
string
required
The name of the product. Should be the same name as the product from the landing product page given through link or mobile_link attributes. Max 150 characters.
​
description
string
required
The description of the product. This field does not support HTML and must be in plain text. Max 5000 characters.
​
availability
enum
required
Current availability of your item.

Possible values: in stock, available for order, preorder, out of stock, discontinued
​
condition
enum
required
Condition of the item being sold.

Possible values: new, used, refurbished
​
price
string
required
Price of the item. Format as a number followed by the 3-digit ISO currency code (ISO 4217), with a space between cost and currency. Use . as the decimal point.
​
link
string
required
URL of the product page where people can buy the item. Must include https.
​
image_link
string
required
URL for the primary image of your item. Must be JPG, GIF, WEBP, or PNG. Minimum 500x500px. Max file size 5MB.
​
brand
string
The brand name of the item. Required if gtin and mpn are not available.
​
gtin
string
Global Trade Item Number (UPC, EAN, JAN, or ISBN). Required if brand and mpn are not available.
​
mpn
string
Manufacturer Part Number. Required if gtin and brand are not available.
​
mobile_link
string
URL of a mobile-optimized product page. Must include https.
​
additional_image_link
string
Comma-separated list of up to 10 additional image URLs. Follow the same specs as image_link.
​
google_product_category
string
Category according to Google’s product taxonomy (path or ID).
​
product_type
string
Your business’s custom product taxonomy. Subcategories separated by > (with spaces).
​
inventory
int
Quantity available to sell. Must be ≥ 1 when availability is in stock.
​
sale_price
string
Discounted price (must be lower than price). Same format as price.
​
sale_price_effective_date
string
Time range for the sale period in ISO-8601 format: YYYY-MM-DDTHH:MM+HH:MM/YYYY-MM-DDTHH:MM+HH:MM.
​
item_group_id
string
Groups product variants together (size, color, age_group, gender). Required if the product has variants.
​
item_group_key
string
X-generated item group identifier.
​
gender
enum
Gender for item sizing.

Possible values: female, male, unisex
​
color
string
Primary color of the product (do not use hex codes).
​
size
string
Size of the item (word, abbreviation, or number).
​
age_group
enum
Associated age group.

Possible values: adult, all ages, teen, kids, toddler, infant, newborn
​
custom_label_0
string
Extra custom label.
​
custom_label_1
string
Extra custom label.
​
custom_label_2
string
Extra custom label.
​
custom_label_3
string
Extra custom label.
​
custom_label_4
string
Extra custom label.
Response Parameters
​
warnings
array
Warnings about your request.
​
errors
array
Error messages about your request.
​
product_key
string
Unique product object identifier generated by X.
​
id
string
Unique ID for the item.
​
status
enum
Status of your request.

Possible values: CREATE_SUCCESS, UPDATE_SUCCESS, ERROR, NO_CHANGE
Example Request 
PUT https://ads-api.x.com/12/product_catalogs/1547080201384865792/products
JSON Body 
{
  "products": [
    {
      "id": "test-12345",
      "title": "Test Product 1",
      "description": "The product which was added from the upsert endpoint",
      "availability": "in stock",
      "condition": "new",
      "link": "https://www.x.com/twtr_blue",
      "image_link": "https://www.kurzweilai.net/images/Naam-Limits-of-Earth-Part1-001-earth-600x600.jpg",
      "brand": "x",
      "gtin": "1432563728",
      "mpn": "3268793T",
      "mobile_link": "https://www.x.com/twtr_blue",
      "google_product_category": "Apparel & Accessories > Clothing > Dresses",
      "product_type": "Apparel & Accessories > Clothing > Dresses",
      "inventory": 2,
      "price": "60.00 USD",
      "gender": "female",
      "color": "blue",
      "size": "medium",
      "sale_price": "50.00 USD",
      "sale_price_effective_date": "2022-10-04T17:20:31.000Z/2022-10-10T04:00:00.000Z",
      "age_group": "adult",
      "custom_label_0": "custom value"
    }
  ]
}
Example Response 
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792"
    }
  },
  "data": {
    "products_response": [
      {
        "warnings": [],
        "errors": [],
        "product_key": "1576769414321651714",
        "id": "test-123456",
        "status": "CREATE_SUCCESS"
      }
    ]
  }
}

​
DELETE product_catalogs/:product_catalog_id/products

Delete existing products. This is a permanent deletion. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/products Request Parameters (JSON body)
​
product_keys
array
required
Array of unique product object identifiers generated by X.
Example Request 
DELETE https://ads-api.x.com/12/product_catalogs/1569782857975087104/products
JSON Body 
{
  "product_keys": [
    "1576769414321651714",
    "1577536549830344705"
  ]
}
Example Response 
{
  "request": {
    "params": {
      "product_keys": [
        "1576769414321651714",
        "1577536549830344705"
      ]
    }
  },
  "data": {
    "delete_products": [
      {
        "product_key": "1576769414321651714",
        "failed_product_key": null,
        "message": null
      },
      {
        "product_key": "1577536549830344705",
        "failed_product_key": null,
        "message": null
      }
    ]
  }
}

​
Product Sets

Product Sets are collections of products which represent a subset of your catalog (e.g. “Fall Sale Products”). You can use product sets to run Dynamic Product Ads (DPA) featuring the specific products included in that collection, rather than all products in your catalog.

​
GET product_catalogs/:product_catalog_id/product_sets/:product_set_id

Retrieve details for a specific Product Set associated with the specified Product Catalog. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/product_sets/:product_set_id
​
product_set_id
string
Unique ID for the product set.
Example Request 
GET https://ads-api.x.com/12/product_catalogs/1547080201384865792/product_sets/1560456755976343552
Example Response 
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "id": "1560456755976343552"
    }
  },
  "data": {
    "name": "Test Product Set API",
    "description": "Price and Custom Filter",
    "product_ids": [
      "123abc",
      "myshoes2"
    ],
    "processing_status": "DONE",
    "id": "1560456755976343552",
    "filters": [
      {
        "attribute": "price",
        "operator": "LESS_THAN",
        "value": "120.00 USD"
      },
      {
        "attribute": "custom_field_5",
        "operator": "MATCH",
        "value": "test"
      }
    ],
    "type": "FILTERED"
  }
}

​
POST product_catalogs/:product_catalog_id/product_sets

Create a new product set. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/product_sets Request Parameters (JSON body)
​
name
string
required
Name of the product set.
​
description
string
Description of the product set.
​
type
enum
required
Type of product set.

Possible values: MANUAL, FILTERED
​
filters
array
Required when type is FILTERED. Array of filter objects with attribute, operator, and value.

Supported attributes: price, product_type, google_product_category, sale_price, inventory, custom_label_0 through custom_label_4.

Supported operators: GREATER_THAN, EQUAL_TO, LESS_THAN, MATCH, NOT_CONTAINS, CONTAINS.
​
product_keys
array
Required when type is MANUAL. Array of X-generated product keys.
Response Parameters
​
processing_status
enum
Status of product set creation when using FILTERED type.

Possible values: DONE, PROCESSING, FAILED
Example Request (MANUAL type) 
POST https://ads-api.x.com/12/product_catalogs/1569782857975087104/product_sets
JSON Body 
{
  "name": "manual API product set",
  "type": "MANUAL",
  "product_keys": [
    "1569784751351013380"
  ]
}
Example Response 
{
  "request": {
    "params": {
      "product_catalog_id": "1569782857975087104",
      "name": "manual API product set",
      "type": "MANUAL",
      "product_keys": [
        "1569784751351013380"
      ]
    }
  },
  "data": {
    "name": "manual API product set",
    "description": null,
    "product_ids": [
      "sdkljsdijf"
    ],
    "processing_status": "DONE",
    "id": "1573806483589849088",
    "filters": [],
    "type": "MANUAL"
  }
}
Example Request (FILTERED type) 
POST https://ads-api.x.com/12/product_catalogs/1569782857975087104/product_sets
JSON Body 
{
  "name": "filtered API product set",
  "description": "price above 100 USD",
  "type": "FILTERED",
  "filters": [
    {
      "attribute": "price",
      "operator": "GREATER_THAN",
      "value": "100.00 USD"
    }
  ]
}
Example Response 
{
  "request": {
    "params": {
      "product_catalog_id": "1569782857975087104",
      "name": "filtered API product set",
      "description": "price above 100 USD",
      "type": "FILTERED",
      "filters": [
        {
          "attribute": "price",
          "operator": "GREATER_THAN",
          "value": "100.00 USD"
        }
      ]
    }
  },
  "data": {
    "name": "filtered API product set",
    "description": "price above 100 USD",
    "product_ids": [
      "nike-sb-dunk-high-pro-medium-grey-pink",
      "sdkljsdijf"
    ],
    "processing_status": "DONE",
    "id": "1573831671954096128",
    "filters": [
      {
        "attribute": "price",
        "operator": "GREATER_THAN",
        "value": "100.00 USD"
      }
    ],
    "type": "FILTERED"
  }
}

​
PUT product_catalogs/:product_catalog_id/product_sets/:product_set_id

Update an existing product set. Note: Updating FILTERED product sets is not supported. The example below shows a MANUAL product set update. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/product_sets/:product_set_id Request Parameters (JSON body)
​
product_set_id
string
required
Unique ID for the product set.
​
name
string
Name of the product set.
​
description
string
Description of the product set.
​
product_keys
array
Array of X-generated product keys (for MANUAL sets).
Example Request 
PUT https://ads-api.x.com/12/product_catalogs/1549442554172694528/product_sets/1564499160082001920
JSON Body 
{
  "name": "Update name product catalogs",
  "product_keys": ["1576768397127606272", "1547080787865939969"]
}
Example Response 
{
  "request": {
    "params": {
      "product_catalog_id": "1576873894266273792",
      "id": "1564499160082001920",
      "product_keys": [
        "1576768397127606272",
        "1547080787865939969"
      ],
      "name": "Update name product catalogs"
    }
  },
  "data": {
    "name": "Update name product catalogs",
    "description": "Manual product Sets description",
    "product_ids": [
      "test-12345",
      "123abc"
    ],
    "processing_status": "DONE",
    "id": "1564499160082001920",
    "filters": [],
    "type": "MANUAL"
  }
}

​
DELETE product_catalogs/:product_catalog_id/product_sets/:product_set_id

Delete an existing product set. This is a permanent deletion. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/product_sets/:product_set_id
​
product_set_id
string
required
Unique ID for the product set.
Example Request 
DELETE https://ads-api.x.com/12/product_catalogs/1547080201384865792/product_sets/1559806000097787904
Example Response 
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "id": "1559806000097787904"
    }
  },
  "data": {
    "name": "Filtered Product",
    "description": "Filtered product Set",
    "product_ids": [],
    "processing_status": "DONE",
    "id": "1559806000097787904",
    "filters": [
      {
        "attribute": "price",
        "operator": "GREATER_THAN",
        "value": "100.00 USD"
      }
    ],
    "type": "FILTERED"
  }
}

​
Scheduled Feeds

Scheduled Feeds configure the file location and frequency with which X ingests product data into a user’s catalog. Only one product feed is supported per user. Importing a scheduled feed is an additive action — removing products from the feed does not delete them from the catalog.

​
GET product_catalogs/:product_catalog_id/scheduled_feeds

Retrieve details for scheduled feeds associated with the specified Product Catalog. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/scheduled_feeds Example Request 
GET https://ads-api.x.com/12/product_catalogs/1547080201384865792/scheduled_feeds
Example Response 
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "start_time": "01:30",
      "product_catalog_id": "1547080201384865792",
      "feed_url": "https://test212/file.csv",
      "feed_format": "CSV",
      "id": "1564821386714947589",
      "created_at": "2022-08-31T03:44:26.000Z",
      "frequency": "DAILY",
      "repeat": null,
      "updated_at": "2022-09-27T08:47:23.000Z",
      "time_zone": "America/New_York"
    }
  ]
}

​
POST product_catalogs/:product_catalog_id/scheduled_feeds

Create a scheduled product feed. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/scheduled_feeds
​
feed_url
string
required
Host feed URL for your product file. Can be up to 8GB.
​
feed_format
enum
required
Format of the product feed file.

Possible values: CSV, TSV, XML
​
frequency
enum
required
How often X should ingest the feed.

Possible values: HOURLY, DAILY, WEEKLY
​
repeat
string
Required for WEEKLY or HOURLY frequency.

  • WEEKLY: MONDAY–SUNDAY
  • HOURLY: 1, 2, 3, 4, 6, 8, 12
  • DAILY: Do not include this parameter.
​
start_time
string
required
Time to import the feed file (HH:MM format).
​
time_zone
string
required
IANA time zone for start_time.
Example Request 
POST https://ads-api.x.com/12/product_catalogs/1547080201384865792/scheduled_feeds?feed_url=https://test212/file.csv&feed_format=CSV&frequency=WEEKLY&time_zone=America/New_York&repeat=SATURDAY&start_time=01:30
Example Response 
{
  "request": {
    "params": {
      "start_time": "01:30",
      "product_catalog_id": "1547080201384865792",
      "feed_url": "https://test212/file.csv",
      "feed_format": "CSV",
      "frequency": "WEEKLY",
      "repeat": "SATURDAY",
      "time_zone": "America/New_York"
    }
  },
  "data": {
    "start_time": "01:30",
    "product_catalog_id": "1547080201384865792",
    "feed_url": "https://test212/file.csv",
    "feed_format": "CSV",
    "id": "1576851765428822016",
    "created_at": "2022-10-03T08:28:52.000Z",
    "frequency": "WEEKLY",
    "repeat": "SATURDAY",
    "updated_at": "2022-10-03T08:28:52.000Z",
    "time_zone": "America/New_York"
  }
}

​
PUT product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id

Update an existing scheduled product feed. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id
​
scheduled_feed_id
string
required
Unique ID for the scheduled feed.
​
feed_url
string
Host feed URL for your product file (up to 8GB).
​
feed_format
enum
Format of the product feed file.

Possible values: CSV, TSV, XML
​
frequency
enum
Ingestion frequency.

Possible values: HOURLY, DAILY, WEEKLY
​
repeat
string
Repeat value (see POST for valid values per frequency).
​
start_time
string
Time to import the feed (HH:MM).
​
time_zone
string
IANA time zone for start_time.
Example Request 
PUT https://ads-api.x.com/12/product_catalogs/1547080201384865792/scheduled_feeds/1577629831247720448?start_time=07:30
Example Response 
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "start_time": "07:30",
      "id": "1577629831247720448"
    }
  },
  "data": {
    "start_time": "07:30",
    "product_catalog_id": "1547080201384865792",
    "feed_url": "https://test212/file.csv",
    "feed_format": "CSV",
    "id": "1577629831247720448",
    "created_at": "2022-10-05T12:00:37.000Z",
    "frequency": "WEEKLY",
    "repeat": "SATURDAY",
    "updated_at": "2022-10-05T12:03:07.000Z",
    "time_zone": "America/New_York"
  }
}

​
DELETE product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id

Delete an existing scheduled product feed. This is a permanent deletion. Resource URL https://ads-api.x.com/12/product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id
​
scheduled_feed_id
string
required
Unique ID for the scheduled feed.
Example Request 
DELETE https://ads-api.x.com/12/product_catalogs/1547080201384865792/scheduled_feeds/1576854236993708032
Example Response 
{
  "request": {
    "params": {
      "product_catalog_id": "1547080201384865792",
      "id": "1576854236993708032"
    }
  },
  "data": {
    "start_time": "07:30",
    "product_catalog_id": "1547080201384865792",
    "feed_url": "https://test212/file.csv",
    "feed_format": "CSV",
    "id": "1576854236993708032",
    "created_at": "2022-10-03T08:38:41.000Z",
    "frequency": "DAILY",
    "repeat": null,
    "updated_at": "2022-10-03T08:50:10.000Z",
    "time_zone": "America/New_York"
  }
}