Marketing API Version

Product Set

A Product Set is a set of products in a Product Catalog that you advertise in a dynamic ad. Each Product Catalog can have many Product Sets.

Reading

A Product Set object

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Examples

To get a list of all Product Sets, make an HTTP GET call to:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/product_sets

To get a Product Set, make an HTTP GET call to:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_SET_ID>

To get a list of Product Items in a Product Set, make an HTTP GET call to:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_SET_ID>/products

To get a list of Product Groups in a Product Set, make an HTTP GET call to:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_SET_ID>/product_groups
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription

id

numeric string

ID of the product set

auto_creation_url

string

URL scraped to create a product set

filter

string

The filter rule that defines the set of products in the catalog

name

string

The name given by the owner of this product set

product_catalog

Product catalog for this product set

product_count

unsigned int32

Count of products in this product set

Edges

EdgeDescription

da_checks

A list of results after running Dynamic Ads checks on this product set.

destinations

Destinations that belong to this product set

flights

Flights that belong to this product set

home_listings

Home listings that belong to this product set

hotels

Hotels that belong to this product set

products

Product items that belong to this product set

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.

Creating

Product Sets are defined by filters in a Product Catalog. You define a filter with Website Custom Audiences Rules Grammar.

Filter Rules

Creating a Product Set with an empty filter parameter indicates that all product items in the Product Catalog should be in the set. An empty filter parameter can be specified using either an empty parameter value or an empty JSON object, {}.

If the filter rules you set result in a Product Set with no products, ads tied to this empty Product Set will not deliver.

Filter rules are made up of the following operators and fields:

NameDescription

Operators

The type of filter.

and

Conjunction of a list of clauses

or

Disjunction of a list of clauses

i_contains

Contains substring (case insensitive)

i_not_contains

Does not contain substring (case insensitive)

contains

Contains substring (case sensitive)

not_contains

Does not contain substring (case sensitive)

is_any

Value is any of (case sensitive)

is_not_any

Value is not any of (case sensitive)

i_is_any

Value is any of (case insensitive)

i_is_not_any

Value is not any of (case insensitive)

eq

Equal to (case sensitive)

neq

Not equal to (case sensitive)

lt

Less than (numeric fields only)

lte

Less than or equal to (numeric fields only)

gt

Greater than (numeric fields only)

gte

Greater than or equal to (numeric fields only)

starts_with

Value starts with (case sensitive)

i_starts_with

Value starts with (case insensitive)

Data

The data being filtered.

age_group

The demographic of an item. There are only 5 accepted values: newborn, infant, toddler, kids, and adult.

availability

The availability of the product item. Only 4 predefined values: preorder, in stock, out of stock, and available for order.

brand

The brand of a product item

category

The category of the product item

color

The color of an item.

condition

The condition of the product item. There are only 3 accepted values: new, refurbished, and used.

currency

The currency abbreviation for an item's price.

custom_label_0

The value of a custom label of a product item.

custom_label_1

The value of a custom label of a product item.

custom_label_2

The value of a custom label of a product item.

custom_label_3

The value of a custom label of a product item.

custom_label_4

The value of a custom label of a product item.

gender

The gender of the product item. There are only 3 accepted values: male, female, and unisex.

material

The material or fabric that a product is made out of. For example, 'Leather', 'Denim', 'Suede'.

name

The name of a product item.

pattern

The pattern or graphic print featured on a product. For example, 'Polka Dot', 'Striped', 'Paisley'.

price_amount

The price multiplied by 100, for all currencies. For example, 490 when used with USD denotes $4.90, and 49000 when used with JPY denotes ¥490.

product_feed_id

The Facebook ID of the Product Feed of a product item

product_item_id

The Facebook ID of a product item

product_group_id

The Facebook ID of the Product Group of a product item

product_type

The retailer defined category of a product item

retailer_id

The retailer defined ID of a product item

retailer_product_group_id

The retailer defined ID of a product group

sale_price_amount

The sale price of a product item multiplied by 100, for all currencies. For example, 490 when used with USD denotes $4.90, and 49000 when used with JPY denotes ¥490.

size

The size of a product item. For example, 'XL', '16/34 Tall', '3.5 Kid'.

Each rule is a JSON encoded string.

Example Filter Rules

RuleDescription
{
  "category": {
    "eq": "Luggage & Bags > Backpacks"
  }
}

will match all the products with the category equal to "Luggage & Bags > Backpacks"

{
  "retailer_id": {
    "is_any": ["pid1", "pid2"]
  }
}

will match the products with retailer ID pid1 or pid2

{
  "or": [
    {
      "retailer_product_group_id": {
        "eq": "group_1"
      }
    },
    {
      "product_type": {
        "i_contains": "shirt"
      }
    }
  ]
}

will match all the products with the retailer_product_group_id equal to group_1 or product_type containing shirt

Examples

Create a product set that matches specific product IDs

curl \
-F "name=Sample Product Set" \
-F "filter={'retailer_id': {'is_any': ['pid1', 'pid2']}}" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/product_sets

Create a product set that matches all shirt items

curl \
-F "name=New Product Set Name" \
-F "filter={'product_type': {'i_contains': 'shirt'}}" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/product_sets
You can make a POST request to product_sets edge from the following paths:
When posting to this edge, a ProductSet will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • manage_pages
  • pages_show_list
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
filter
A JSON-encoded rule

Filter rules to define a product set (max length: 500 KB). The pair (filter, parent_id) must be unique inside a catalog

name
UTF-8 encoded string

Name of the product set

Required

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
294Managing advertisements requires an access token with the extended permission for ads_management

Updating

Examples

For an existing Product Set, you can update the filter by sending an HTTP POST to the product set ID:

curl \
-F "name=New Product Set Name" \
-F "filter={'product_type': {'i_contains': 'shirt'}}" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_SET_ID>
You can update a ProductSet by making a POST request to /{product_set_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
filter
A JSON-encoded rule

Filter rules to define a product set (max length: 500 KB)

name
UTF-8 encoded string

Name of the product set

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
294Managing advertisements requires an access token with the extended permission for ads_management

Deleting

You can delete a ProductSet by making a DELETE request to /{product_set_id}.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error