Overview

Overview

The Catalog API is a commerce solution that gives advertisers the ability to set up product feeds, group products into sets, and holistically manage catalog products. The Catalog API will be a core tool that enables programmatic catalog management and grants advertisers more control over how their catalogs are ingested and updated.

A catalog holds everything regarding the user's product and product set and is associated with the user's handle. Currently, one user can only create one catalog. 

The Catalog API supports 2 ways to ingest products:

  1. Scheduled Feed: the user can add a feed url (CSV, TSV, and XML) that will be periodically fetched (X currently supports a file up to 8GB)

  2. Batch Products API: the user can view, create, update and delete product attributes with batch (JSON) requests

X merchants are able to create product sets based on filter rules. By doing so, they will be able to attach additional metadata to their products, and create special product sets to showcase these products through organic commerce features or dynamic product ads. The Catalog API and X shopping manager supports two types of product sets. 

  1. Manual: the user can select up to 50 products, and set a name and a description

  2. Filter: the user can add up to 30 filters to automatically generate sets with products that satisfy these filters. Types of filters include price, Google product category, product type, inventory, sale price, and custom fields.

Catalog API comes with 4 endpoints to manage catalog:

  • Product Catalogs - Creating a container for product information
  • Products -  Synchronously adding, updateing, viewing, and removing products from the catalogs
  • Product Sets -  Sorting products into groups based on product information
  • Schedule Feeds - Seting up the asynchronous ingestion of file-based product data into the catalogs

 

Prerequisites for the Catalog API

Catalog API endpoints are currently available via early-access only. To apply for access, please reach out to your X representative. 

You are required to accept the terms of service via X Shopping Manager.

For the details on Shopping Manager and product specifications, please refer to Product specifications guide.

 

Rate Limits 

The following table lists the rate limits for each endpoint.

 

Product Catalog

HTTP Method

Rate limit

GET /product_catalogs

1,000 per 15 minutes

POST /product_catalogs

20 per 15 minutes

PUT /product_catalogs/:product_catalog_id

20 per 15 minutes

DELETE /product_catalogs/:product_catalog_id

20 per 15 minutes

 

Batch Products API 

 

HTTP Method

Rate limit

GET /product_catalogs/:product_catalog_id/products

1,000 per 15 minutes

PUT /product_catalogs/:product_catalog_id/products

600 per 15 minutes

DELETE /product_catalogs/:product_catalog_id/products

150 per 15 minutes

 

Product Sets

 

HTTP Method

Rate limit

GET /product_catalogs/:product_catalog_id/product_sets

2,000 per 15 minutes

POST /product_catalogs/:product_catalog_id/product_sets

100 per 15 minutes

PUT /product_catalogs/:product_catalog_id/product_sets/:product_set_id

500 per 15 minutes

DELETE /product_catalogs/:product_catalog_id/product_sets/:product_set_id

100 per 15 minutes

 

Product Feeds

 

HTTP Method

Rate limit

GET /product_catalogs/:product_catalog_id/product_feeds

1,000 per 15 minutes

POST /product_catalogs/:product_catalog_id/product_feeds

20 per 15 minutes

PUT /product_catalogs/:product_catalog_id/product_feeds/:product_feed_id

20 per 15 minutes

DELETE /product_catalogs/:product_catalog_id/product_feeds/:product_feed_id

20 per 15 minutes