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

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

latest_metadata

Latest product set metadata

live_metadata

Live product set metadata, which passed integrity review

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

retailer_id
string

Retailer's ID for the product set.

Edges

EdgeDescription

Automotive models in a product set

Destinations that belong to this product set

Flights that belong to this product set

Home listings that belong to this product set

Hotels that belong to this product set

Product items that belong to this product set

Vehicle offers that belong to this set

Vehicles that belong to this set

Error Codes

ErrorDescription
100Invalid 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

ParameterDescription
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

ErrorDescription
80004There 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.
10803Product set with the same filters already exists
100Invalid parameter
200Permissions 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

ParameterDescription
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

ErrorDescription
801Invalid operation
100Invalid parameter
200Permissions 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

FieldDescription

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.

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