Catalog Management API Reference

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

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

string

required

Name of your product catalog.

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

string

required

Identifier of your product catalog.

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

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

string

This is a X-generated item group identifier.

int

default:"100"

Specifies the number of records to try and retrieve per distinct request.
Min: 1, Max: 100

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)

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.

string

required

Unique product object identifier generated by X.

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.

string

required

The description of the product. This field does not support HTML and must be in plain text. Max 5000 characters.

enum

required

Current availability of your item.

Possible values: in stock, available for order, preorder, out of stock, discontinued

enum

required

Condition of the item being sold.

Possible values: new, used, refurbished

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.

string

required

URL of the product page where people can buy the item. Must include https.

string

required

URL for the primary image of your item. Must be JPG, GIF, WEBP, or PNG. Minimum 500x500px. Max file size 5MB.

string

The brand name of the item. Required if gtin and mpn are not available.

string

Global Trade Item Number (UPC, EAN, JAN, or ISBN). Required if brand and mpn are not available.

string

Manufacturer Part Number. Required if gtin and brand are not available.

string

URL of a mobile-optimized product page. Must include https.

string

Comma-separated list of up to 10 additional image URLs. Follow the same specs as image_link.

string

Category according to Google’s product taxonomy (path or ID).

string

Your business’s custom product taxonomy. Subcategories separated by > (with spaces).

int

Quantity available to sell. Must be ≥ 1 when availability is in stock.

string

Discounted price (must be lower than price). Same format as price.

string

Time range for the sale period in ISO-8601 format: YYYY-MM-DDTHH:MM+HH:MM/YYYY-MM-DDTHH:MM+HH:MM.

string

Groups product variants together (size, color, age_group, gender). Required if the product has variants.

string

X-generated item group identifier.

enum

Gender for item sizing.

Possible values: female, male, unisex

string

Primary color of the product (do not use hex codes).

string

Size of the item (word, abbreviation, or number).

enum

Associated age group.

Possible values: adult, all ages, teen, kids, toddler, infant, newborn

string

Extra custom label.

string

Extra custom label.

string

Extra custom label.

string

Extra custom label.

string

Extra custom label.

Response Parameters

array

Warnings about your request.

array

Error messages about your request.

string

Unique product object identifier generated by X.

string

Unique ID for the item.

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)

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

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)

string

required

Name of the product set.

string

Description of the product set.

enum

required

Type of product set.

Possible values: MANUAL, FILTERED

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.

array

Required when type is MANUAL. Array of X-generated product keys.

Response Parameters

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)

string

required

Unique ID for the product set.

string

Name of the product set.

string

Description of the product set.

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

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

string

required

Host feed URL for your product file. Can be up to 8GB.

enum

required

Format of the product feed file.

Possible values: CSV, TSV, XML

enum

required

How often X should ingest the feed.

Possible values: HOURLY, DAILY, WEEKLY

string

Required for WEEKLY or HOURLY frequency.

WEEKLY: MONDAY–SUNDAY
HOURLY: 1, 2, 3, 4, 6, 8, 12
DAILY: Do not include this parameter.

string

required

Time to import the feed file (HH:MM format).

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

string

required

Unique ID for the scheduled feed.

string

Host feed URL for your product file (up to 8GB).

enum

Format of the product feed file.

Possible values: CSV, TSV, XML

enum

Ingestion frequency.

Possible values: HOURLY, DAILY, WEEKLY

string

Repeat value (see POST for valid values per frequency).

string

Time to import the feed (HH:MM).

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

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"
  }
}

Overview

Fundamentals

Resources

Measurement

Catalog Management API Reference

API Reference

Product Catalogs

GET product_catalogs

POST product_catalogs

PUT product_catalogs/:product_catalog_id

DELETE product_catalogs/:product_catalog_id

Products

GET product_catalogs/:product_catalog_id/products

PUT product_catalogs/:product_catalog_id/products

DELETE product_catalogs/:product_catalog_id/products

Product Sets

GET product_catalogs/:product_catalog_id/product_sets/:product_set_id

POST product_catalogs/:product_catalog_id/product_sets

PUT product_catalogs/:product_catalog_id/product_sets/:product_set_id

DELETE product_catalogs/:product_catalog_id/product_sets/:product_set_id

Scheduled Feeds

GET product_catalogs/:product_catalog_id/scheduled_feeds

POST product_catalogs/:product_catalog_id/scheduled_feeds

PUT product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id

DELETE product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id

​API Reference

​Product Catalogs

​GET product_catalogs

​POST product_catalogs

​PUT product_catalogs/:product_catalog_id

​DELETE product_catalogs/:product_catalog_id

​Products

​GET product_catalogs/:product_catalog_id/products

​PUT product_catalogs/:product_catalog_id/products

​DELETE product_catalogs/:product_catalog_id/products

​Product Sets

​GET product_catalogs/:product_catalog_id/product_sets/:product_set_id

​POST product_catalogs/:product_catalog_id/product_sets

​PUT product_catalogs/:product_catalog_id/product_sets/:product_set_id

​DELETE product_catalogs/:product_catalog_id/product_sets/:product_set_id

​Scheduled Feeds

​GET product_catalogs/:product_catalog_id/scheduled_feeds

​POST product_catalogs/:product_catalog_id/scheduled_feeds

​PUT product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id

​DELETE product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id

API Reference

Product Catalogs

GET product_catalogs

POST product_catalogs

PUT product_catalogs/:product_catalog_id

DELETE product_catalogs/:product_catalog_id

Products

GET product_catalogs/:product_catalog_id/products

PUT product_catalogs/:product_catalog_id/products

DELETE product_catalogs/:product_catalog_id/products

Product Sets

GET product_catalogs/:product_catalog_id/product_sets/:product_set_id

POST product_catalogs/:product_catalog_id/product_sets

PUT product_catalogs/:product_catalog_id/product_sets/:product_set_id

DELETE product_catalogs/:product_catalog_id/product_sets/:product_set_id

Scheduled Feeds

GET product_catalogs/:product_catalog_id/scheduled_feeds

POST product_catalogs/:product_catalog_id/scheduled_feeds

PUT product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id

DELETE product_catalogs/:product_catalog_id/scheduled_feeds/:scheduled_feed_id