Graph API Version

Product Catalog Product Sets

Reading

Product sets that are in the Catalog

Example

GET /v19.0/{product-catalog-id}/product_sets HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{product-catalog-id}/product_sets',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{product-catalog-id}/product_sets",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{product-catalog-id}/product_sets",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();

/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{product-catalog-id}/product_sets"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

Parameter	Description
`ancestor_id` numeric string or integer	Filters out only product sets which are descendant of the specified product set
`has_children` boolean	Filters out based on if the product set has any child
`parent_id` numeric string or integer	Filters out only Product Sets which are direct children of the specified parent in the hierarchy (0 means "root Product Sets")
`retailer_id` UTF-8 encoded string	Filters out based on the product set's retailer id

Fields

Reading from this edge will return a JSON formatted result:

{
    "data": [],
    "paging": {},
    "summary": {}
}

`data`

A list of ProductSet nodes.

`paging`

For more details about pagination, see the Graph API guide.

`summary`

Aggregated information about the edge, such as counts. Specify the fields to fetch in the summary param (like summary=total_count).

Field Description

Field	Description
`total_count` int32	Total number of objects on this edge Default

total_count

int32

Total number of objects on this edge

Default

Error Codes

Error	Description
100	Invalid parameter
368	The action attempted has been deemed abusive or is otherwise disallowed
2500	Error parsing graph query

Creating

You can make a POST request to product_sets edge from the following paths:

/{product_catalog_id}/product_sets

When posting to this edge, a ProductSet will be created.

Example

Graph API Explorer

POST /v19.0/<PRODUCT_CATALOG_ID>/product_sets HTTP/1.1
Host: graph.facebook.com

