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, CREATORS_AS_SELLERS, 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 |
---|---|
368 | The action attempted has been deemed abusive or is otherwise disallowed |
100 | Invalid parameter |
190 | Invalid OAuth 2.0 Access Token |
200 | Permissions error |
2500 | Error parsing graph query |
curl \ -F 'name=Catalog' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/product_catalogs
vehicles
edge from the following paths:
Parameter | Description |
---|---|
address
JSON object
|
address Required
|
city
string
|
Default value:
""
city |
city_id
string
|
city_id |
country
string
|
Default value:
""
country |
latitude
float
|
latitude |
longitude
float
|
longitude |
neighborhoods
array<string>
|
neighborhoods |
postal_code
string
|
Default value:
""
postal_code |
region
string
|
Default value:
""
region |
street_address
string
|
Default value:
""
street_address |
applinks
Object
|
applinks |
web
|
|
android
|
|
ios
|
|
ipad
|
|
iphone
|
|
windows_phone
|
|
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
|
image_url
URL
|
Required
|
tags
list<string>
|
|
interior_color
string
|
interior_color |
make
string
|
make Required
|
mileage
JSON object
|
mileage Required
|
unit
enum {KILOMETERS, MILES}
|
Default value:
"MILES"
unit |
value
int64
|
Default value:
0
value |
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 |
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 |
---|---|
100 | Invalid parameter |
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. |
200 | Permissions error |
190 | Invalid OAuth 2.0 Access Token |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
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. |
carousel_ad
Object
|
Required
|
transformation_type
enum{background_cropping_and_padding, background_padding, none}
|
Required
|
single_ad
Object
|
Required
|
transformation_type
enum{background_cropping_and_padding, background_padding, none}
|
Required
|
destination_catalog_settings
JSON object
|
Destination catalog settings. |
generate_items_from_pages
boolean
|
Default value:
false
|
flight_catalog_settings
JSON object
|
Flight catalog settings. |
generate_items_from_events
boolean
|
Default value:
false
|
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 |
external_access_token
string
|
External access token |
external_merchant_id
string
|
External merchant identifier |
store_catalog_settings
JSON object
|
Store catalog settings. |
page_id
numeric string
|
page_id Required
|
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 |
200 | Permissions error |
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 |
/{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. |
carousel_ad
Object
|
Required
|
transformation_type
enum{background_cropping_and_padding, background_padding, none}
|
Required
|
single_ad
Object
|
Required
|
transformation_type
enum{background_cropping_and_padding, background_padding, none}
|
Required
|
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. |
generate_items_from_pages
boolean
|
Default value:
false
|
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. |
generate_items_from_events
boolean
|
Default value:
false
|
name
UTF-8 encoded string
|
Name of the Product Catalog |
partner_integration
JSON object
|
Partner integration settings |
external_access_token
string
|
External access token |
external_merchant_id
string
|
External merchant identifier |
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 |
page_id
numeric string
|
page_id Required
|
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 |
/{product_catalog_id}/assigned_users
. Parameter | Description |
---|---|
user
UID
|
Business user id or system user id Required
|
success
: bool,Error | Description |
---|---|
100 | Invalid parameter |
200 | Permissions error |