products

Products

These endpoints are currently available via early-access only. To apply for access, please fill out this form.

Twitter 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 subbmited 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

Request Parameters¶

Name Description

Name	Description
item_group_key optional	This is a Twitter-generated item group identifier. Type: string Example: `1573459926562705409`
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `100`
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `8x7v00oow`

item_group_key
optional

This is a Twitter-generated item group identifier.

Type: string

Example: 1573459926562705409

count
optional

Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 100
Min, Max: 1, 100

cursor
optional

Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow

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": "Twitter",
      "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.twitter.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.

Request Attributes¶

Name	Description
id 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. Type: string Example: `S654a`
product_key required	Unique product object identifier generated by Twitter. Type: string Example: `1557743648607010810`
title required Max character limit: 150 (open-text)	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. Type: string Example: `Twitter Blue Sneakers`
description required Max character limit: 5000 (open-text)	The description of the product. This field does not support HTML and must be in plain text. Type: string Example: `The first of its kind at Twitter, the Twitter Blue Sneaker is a sleek, fashionable athletic sneaker. Made of breathable soft cotton. Comes in the blue color, matching Twitter’s brand.`
availability required	Current availability of your item. Select one of the possible values from the list below. Type: enum Possible Values: `in stock` `available for order` `preorder` `out of stock` `discontinued`
condition required	Condition of the item being sold. Select one of the possible values from the list below. Type: enum Possible Values: `new` `used` `refurbished`
price required	Price of the item. Format the price as a number, followed by the 3-digit ISO currency code (ISO 4217 standards), with a space between cost and currency. Use a period (".") as the decimal point. Type: ISO 4217 Example: `99.99 USD`
link required	URL of the product page specific to the product where people can buy the item. If a user is on a mobile device, and a mobile_link is included, the viewing user will be sent to the url provided via the mobile_link attribute. We’ll validate the URL according to RFCs. Specifically it must include “https”. Type: string Example: `https://www.twitter.com/twtr_blue`
image_link required	URL for the primary image of your item. If you change the image later, the new image must use a different URL or the image will not update. Image specifications: - All images must be in JPG, GIF, WEBP, or PNG format. - We highly recommend product images are in square (1:1) format. - The minimum image size is 500 x 500 px. Image file size limit: 5 MB. Type: string Example: `https://t.co/demin_jeans_452.jpg`
brand Sometimes required Max character limit: 100	The brand name of the item. Required if a Global Trade Item Number (gtin) and Manufacturer Part Number (mpn) is not available, but encouraged to always include. Type: string Example: `Twitter`
gtin Sometimes required Max character limit: 100	The Global Trade Item Number (unique universal product identifier) of the item. This should be included when available, but is optional if mpn and/or brand is included. Enter the item's UPC, EAN, JAN, or ISBN. Type: string Example: `012345678901`
mpn Sometimes required	The Manufacturer Part Number of the item. Required if a Global Trade Item Number (gtin) and Manufacturer Part Number (mpn) is not available, but encouraged to always include if available. Type: string Example: `TW123456TTER`
mobile_link optional	URL of a mobile optimized version of the product page specific to the product where people can buy the item. If a user is on a mobile device, the viewing user will be sent to the url provided via the mobile_link attribute. We’ll validate the URL according to RFCs. Specifically it must include “https”. Type: string Example: `https://lite.twttr.com/twtr_blue`
additional_image_link optional	To add more images of your item, use additional_image_link. URLs should be comma separated. Follow the same specifications as mentioned in the image_link attribute. Include up to 10 additional images. Type: string Example: `https://t.co/jeans_1.jpg, https://t.co/jeans_2.jpg, https://t.co/demin_jeans_3.jpg`
google_product_category optional	The category of the item, according to Google's product taxonomy. Use the category's taxonomy path or its category ID number. Note that in some cases, this category will be shown to Twitter users. Type: string Example: `Electronics > Video Game Consoles` `1294`
product_type optional	The category the item belongs to, according to your business's custom product taxonomy, if you have one. You can also enter a Google product category (google_product_category). Subcategories must be sent separated by “ > “. The > must be wrapped by spaces. Note that in some cases, this category will be shown to Twitter users. Type: string Example: `Clothing > Men’s > Pants > Denim`
inventory optional	The quantity of this item that you have available to sell on Twitter. If included, an item’s inventory value must be 1 or higher when its availability field is set to in stock for the item to be shown to users. Otherwise, this value could be greater than or equal to 0 when its availability field is set to available for order, or preorder for the item to be shown to users. Type: int Example: `1000`
sale_price optional	The discounted price of the item. Format the price as a number, followed by the 3-digit ISO currency code (ISO 4217 standards), with a space between cost and currency. Use a period (".") as the decimal point. The sale_price must be lower than the price. Type: ISO 4217 Example: `80.99 USD`
sale_price_effective_date optional	Time range for the item’s sale period, including the date, time, and time zone when your sale starts and ends. If sale dates aren’t entered, any items with a sale_price will remain on sale until you remove their sale price. It is possible to provide just a start date without an end date, in which case the sale price will remain on sale from the start date until the sale price is removed.Start date must be before end date. Detailed instructions: 1) Type the start date as YYYY-MM-DD. 2)Type "T" after the start date. 3) Type the start time in a 24-hour format (00:00 to 23:59), followed by the UTC time zone (-12:00 to +14:00). 4) Type a "/" and then repeat the same format for the item’s sale end date and time. Type: ISO-8601 timestamps Example: `2020-06-28T09:00-08:00/2020-07-28T23:59-08:00`
item_group_id Sometimes required	Use the item_group_id attribute to group product variants together. Variants are a group of similar items that only differ from one another by product details like size, color, age_group, and gender. This field is required if your product has variants. Type: string Example: `twtrshoes1234_12`
item_group_key optional	This is a Twitter-generated item group id. Type: string Example: `1573525521559801856`
gender optional	Determines gender for item sizing. Select one of the possible values from the list below. Type: enum Possible Values: `female` `male` `unisex`
color optional	The primary color of the product. Use one or more words to describe the color. Don’t use a hex code. Type: string Example: `blue`
size optional	Size of the item written as a word, abbreviation or number. Type: string Example: `medium`
age_group optional	The associated age group of the item. Select one of the possible values from the list below. Type: enum Possible Values: `adult` `all ages` `teen` `kids` `toddler` `infant` `newborn`
custom_label_0 optional	Extra custom label Type: string Example: `Holiday Sale`
custom_label_1 optional	Extra custom label Type: string Example: `Holiday Sale`
custom_label_2 optional	Extra custom label Type: string Example: `Holiday Sale`
custom_label_3 optional	Extra custom label Type: string Example: `Holiday Sale`
custom_label_4 optional	Extra custom label Type: string Example: `Holiday Sale`

Response Parameters¶

Name	Description
warnings	Warnings about your request Type: array Example: `SALE_PRICE_TOO_HIGH`
errors	Error messages about your request Type: array Example: `Sale price must be lower than the price`
product_key	Unique product object identifier generated by Twitter. Type: string Example: `1573527897222000640`
id	Unique ID for the item. Use the SKU if possible. If there are multiple instances of the same ID, all instances will be ignored. Type: string Example: `S654a`
status	Status of your request Type: enum Example: `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.twitter.com/twtr_blue",
      "image_link": "https://www.kurzweilai.net/images/Naam-Limits-of-Earth-Part1-001-earth-600x600.jpg",
      "brand": "twitter",
      "gtin": "1432563728",
      "mpn": "3268793T",
      "mobile_link": "https://www.twitter.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/:catalog_id/products¶

Deleting existing products. Please note that this is a permanent deletion.

Request Parameters¶

Name Description

Name	Description
product_keys required	Unique product object identifier generated by Twitter. Type: string Example: `1547082514342088705`

product_keys
required

Unique product object identifier generated by Twitter.

Type: string

Example: 1547082514342088705

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