name=Test+Set&filter=%7B%22product_type%22%3A%7B%22i_contains%22%3A%22shirt%22%7D%7D

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/<PRODUCT_CATALOG_ID>/product_sets',
    array (
      'name' => 'Test Set',
      'filter' => '{"product_type":{"i_contains":"shirt"}}',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/<PRODUCT_CATALOG_ID>/product_sets",
    "POST",
    {
        "name": "Test Set",
        "filter": "{\"product_type\":{\"i_contains\":\"shirt\"}}"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Bundle params = new Bundle();
params.putString("name", "Test Set");
params.putString("filter", "{\"product_type\":{\"i_contains\":\"shirt\"}}");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/<PRODUCT_CATALOG_ID>/product_sets",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();

NSDictionary *params = @{
  @"name": @"Test Set",
  @"filter": @"{\"product_type\":{\"i_contains\":\"shirt\"}}",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/<PRODUCT_CATALOG_ID>/product_sets"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

curl -X POST \
  -F 'name="Test Set"' \
  -F 'filter={
       "product_type": {
         "i_contains": "shirt"
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<PRODUCT_CATALOG_ID>/product_sets

If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

Parameter	Description
`filter` A JSON-encoded rule	Filter rules to define a product set (max length: 500 KiB)
`metadata` JSON object	Product set metadata, which can be used for creating product collections
`cover_image_url` URI	cover_image_url
`description` string	description
`external_url` URI	external_url
`external_url_handle` string	external_url_handle
`name` UTF-8 encoded string	Name of the product set Required
`publish_to_shops` array<JSON object>	Shop ids where this product set should be published as collection.
`shop_id` shop ID	shop_id
`ordering_index` int64	ordering_index
`retailer_id` UTF-8 encoded string	External product set retailer id

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: numeric string,

}

Error Codes

Error	Description
100	Invalid parameter
10803	Product set with the same filters already exists
368	The action attempted has been deemed abusive or is otherwise disallowed
200	Permissions error

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.

Filter Rules

Creating a product set with an empty filter parameter indicates that all 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, {}.

Limitations

If the filter rules you set result in a Product Set with no products, ads tied to this empty Product Set will not deliver.
A search will only sample 1% of a catalog. For catalogs with a large number of products, only 1% of products will be searched.

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

Operator	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)

Field	Description
`age_group`	The demographic of an item. There are only 5 accepted values: `newborn`, `infant`, `toddler`, `kids`, and `adult`.
`agent_fb_page_id`	Unique ID of the agent.
`availability`	The availability of the product item, home listing, or vehicle. Predefined values for products: `preorder`, `in stock`, `out of stock`, and `available for order`. Supported values for dynamic ads: `for_sale`, `for_rent`, `sale_pending`, `recently_sold`, `off_market`, `available_soon`. Supported value for Marketplace: `for_rent`. Supported values for vehicles: `available`, `not_available`. Note: Vehicles that are unavailable in an ad are not visible to public.
`base_price_amount`	The base price per night for a hotel. You must specify the value with currency. `base_price_amount` is the value of `base_price`. `base_price_currency` is the currency for the `base_price`.
`body_style`	The body style of a vehicle. Supported values for Marketplace and dynamic ads: `CONVERTIBLE`, `COUPE`, `CROSSOVER`, `HATCHBACK`, `MINIVAN`, `TRUCK`, `SEDAN`, `SMALL_CAR`, `SUV`, `VAN`, `WAGON`, `OTHER`.
`brand`	The brand of a product item or hotel.
`category`	The category of the product item.
`city`	The city where a hotel, destination, automobile dealership, or home listing is located.
`city_id`	The city ID of the product item.
`city_page_id`	The value to use in a deep link URL (`template_URL`) in ad creative.
`color`	Type: string. The color of an item.
`condition`	The condition of a product item or vehicle. Supported values for products: `new`, `refurbished`, and `used`. Supported values for vehicles: `Excellent`, `Good`, `Fair`, `Poor`, `Other`.
`country`	The country where a hotel, home listing, automobile dealership, or destination is located.
`currency`	The currency abbreviation for an item's, hotel's, home listing's, automobile dealership's, or destination's price.
`custom_label_0`	The value of a custom label of a product item, hotel, destination, vehicle, or home listing.
`custom_label_1`	The value of a custom label of a product item, hotel, or destination.
`custom_label_2`	The value of a custom label of a product item, hotel, or destination.
`custom_label_3`	The value of a custom label of a product item, hotel, or destination.
`custom_label_4`	The value of a custom label of a product item, hotel, or destination.
`date_first_on_lot`	The date a vehicle first arrived at the dealership. Used to indicate the inventory age. Should be in yyyy-mm-dd format. Example: `2018-09-05`
`date_first_on_lot_time`	The date and time a vehicle first arrived at the dealership.
`days_on_market`	The number of days a home listing is on the open market.
`dealer_communication_channel`	The method with which an automobile dealer will be contacted by a buyer. Supported values: `CHAT` or `LEAD_FORM`. `LEAD_FORM` is subject to regional availability: when unavailable, every listing is forced to `CHAT`, irregardless of the value entered.
`dealer_id`	The alphanumeric ID of an automobile dealership.
`dealer_name`	The name of the automobile dealership.
`drivetrain`	The vehicle's drivetrain. Supported values: `4X2`, `4X4`, `AWD`, `FWD`, `RWD`, `Other`.
`description`	The description of a flight route, home listing, or destination.
`destination_airport`	The IATA code for the destination. Supports airport and city IATA code. Use IATA Code Search to validate IATA codes. To improve performance, avoid using a space for this unique ID.
`destination_city`	The name of the destination city. Example: `New York`
`destination_id`	The unique ID for a destination within a catalog. This ID will be matched with any `content_ids` provided in your `destination` app and pixel events.
`exterior_color`	The exterior color of a vehicle
`feed_id`	The ID of the product feed from which the item came.
`flight_id`	The defined ID for a flight.
`fuel_type`	The type of fuel designated for a vehicle. Supported values: `DIESEL`, `ELECTRIC`, `GASOLINE`, `FLEX`, `HYBRID`, `OTHER`.
`furnish_type`	The type of furnishing available for a home listing: `furnished`, `unfurnished`, `semi-furnished`.
`gender`	The gender of the product item. There are only 3 accepted values: `male`, `female`, and `unisex`.
`home_listing_id`	The granular nique ID for a home listing (apartment, condo, home).
`hotel_id`	The unique ID for a hotel within a catalog. This ID is matched with any `content_ids` provided in your hotel app and pixel events.
`image_tags`	A string that describes an image. There can be multiple tags associated with an image. Example: [for home listings]`Fitness Center`, `Swimming Pool`, [for vehicles] `Exterior`, `Interior`, `StockImage`. For vehicles, follow this naming convention: `(image[0].url`, `image[0].tag[0]`, `image[0].tag[1])`. For vehicle offer ads, `Lease Offer`, `Financing`, and so on. In the `image[0].tag[m]` structure, increment the `m` value to add more tags. When using a CSV/TSV file, we support two different formats: Use an image header that looks like: `image[0].url`, `image[1].url`, and so on. Use a JSON flatten string that looks like: `"[{url:'https://images.com/1.jpg'},{url:'https://images.com/2.jpg'}]"`
`interior_color`	The vehicle's interior color.
`listing_type`	The type of home listing. Supported values for Marketplace: `for_rent_by_agent`, `for_rent_by_owner`. Supported values for dynamic ads: `for_rent_by_agent`, `for_rent_by_owner`, `for_sale_by_agent`, `for_sale_by_owner`, `foreclosed`, `new_construction`, `new_listing`.
`make`	The brand of a vehicle. Example `Ford`
`margin_level`	An indicator of the profitability of a hotel; value from `1` to `10`.
`market_id`	The market where an offer is eligible. Use for TWO FEED use case, to correspond with the market feed. For regional offers, this field is required and should match the `market_id` provided in the market feed. For national offers (offers applicable to all of the U.S.), this field should be empty.
`material`	The material or fabric that a product is made out of. Example: 'Leather', 'Denim', 'Suede'.
`mileage_unit`	The mileage unit of a vehicle in miles (`MI`) or kilometers (`KM`).
`mileage_value`	For used vehicles, the current mileage of a vehicle in miles (`MI`) or kilometers (`KM`). For new vehicles, use `0`. Vehicles on Marketplace must have over 500 miles/kms.
`model`	The name of a vehicle product and sometimes a range of products. Example: `Focus`
`name`	The name of a product item, hotel, home listing, or destination.
`neighborhood`	The neighborhood where a hotel or home listing is located. If there's more than one neighborhood, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of neighborhoods.
`neighborhood_id`	The neighborhood ID of a product item.
`num_baths`	The total number of bathrooms for a home listing. Must be `1` at a minimum.
`num_beds`	The total number of bedrooms for a home listing. Can be `0` for a studio.
`number_of_raters`	The number of people who rated a hotel.
`num_of_valid_guest_rating`	Number of starts the hotel has; for example, when you book a hotel and it has a rating that is 9 out of 10.
`num_rooms`	The total number of rooms for a home listing.
`num_units`	The total number of units in a building. Use only for apartments or condos, available as a rental.
`offer_type`	The type of offer: `lease`, `finance`, `cash`.
`one_way_price`	One-way price of a flight. You must specify the value with the currency.
`origin_airport`	The IATA code for the origin of an airport. Supports airport and city IATA codes. Use IATA Code Search to validate IATA codes.
`origin_city`	The city name of the flight's origin.
`pattern`	The pattern or graphic print featured on a product. Example: 'Polka Dot', 'Striped', 'Paisley'.
`postal_code`	The postal or zip code designated for a hotel location, home listing, or automobile dealership. Optional for countries without a postal code system.
`postal_codes`	For vehicle offer ads, the list of postal codes for the specific market provided in this format: `['94025', '94536']`.
`price`	The price of a flight, home listing, vehicle, or destination. You must specify the value with currency.
`price_amount`	The price multiplied by 100, for all currencies. Example: `490` when used with USD denotes $4.90, and `49000` when used with JPY denotes ¥490.
`price_change`	The price change for a destination. Values include: `0` - no price change, `–10` - 10% price drop, `20` - 20% price increase.
`priority`	The priority of a flight or hotel. Values from `0` (lowest priority) to `5` (highest priority). A flight without a value defaults to `0`.
`product_expiration_time`	The expiration date when the product is no longer available. You can set an expiration date and if you have an ad running, it will fetch only the non-expired products. For example, if the expiration date is today, after today this product will no longer appear in ads.
`product_feed_id`	The Facebook ID of the Product Feed of a product item, flight, hotel, home listing, vehicle, vehicle offer, or destination.
`product_group_id`	The Facebook ID of the Product Group of a product item.
`product_item_id`	The Facebook ID of a product item.
`product_type`	The retailer defined category of a product item.
`property_type`	The type of home listing property. Supported values for Marketplace: `apartment`, `builder_floor`, `condo`, `house`, `house_in_condominium`, `house_in_villa`, `loft`, `penthouse`, `studio`, `townhouse`, `other`. Supported values for dynamic ads: `apartment`, `condo`, `house`, `land`, `manufactured`, `townhouse`, `other`.
`rating_system`	The system the `guest_rating` is based on. Examples: Expedia, TripAdvisor
`region`	The state, county, region, or province for a home listing or automobile dealership.
`region_id`	The region-defined ID of a product item or automobile dealership.
`retailer_id`	The retailer-defined ID of a product item, flight, hotel, home listing, vehicle, vehicle offer, or destination.
`retailer_product_group_id`	The retailer defined ID of a product group.
`review_status`	This is related to dynamic review. It tells if the product is accepted or rejected in review. Values can be `rejected`, `pending`, `approved`.
`sale_price`	The sale price or special price of a vehicle.
`sale_price_amount`	For products: The sale price of a product item multiplied by 100, for all currencies. Example: `490` when used with USD denotes $4.90, and `49000` when used with JPY denotes ¥490. For hotels: Discounted sale cost and currency of a hotel stay, based on `checkin_date` and `length_of_stay`.
`score`	Value for the hotel rating score. Example: `7.8`
`size`	The size of a product item. Example: 'XL', '16/34 Tall', '3.5 Kid'
`star_rating_float`	The hotel star rating. Valid values: `1` to `5` and should be a multiple of 0.5. Example: `3`, `4.5`
`state_of_vehicle`	The current state of a vehicle: `New`, `Used`, `CPO` (certified pre-owned).
`title`	The full name of a vehicle. Max characters: 500. The title is relevant and specific to each vehicle and it should contain what is set in `year`, `make`, `model`, and `trim` fields. Example: `SE Ford Certified and 6-Speed Automatic`
`transmission`	The transmission type of the vehicle: `Automatic` or `Manual`.
`trim`	The trim of the vehicle: `5DR HB SE` Max characters: 50.
`url`	The link to an external site where you can view a flight. If a deep link is specified on the ad level, that takes precedence.
`vehicle_ID`	The unique ID for a vehicle. Can be a variant for a vehicle. If there are multiple instances of the same ID, we ignore all instances. For vehicle offers, it is the ID that advertisers can use to identify an offer. This is also the same value that is passed under the `content_id` parameter in the pixel.
`vehicle_registration_plate`	A metal or plastic plate attached to a motor vehicle or trailer for official identification purposes. For Marketplace, a vehicle registration plate is required in the United Kingdom,
`vehicle_type`	The type of vehicle: `car_truck` (default if not supplied), `boat`, `commercial`, `motorcycle`, `powersport`, `rv_camper`, `trailer`, or `other`.
`vendor_ID`	The vendor-defined ID of a product item.
`vin`	The vehicle identification number. The VIN must be exactly 17 characters and is not required for pre-1983 vehicles. The VIN is required in all countries where Marketplace is available. In the United Kingdom, France, and Brazil, a vehicle registration plate is required instead of a VIN.
`visibility`	Toggle visibility on product item. Supported values: `published`, `staging`, `hidden`, `whitelist_only`. Items in `staging` mode are not visible to buyers, and are not available for product tagging on Instagram, nor for dynamic ads.
`year`	The year a vehicle was launched in `yyyy` format.

Filter Examples

Formatted for readability.

To create a product set that matches specific product IDs, send a POST request to the /PRODUCT-CATALOG-ID/product_sets endpoint and set the retailer_id filter field to is_any operator and an array of product IDs.

curl -i -X POST

"https://graph.facebook.com/API-VERSION/PRODUCT-CATALOG-ID/product_sets

?name=Sample Product Set
&filter={
'retailer_id': {
'is_any': ['pid1', 'pid2']
}
}
&access_token=ACCESS-TOKEN"

To create a product set that matches all shirt items, send a POST request to the /PRODUCT-CATALOG-ID/product_sets endpoint and set the product_type filter field to i_contains operator and the string shirt.

curl -i - X POST
"https://graph.facebook.com/API-VERSION/PRODUCT-CATALOG-ID/product_sets
&name=New Product Set Name
&filter={
'product_type': {
'i_contains': 'shirt'
}
}
&access_token=ACCESS-TOKEN"

Each rule is a JSON-encoded string.

Recommendation: Query with content type application/json.

Example Filter Rules

Rule	Description
`{"category": {"eq": "Luggage & Bags"}}`	Match all products within the "Luggage & Bags" category.
`{"retailer_id": {"is_any": ["pid1", "pid2"]}}`	Match all products with the retailer ID of pid1 or pid2.
`{ "or": [{"retailer_product_group_id": {"eq": "group_1"}},{"product_type": {"i_contains": "shirt"}}]}`	Match all products with the `retailer_product_group_id` of group_1 or `product_type` containing shirt.