Product Sets
product-sets

Product Sets

Run in Postman ❯ 

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

Product Sets are collections of products which represent a subset of your catalog, e.g. “Fall Sale Products”. You’ll have the option to 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 some or all Product Sets associated with the specified Product Catalog.

Resource URL

https://ads-api.x.com/12/product_catalogs/:product_catalog_id/product_sets/:product_set_id

Request Parameters

Name Description
product_set_id
optional

Unique ID for product set

Type: string

Example: 1547082514342088705

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

Creating a new product set

Request Parameters

Name Description
name
required

Name of product set.

Type: string

Example: My product set
description
optional

Description of product sets.

Type: string

Example: My special product set
type
required

Type of filters.

Type: enum

Possible values: MANUAL, FILTERED
filters
sometimes required

If FILTERED is selected in type, the filters attribute needs to be set. Available filters are price, product type, Google Product Category, sale price, inventory, and custom labels.

Type: array of objects

Each object contains three keys:

attribute:

Possible Values: google_product_category, product_type, inventory, price,custom_label_0,custom_label_1,custom_label_2,custom_label_3,custom_label_4,sale_price

operator:

Possible Values: GREATER_THAN , EQUAL_TO , LESS_THAN, MATCH,NOT_CONTAINS,CONTAINS

value

Example:

{"attribute": "price", "operator": "GREATER_THAN", "value": "100.00 USD"}

{"attribute": "custom_label_0", "operator": "MATCH", "value": "test"}
product_keys
sometimes required

If MANUAL is selected in type, the product_keys attribute needs to be set. Please note that these are Twitter generated IDs.

Type: array (Input as a comma-separated list of IDs in the query param)

Example: ["1557743648607010810","1357743648607310814"]

Response Parameters

Name Description
processing_status

Status of product set when you apply FILTERED type

Type: enum

Possible values: DONE, PROCESSING,FAILED

Example Request for 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 for 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": "FILTER"
  }
}

     

PUT product_catalogs/:product_catalog_id/product_sets/:product_set_id

Updating existing product set

Request Parameters

Name Description
product_keys
optional

Unique product object identifier generated by Twitter.

Type: array

Example: ["1576768397127606272","1547080787865939969"]
product_set_id
required

Unique ID for product set

Type: string

Example: 1547082514342088705
name
optional

Name of product set.

Type: string

Example: My product set
description
optional

Description of product sets.

Type: string

Example: My special product set

Note: Updating FILTERED product sets is not available. Below example is for MANUAL product set update.

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

Deleting an existing product set. Please note that this is a permanent deletion.

Request Parameters

Name Description
product_set_id
required

Unique ID for product set

Type: string

Example: 1547082514342088705

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