Catalog Management
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:
-
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)
-
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.
-
Manual: the user can select up to 50 products, and set a name and a description
-
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 |