Graph API Version

Product Set

A product set is a group of related items in a product catalog.

Reading

A call to this endpoint returns Product Set data.

Examples

To get a product set, send a GET request:

curl -i -X GET "https://graph.facebook.com/PRODUCT-SET-ID?access_token=ACCESS-TOKEN"

Parameters

This endpoint doesn't have any parameters.

Fields

Field	Description
`id` numeric string	ID of the product set. Default
`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 Default
`latest_metadata` ProductSetMetadata	Latest product set metadata
`live_metadata` ProductSetMetadata	Live product set metadata, which passed integrity review
`name` string	The name given by the owner of this product set Default
`product_catalog` ProductCatalog	Product catalog for this product set
`product_count` unsigned int32	Count of products in this product set
`retailer_id` string	Retailer's ID for the product set. Default

Edges

Edge	Description
`automotive_models`	Automotive models in a 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
`vehicle_offers`	Vehicle offers that belong to this set
`vehicles`	Vehicles that belong to this set

Error Codes

Error	Description
100	Invalid parameter

Creating

You can't perform this operation on this endpoint.

Updating

Update an existing product set.

Example

To update a product set, send a POST request:

curl -i -X "https://graph.facebook.com/PRODUCT-SET-ID?name=Product Set Name,filter={'product_type': {'contains': 'shirt'}},access_token=ACCESS-TOKEN"

You can update a ProductSet by making a POST request to /{product_set_id}.

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
`name` UTF-8 encoded string	Name of the product set
`publish_to_shops` array<JSON object>	List of 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
80004	There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
10803	Product set with the same filters already exists
100	Invalid parameter
200	Permissions error

Deleting

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

By default a product set can not be deleted while it is being used in an active ad, shop collection, or other usages. To override this behavior, include allow_live_product_set_deletion=true in your request.

Parameters

Parameter Description

Parameter	Description
`allow_live_product_set_deletion` boolean	Default value: `false` Flag to allow the deletion of live product set

allow_live_product_set_deletion

boolean

Default value: false

Flag to allow the deletion of live product set

Return Type

Struct {

success: bool,

}

Error Codes

Error	Description
801	Invalid operation
100	Invalid parameter
200	Permissions error

Filter Rules

Creating a product set with an empty filter parameter indicates that all items in the product catalog should be in the set. Each rule is a JSON-encoded string. An empty filter parameter can be specified using either an empty parameter value or an empty JSON object, {}.

Recommendation: Query with content type application/json.

Limitations

If the filter rules you set result in an empty product set, ads tied to this 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.
The contains operators can only be used for string matching when creating product sets. For enum values use the eq operators.
Filter operators are not case sensitive. However, i_* operators can still be used.

Filter rules contain fields and operators in the following syntax:

curl -i -X POST "https://graph.facebook.com/PRODUCT-SET-ID?
    name=Product Set Name,
    filter={'field-name': {'operator-type': 'query-value'}},
    access_token=ACCESS-TOKEN"

Fields

Field	Description
`age_group` enum {adult, infant, kids, newborn, toddler}	The target age group for an item.
`agent_fb_page_id` int	The Facebook Page ID for the real estate agent.
`availability` Home Listings – For Dynamic Ads enum {available_soon, for_sale, for_rent, off_market, recently_sold, sale_pending} Home Listings – For Marketplace enum {for_rent} Product Items enum {available for order, in stock, preorder, out of stock} Vehicles enum {available, not_available}	The availability for an item, home listing, or vehicle. Note: Vehicles that are unavailable in an ad are not visible to the public.
`base_price_amount` int	The base price per night for a hotel. `base_price` and `base_price_currency` are required.
`body_style` enum {CONVERTIBLE, COUPE, CROSSOVER, HATCHBACK, MINIVAN, TRUCK, SEDAN, SMALL_CAR, SUV, VAN, WAGON, OTHER}	The body style of a vehicle. For Marketplace and dynamic ads.
`brand` string	The brand of a product item or hotel.
`category` string	The category of the product item.
`city` string	The city where a hotel, destination, automobile dealership, or home listing is located.
`city_id` int	The city ID where a hotel, destination, automobile dealership, or home listing is located.
`city_page_id` string	The value to use in a deep link URL (`template_URL`) in ad creative.
`color` string	The color of an item.
`condition` For Product Items enum {new, refurbished, used} For Vehicles enum {Excellent, Good, Fair, Poor, Other}	The condition of a product item or vehicle.
`country` string	The country where a hotel, home listing, automobile dealership, or destination is located.
`currency` string	The alpha currency code.
`custom_label_0` string	The value for a custom label of a product item, hotel, destination, vehicle, or home listing.
`custom_label_1` string	The value for a custom label of a product item, hotel, destination, vehicle, or home listing.
`custom_label_2` string	The value for a custom label of a product item, hotel, destination, vehicle, or home listing.
`custom_label_3` string	The value for a custom label of a product item, hotel, destination, vehicle, or home listing.
`custom_label_4` string	The value for a custom label of a product item, hotel, destination, vehicle, or home listing.
`date_first_on_lot` string	The date a vehicle first arrived at the dealership in YYYY-MM-DD format. For example, 2018-09-05.
`date_first_on_lot_time` string	The date and time a vehicle first arrived at the dealership.
`days_on_market` int	The number of days a home listing has been on the open market.
`dealer_communication_channel` enum {CHAT, LEAD_FORM}	The method which an automobile dealer will use to contact a buyer. `LEAD_FORM` is subject to regional availability and defaults to `CHAT` when not available.
`dealer_id` string	The alphanumeric ID for an automobile dealership.
`dealer_name` string	The name for the automobile dealership.
`drivetrain` enum {4X2, 4X4, AWD, FWD, RWD, Other}	The drivetrain for a vehicle.
`description` string	The description for a flight, home listing, or destination.
`destination_airport` string	The IATA code for the destination airport. For example, HKG, LAX, or LHR.
`destination_city` string	The name of the destination city. For example, London, New York, or Tokyo.
`destination_id` string	The unique ID for a destination within a catalog. This ID is also used for the `content_id` parameter in your destination app and pixel events.
`exterior_color` string	The exterior color for a vehicle.
`feed_id` string	The Facebook ID for the feed in which the product belongs.
`flight_id` string	The unique ID for a flight.
`fuel_type` enum {DIESEL, ELECTRIC, GASOLINE, FLEX, HYBRID, OTHER}	The type of fuel designated for a vehicle.
`furnish_type` enum {furnished, semi-furnished, unfurnished}	The type of furnishing available for a home listing.
`gender` enum {female, male, unisex}	The gender for the product item.
`home_listing_id` string	The unique ID for a home listing.
`hotel_id` string	The unique ID for a hotel within a catalog. This ID is also used for the `content_id` parameter in your hotel app and pixel events.
`image_tags` string	URLs and tags to describe images that are used in ads. Multiple tags can be associated with an image. For example, "Fitness Center", "Swimming Pool", or "Parking". For vehicles, follow this naming convention: `(image[0].url`, `image[0].tag[0]`, `image[0].tag[1])` where the tag value is incremented for each additional tag. When using a CSV/TSV file, use either an image header, `image[0].url`, `image[1].url`, and so on, or a JSON flatten string, `"[{url:'https://images.com/1.jpg'},{url:'https://images.com/2.jpg'}]"`.
`interior_color` string	The interior color for a vehicle.
`listing_type` For Dymanic Ads enum {for_rent_by_agent, for_rent_by_owner, for_sale_by_agent, for_sale_by_owner, foreclosed, new_construction, new_listing} For Marketplace enum {for_rent_by_agent, for_rent_by_owner}	The type of listing for a home.
`make` string	The brand of a vehicle. For example, Ford, Toyota, or Kia.
`margin_level` int	An indicator for the profitability of a hotel from `1` to `10`.
`market_id` int	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` string	The material or fabric that a product is made of such as cotton, denim, or nylon.
`mileage_unit` enum {KM, MI}	The mileage unit of a vehicle in kilometers or miles.
`mileage_value` int	The current mileage for a vehicle, in miles or kilometers. For new vehicles, use `0`. Vehicles on Marketplace must have over 500 miles or kilometers.
`model` string	The model for a vehicle such as "Ford Focus" where "Focus" is the model.
`name` string	The name for a product item, hotel, home listing, or destination.
`neighborhood` string	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` string	The neighborhood ID for a product item.
`num_baths` int	The total number of bathrooms for a home listing. Must be `1` at a minimum.
`num_beds` int	The total number of bedrooms for a home listing. Can be `0` for a studio.
`number_of_raters` int	The number of people who rated a hotel.
`num_of_valid_guest_rating` string	Total number ratings for a hotel made by valid guests.
`num_rooms` int	The total number of rooms for a home listing.
`num_units` int	The total number of units available in an apartment or condo building.
`offer_type` enum {cash, finance, lease}	The type of offer for a home listing or vehicle.
`one_way_price` string	One-way price for a flight. The currency must be specified, for example, `99.99 USD`.
`origin_airport` string	The IATA code for the airport where the flight originated.
`origin_city`	The name of the city where the flight originated.
`pattern` string	The pattern or graphic print featured on a product. For example, "solid", "striped", or "polka dots".
`postal_code` int	The postal or zip code for a hotel, home listing, or automobile dealership location. Optional for countries without a postal code system.
`postal_codes` list	A list of postal codes for a specific market for vehicle offer ads.
`price` float	The price for a flight, home listing, vehicle, or destination. The `currency` field is required.
`price_amount` int	The price multiplied by 100, for all currencies. For example, $4.90USD will be `490` and ¥490JPY will be `49000`.
`price_change` string	The price change for a destination. For example, `0` for no price change, `–10` for a 10% price decrease, and `20` for a 20% price increase.
`priority` int	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 date and time when the product is no longer available. Ads will only fetch products that have not expired. For example, if the expiration date is today, after today this product will no longer appear in ads.
`product_feed_id` int	The Facebook ID for the product feed for a product item, flight, hotel, home listing, vehicle, vehicle offer, or destination.
`product_group_id` int	The Facebook ID for the product group of a product item.
`product_item_id` int	The Facebook ID for a product item.
`product_type` string	The category for a product item defined by the retailer.
`property_type` For Dynamic Ads enum {apartment, condo, house, land, manufactured, townhouse, other} For Marketplace enum {apartment, builder_floor, condo, house, house_in_condominium, house_in_villa, loft, penthouse, studio, townhouse, other}	The property type for a home listing.
`rating_system` string	The rating system used for `guest_rating`. For example, "Expedia", or "TripAdvisor".
`region` string	The state, county, region, or province for a home listing or automobile dealership.
`region_id` unsigned int32	The region ID for the location for a product item or automobile dealership.
`retailer_id` string	The ID for the retailer.
`retailer_product_group_id` int	The ID for a product group defined by the retailer.
`sale_price` int	The sale price or special price for a vehicle.
`sale_price_amount` int	The sale price for a product item (same format as `price_amount`). For hotels, the discounted sale price for a hotel stay, based on `checkin_date` and `length_of_stay`.
`score` float	The rating score for a hotel.
`size` string	The size for a product item such as for clothing or shoes.
`star_rating_float` float	The star rating for a hotel.
`state_of_vehicle` enum {New, Used, CPO}	The current state of a vehicle.
`title` string	The full name for a vehicle including year, make, model, and trim. Maximum of 500 characters. For example, `2014 Nissan Versa Note S Hatchback 4D`.
`transmission` enum {Automatic, Manual}	The transmission type for a vehicle.
`trim` string	The trim for a vehicle: `5DR HB SE` Max characters: 50.
`url` string	The link to an external site where you can view a flight. Deep links specified on the ad level take precedence.
`vehicle_ID` int	The unique ID for a vehicle. This ID is also used for the `content_id` parameter in the pixel. If the same ID is used in multiple instances, all instances are ignored. For vehicle offers, it is the ID that advertisers can use to identify an offer.
`vehicle_registration_plate` string	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 Brazil, France, and the United Kingdom.
`vehicle_type` enum {car_truck, boat, commercial, motorcycle, powersport, rv_camper, trailer, other}	The type of vehicle. `car_truck` is the default value.
`vendor_ID` int	The ID for a vendor.
`vin` int	The vehicle identification number. The VIN must be exactly 17 characters and is required in all countries where Marketplace is available with the exception of pre-1983 vehicles. In Brazil, France, and the United Kingdom, a vehicle registration plate is required instead of a VIN.
`visibility` enum {published, staging, hidden, whitelist_only}	Visibility for a product item. Items in `staging` mode are not visible to buyers and are not available for product tagging on Instagram or in dynamic ads.
`year` int	The model year for a vehicle, in YYYY format.

Operators

Starting March 3, 2022, we have changed how certain filters work for product sets. These include the contains, not_contains, lt, gt, lte, gte, and starts_with filters. You have 90 days to update your filters. If any sets in your catalog are using the affected filters after June 1, 2022, the items in those sets may change. This means that different items could display in your ads or shops that use those sets. See the changelog for more details.

Operator	Type of filter
`and`	Returns products that match all query values inclusively. For example, `"color": {"red" and "shoe" and "running"}` will only return products that match all 3 query values, such as "red running shoe".
`contains`	Returns products that match a query string. For example, `category: {"contains": "running shoe"}` will return all products that contain the query string, such as "red running shoe", "blue running shoe", and "running shoe for kids".
`or`	Returns products that match only one query value exclusively. For example, `category: {"running" or "walking"}` will return products that match "running" or "walking" but not both.
`not_contains`	Returns products that do not match a query string. For example, `category: {"not_contains": running shoe"}` will return all products that do not contain the query string, such as "red walking shoe", "sandals", and "boots".
`is_any`	Returns products that match any value in a list of query values. For example, `"color": {"is_any": "black", "blue", "brown"}` will return any product that matches at least one query string, such as "black boots", "blue boots", "brown boots".
`is_not_any`	Returns products that do not match any value in a list of query strings. For example, `"color": {"is_not_any": "black", "blue", "brown"}` will return any products that do not match any of the query values, such as "red boots", "yellow boots", and "green boots".
`eq`	Returns products that exactly match a query value. For example, `"brand": {"eq": "Instagram"}` will only match "Instagram" brand products.
`neq`	Returns products that do not exactly match a query value. For example, `"brand": {"eq": "Instagram"}` will only match products that are not "Instagram" brand products.
`lt` int	Returns products that are less than a numeric query value. For example, `"priority": {"lt": 3}` will only match products with a priority that is less than 3.
`lte` int	Returns products that are less than or equal to a numeric query value. For example, `"priority": {"lte": 3}` will only match products with a priority that is less than or equal to 3.
`gt` int	Returns products that are greater than a numeric query value. For example, `"priority": {"gt": 3}` will only match products with a priority that is greater than 3.
`gte` int	Returns products that are greater than or equal to a numeric query value. For example, `"priority": {"gte": 3}` will only match products with a priority that is greater than or equal to 3.
`starts_with`	Returns products that match any string that starts with the query string. For example, `"small"` will return any product that starts with the query string, such as "small sandals", "small t-shirt", "small, blue boots".

Filter Examples

The following example creates a product set with all products listed in the Luggage & Bags category in the product catalog.

Formatted for readability.

curl -i -X POST "https://graph.facebook.com/PRODUCT-CATALOG-ID/product_sets
    ?name=Product Set Name
    &filter={'category': {'eq': 'Luggage & Bags'}}
    &access_token=ACCESS-TOKEN"

The following example creates a product set with all shirts listed the product catalog.

Formatted for readability.

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