We’ve released an update to the Ads API that enables developers to create solutions to help advertisers and merchants manage their product catalogs on Twitter. Ahead of our broad launch in the coming months, you can gain early access to the new Catalog API by filling out this form.
Introducing the Catalog API
The Catalog API is a commerce solution that gives advertisers the ability to set up product feeds, group products into sets, and holistically manage product catalogs.
As Twitter continues to develop on-platform commerce solutions, the Catalog API will be a core tool that enables programmatic catalog management and grants advertisers direct control over how their catalogs are ingested and updated.
Additionally, the Catalog API will provide the following benefits across developer segments:
-
Feed Management and Commerce Developers: Catalog API allows you to programmatically manage your clients’ catalogs on Twitter.
-
Campaign Management Developers: Catalog API will allow you to support the end-to-end creation of Dynamic Product Ads (DPA) once DPA campaign creation comes to the API.
-
Direct Advertiser Developers: Catalog API gives you direct control over how your catalogs are managed, ingested, and updated. Additionally, integrating with this API unlocks the ability to advertise with Dynamic Product Ads (DPA).
To get started with catalog management, check out this overview documentation and our FAQs.
Key Notes
-
The Catalog API is built around the Twitter Shopping Product specification.
-
Management functions include adding, removing, updating, viewing, and grouping products within a catalog.
-
Scheduled Feeds can be used to control the speed and frequency with which products are ingested and updated. Products endpoints can be used for adding, updating, viewing, and removing products from catalogs.
Next Steps
The Catalog API is a foundational building block for supporting commerce on Twitter, so we highly encourage you to build support for this new API and align launch timing with the release of Dynamic Product Ads in Twitter’s Ads Manager. If you’re interested in getting early access, please fill in this form.
Read on for more information about the Catalog API endpoints and integration details.
Catalog API Endpoints
The Catalog API includes the following endpoint resources:
Specific endpoint information and example requests are provided below.
Product Catalogs
With just one settable attribute (name), product_catalogs is a simple but essential endpoint resource. It works as a container for product information and is required in order to use any other Catalog API endpoint. All of the other API resources depend on and are associated with a product catalog.
Example Request
twurl -H ads-api.twitter.com "/12/product_catalogs"
{
"request": {
"params": {}
},
"next_cursor": null,
"data": [
{
"id": "1569782857975087104",
"name": "twitter-catalog"
}
]
}
Scheduled Feeds
The scheduled_feeds endpoint allows customers to set up and manage the asynchronous ingestion of file-based product data into their catalogs. Via this endpoint, customers can specify their feed URL, their feed format, and both the frequency and schedule for when feed updates will occur. As a reminder, files must adhere to the Twitter Shopping Product specification and scheduled_feeds must be associated with a particular Product Catalog.
Example Request
twurl -H ads-api.twitter.com "/12/product_catalogs/1569782857975087104/scheduled_feeds"
{
"request": {
"params": {
"product_catalog_id": "1569782857975087104"
}
},
"next_cursor": null,
"data": [
{
"feed_format": "CSV",
"feed_url": "https://www.test.com/example.csv",
"id": "1575171578983493632",
"frequency": "WEEKLY",
"repeat": "MONDAY",
"start_time": "07:00",
"time_zone": "America/New_York",
"created_at": "2022-09-28T17:12:24.000Z",
"updated_at": "2022-09-28T17:12:24.000Z"
}
]
}
Products
The products endpoint is our synchronous batch API. Via three supported HTTP methods (GET, PUT, and DELETE), customers can directly add, update, view, and remove products from their catalogs. Additionally, when using the PUT endpoint, customers can add and/or update multiple products in a single request via a JSON payload. As a reminder, the data in the JSON payload must adhere to the Twitter Shopping Product specification and products must be associated with a particular Product Catalog.
Example Request
twurl -H ads-api.twitter.com "/12/product_catalogs/1569782857975087104/products?count=1"
{
"request": {
"params": {
"product_catalog_id": "1569782857975087104",
"count": 1
}
},
"next_cursor": "1569783561426976771",
"data": [
{
"id": "twitter-123",
"title": "Lorem ipsum dolor sit amet, clita invenire scriptorem vis ea, eu mea justo nulla platonem, eum postea sanctus ocurreret an.",
"availability": "in stock",
"condition": "new",
"price": "145.00 USD",
"link": "https://www.example.com",
"image_link": "https://pbs.twimg.com/profile_images/1354496336641417217/Cc2g7AwL_400x400.jpg",
"brand": "Twitter",
"gtin": null,
"mpn": "DJ9800-001",
"mobile_link": null,
"additional_image_link": null,
"google_product_category": null,
"product_type": "",
"inventory": null,
"sale_price": null,
"sale_price_effective_date": null,
"item_group_id": null,
"gender": null,
"color": null,
"size": null,
"age_group": null,
"custom_label_0": null,
"custom_label_1": null,
"custom_label_2": null,
"custom_label_3": null,
"custom_label_4": null,
"product_key": "1569783561426976770",
"item_group_key": null
}
]
}
Product Sets
The product_sets endpoint allows customers to sort products into groups based on product information. This grouping can be done manually or automatically via customizable filters, and the resulting product_sets will ultimately be what feeds into DPA creatives. As a reminder, product_sets must be associated with a particular Product Catalog.
Example Request
twurl -H ads-api.twitter.com "/12/product_catalogs/1569782857975087104/product_sets"
{
"request": {
"params": {
"product_catalog_id": "1569782857975087104"
}
},
"next_cursor": null,
"data": [
{
"name": "manual product set example",
"description": null,
"product_ids": [
"TWSHOES-22"
],
"processing_status": "DONE",
"id": "1573806483589849088",
"filters": [],
"type": "MANUAL"
},
{
"name": "filtered product set example",
"description": "price above 100 USD",
"product_ids": [
"twitter-123",
"TWSHOES-22"
],
"processing_status": "DONE",
"id": "1573831671954096128",
"filters": [
{
"attribute": "price",
"operator": "GREATER_THAN",
"value": "100.00 USD"
}
],
"type": "FILTERED"
}
]
}
To get started with catalog management, check out this overview documentation and our FAQs. For early access to the Catalog API, please fill in this form.
Please let us know if you have any questions and feedback or suggestions.
Twitter Ads API team
