Represents a catalog for your business you can use to deliver ads with dynamic ads.
Example — View all product catalogs associated to your business
curl -G \ -d "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/owned_product_catalogs"
You can associate pixels and apps with a product catalog and then display products in ads based on signals from pixels or apps.
Example — Make an HTTP POST
curl \ -F 'external_event_sources[0]=<PIXEL_ID>' \ -F 'external_event_sources[1]=<APP_ID>' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<VERSION>/<PRODUCT_CATALOG_ID>/external_event_sources
You need the appropriate Marketing API Access Level and must accept the Terms of Service by creating your first catalog through Business Manager.
Product catalogs contain a list of items like products, hotels or flights, and the information needed to display them in dynamic ads
Parameter | Description |
---|---|
segment_use_cases array<enum {AFFILIATE_SELLER_STOREFRONT, AFFILIATE_TAGGED_ONLY_DEPRECATED, COLLAB_ADS, COLLAB_ADS_FOR_MARKETPLACE_PARTNER, COLLAB_ADS_SEGMENT_WITHOUT_SEGMENT_SYNCING, DIGITAL_CIRCULARS, FB_LIVE_SHOPPING, IG_SHOPPING, IG_SHOPPING_SUGGESTED_PRODUCTS, MARKETPLACE_SHOPS, TEST}> | segment_use_cases |
Field | Description |
---|---|
id numeric string | ID of a catalog |
business | Business that owns a catalog |
da_display_settings | Image display settings such as background cropping and padding of items in the catalog for different Dynamic Ad formats |
default_image_url string | The URL for the default image, which is used for products without images, or when the product image is temporarily unavailable. If a product image matches the default image, this should be treated as if the image was not loaded |
fallback_image_url list<string> | The URL for the fallback image. This is used as the image for auto-generated dynamic items |
feed_count int32 | The total number of feeds used by a catalog |
is_catalog_segment bool | Verify that you will create ads based on a catalog or catalog segment before you try to create Dynamic Ads. Call this field and determine value otherwise you may get and error when you try to create Dynamic Ads from catalog segments. |
is_local_catalog bool | is_local_catalog |
name string | The name of a catalog given by the creator |
product_count int32 | The total number of products in a catalog |
vertical enum | The type of catalog (for example: hotels, commerce, etc) |
Edge | Description |
---|---|
Edge<Business> | Agencies that have access to a catalog |
Edge<AssignedUser> | Users assigned to this catalog |
Edge<AutomotiveModel> | Automotive models that a catalog contains |
Edge<ProductCatalogCategory> | Categories within the catalog for a given categorization criteria |
Edge<CheckBatchRequestStatus> | Checks the status of a batch request |
Edge<CollaborativeAdsShareSettings> | All the collaborative ads share settings for a catalog segment |
Edge<ProductCatalogDataSource> | data_sources updating catalog including feeds, session containers etc |
Edge<Destination> | Destinations that a catalog contains |
Edge<ProductCatalogDiagnosticGroup> | diagnostics |
Edge<ProductEventStat> | Aggregated statistics on the matched and unmatchd events received from the pixels and apps associated to the catalog, broken down by DA event, source and device_type |
Edge<ExternalEventSource> | External event sources (including pixels) for catalog events like ViewContent |
Edge<Flight> | Flights that a catalog contains |
Edge<HomeListing> | Home listings that a catalog contains |
Edge<ProductCatalogHotelRoomsBatch> | Batch operations with hotel rooms |
Edge<Hotel> | Hotels that a catalog contains |
Edge<ProductCatalogPricingVariablesBatch> | Batch operations with hotel room prices |
Edge<ProductGroup> | Product groups that a catalog contains |
Edge<ProductSet> | Product sets belonging to a catalog |
Edge<ProductCatalogProductSetsBatch> | Batch operations with product sets |
Edge<ProductItem> | Products that a catalog contains |
Edge<VehicleOffer> | Vehicle offers that a catalog contains |
Edge<Vehicle> | Vehicles that a catalog contains |
Error | Description |
---|---|
100 | Invalid parameter |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
200 | Permissions error |
190 | Invalid OAuth 2.0 Access Token |
80009 | There have been too many calls to this Catalog account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting. |
curl \ -F 'name=Catalog' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/product_catalogs
items_batch
edge from the following paths: Parameter | Description |
---|---|
allow_upsert boolean | Default value: true Parameters specifying whether non existing items that are being updated should be inserted or should throw the error |
item_sub_type enum {APPLIANCES, BABY_FEEDING, BABY_TRANSPORT, BEAUTY, BEDDING, CAMERAS, CELL_PHONES_AND_SMART_WATCHES, CLEANING_SUPPLIES, CLOTHING, CLOTHING_ACCESSORIES, COMPUTERS_AND_TABLETS, DIAPERING_AND_POTTY_TRAINING, ELECTRONICS_ACCESSORIES, FURNITURE, HEALTH, HOME_GOODS, JEWELRY, NURSERY, PRINTERS_AND_SCANNERS, PROJECTORS, SHOES_AND_FOOTWEAR, SOFTWARE, TOYS, TVS_AND_MONITORS, VIDEO_GAME_CONSOLES_AND_VIDEO_GAMES, WATCHES} | Default value: "EMPTY" The sub vertical type of items in the request |
item_type string | The type of items in the request Required |
requests JSON object | Array of JSON objects containing batch requests. Each batch request consists of Required |
handles
: List [validation_status
: List [errors
: List [message
: string, retailer_id
: string, warnings
: List [message
: string, Error | Description |
---|---|
80014 | There have been too many calls for the batch uploads to this catalog account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#catalog. |
100 | Invalid parameter |
200 | Permissions error |
190 | Invalid OAuth 2.0 Access Token |
owned_product_catalogs
edge from the following paths: Parameter | Description |
---|---|
additional_vertical_option enum {LOCAL_DA_CATALOG, LOCAL_PRODUCTS} | Additional catalog configurations that does not introduce either new verticals or subverticals |
catalog_segment_filter A JSON-encoded rule | Provide filter for catalog to create a catalog segment. |
da_display_settings Object | Dynamic Ads display settings. |
destination_catalog_settings JSON object | Destination catalog settings. |
flight_catalog_settings JSON object | Flight catalog settings. |
name UTF-8 encoded string | Name of the catalog. Required |
parent_catalog_id numeric string or integer | Parent catalog ID. |
partner_integration JSON object | Partner integration settings |
store_catalog_settings JSON object | Store catalog settings. |
vertical enum {adoptable_pets, commerce, destinations, flights, generic, home_listings, hotels, jobs, local_service_businesses, offer_items, offline_commerce, transactable_items, vehicles} | Default value: commerce The catalog's industry or vertical, such as |
id
in the return type.id
: numeric string, Error | Description |
---|---|
100 | Invalid parameter |
2310068 | Cannot create a catalog segment from a non CPAS compliant parent catalog |
assigned_users
edge from the following paths: Parameter | Description |
---|---|
tasks array<enum {MANAGE, ADVERTISE, MANAGE_AR, AA_ANALYZE}> | Catalog permission tasks to assign this user Required |
user UID | Business user id or system user id Required |
success
: bool, Error | Description |
---|---|
100 | Invalid parameter |
200 | Permissions error |
vehicles
edge from the following paths: Parameter | Description |
---|---|
address JSON object | address Required |
applinks Object | applinks |
availability enum {AVAILABLE, NOT_AVAILABLE, PENDING} | availability |
body_style enum {CONVERTIBLE, COUPE, CROSSOVER, ESTATE, GRANDTOURER, HATCHBACK, MINIBUS, MINIVAN, MPV, PICKUP, ROADSTER, SALOON, SEDAN, SMALL_CAR, SPORTSCAR, SUPERCAR, SUPERMINI, SUV, TRUCK, VAN, WAGON, OTHER, NONE} | body_style Required |
condition enum {EXCELLENT, VERY_GOOD, GOOD, FAIR, POOR, OTHER, NONE} | condition |
currency ISO 4217 Currency Code | currency Required |
date_first_on_lot string | date_first_on_lot |
dealer_id string | dealer_id |
dealer_name string | dealer_name |
dealer_phone string | dealer_phone |
description string | description Required |
drivetrain enum {TWO_WD, FOUR_WD, AWD, FWD, RWD, OTHER, NONE} | drivetrain |
exterior_color string | exterior_color Required |
fb_page_id string | fb_page_id |
fuel_type enum {DIESEL, ELECTRIC, GASOLINE, FLEX, HYBRID, OTHER, PETROL, PLUGIN_HYBRID, NONE} | fuel_type |
images list<Object> | images Required |
interior_color string | interior_color |
make string | make Required |
mileage JSON object | mileage Required |
model string | model Required |
price int64 | price Required |
state_of_vehicle enum {NEW, USED, CPO} | state_of_vehicle Required |
title string | title Required |
transmission enum {AUTOMATIC, MANUAL, OTHER, NONE} | transmission |
trim string | trim |
url URI | url Required |
vehicle_id string | vehicle_id Required |
vehicle_type enum {BOAT, CAR_TRUCK, COMMERCIAL, MOTORCYCLE, OTHER, POWERSPORT, RV_CAMPER, TRAILER} | vehicle_type |
vin string | vin Required |
year int64 | year Required |
id
in the return type.id
: numeric string, Error | Description |
---|---|
100 | Invalid parameter |
10800 | Duplicate retailer_id when attempting to create a store collection |
/{product_catalog_id}
.Parameter | Description |
---|---|
additional_vertical_option enum {LOCAL_DA_CATALOG, LOCAL_PRODUCTS} | Additional catalog configurations that does not introduce either new verticals or subverticals |
da_display_settings Object | The display settings object when used will determine which image transformations (like cropping or padding) will be applied for the item in the specified dynamic ad format. |
default_image_url URL | The URL for the default image, which is used for products without images or for the cases when the product image is temproarily unavailable. If a product image matches the default image, this should be treated as if the image was not loaded. |
destination_catalog_settings JSON object | Catalog setting for destination catalogs. |
fallback_image_url URL | The URL for the fallback image. This is used as the image for the auto-generated dynamic items. |
flight_catalog_settings JSON object | Catalog setting for flight catalogs. |
name UTF-8 encoded string | Name of the Product Catalog |
partner_integration JSON object | Partner integration settings |
store_catalog_settings JSON object | Catalog settings for store catalogs; the page with the location structure for all the stores within this settings will be used to validate the store number for feed uploading |
success
: bool, Error | Description |
---|---|
200 | Permissions error |
100 | Invalid parameter |
You can delete a product catalog with the following API. You cannot remove a product catalog from a Business Manager, or transfer a catalog from one Business Manager to another.
curl -X DELETE \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>
To do this in a batch call, specify the parameter in the query string for the URL:
curl \ -F 'access_token=<ACCESS_TOKEN>' \ -F 'batch=[{"method":"DELETE", "relative_url":"<PRODUCT_CATALOG_ID>/external_event_sources?external_event_sources=["<EXTERNAL_EVENT_SOURCE_ID>"]' \ https://graph.facebook.com
To remove the association between the catalog and a pixel or app, make an HTTP DELETE
:
curl -X DELETE \ -d '0=<PIXEL_ID>' \ -d '1=<APP_ID>' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/external_event_sources
To see all pixel and apps associated with a product catalog, make an HTTP GET
:
curl -G \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/external_event_sources
/{product_catalog_id}
.Parameter | Description |
---|---|
allow_delete_catalog_with_live_product_set boolean | Default value: false If the catalog has live product sets, the deletion will be blocked by default. Set this parameter to true to enforce the deletion even if it has live product sets |
success
: bool, Error | Description |
---|---|
801 | Invalid operation |
3970 | You must be assigned as an admin of this product catalog before you can delete it. |
100 | Invalid parameter |
200 | Permissions error |
/{product_catalog_id}/assigned_users
.Parameter | Description |
---|---|
user UID | Business user id or system user id Required |
success
: bool, Error | Description |
---|---|
100 | Invalid parameter |