Marketing API Version

Product Catalog

Represents a catalog for your business you can use to deliver ads with Dynamic Ads. For example, to see all the product catalogs your business has access to:

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. 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

Permissions

You need the appropriate Marketing API Access Level and must accept the Terms of Service by creating your first catalog through Business Manager.

Reading

Product catalogs contain a list of items like products, hotels or flights, and the information needed to display them in dynamic ads.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription
id
numeric string

ID of a catalog

business
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

flight_catalog_settings
FlightCatalogSettings

Catalog settings for a flight 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)

Edges

EdgeDescription

agencies

Agencies that have access to a catalog

check_batch_request_status

Checks the status of a batch request

da_event_samples

Top samples of unmatched events for the selected event source (aggregated by content_id or content_url) over the last day of event fires. Useful for identifying top urls or content_ids causing low catalog match rate

destinations

Destinations that a catalog contains

event_stats

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

external_event_sources

External Event Sources for Dynamic Ads.

flights

Flights that a catalog contains

home_listings

Home listings that a catalog contains

hotel_rooms_batch

Batch operations with hotel rooms

hotels

Hotels that a catalog contains

pricing_variables_batch

Batch operations with hotel room prices

product_feeds

Product feeds belonging to a catalog

product_groups

Product groups that a catalog contains

product_sets

Product sets belonging to a catalog

product_sets_batch

Batch operations with product sets

products

Products that a catalog contains

vehicles

Vehicles that a catalog contains

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
278Reading advertisements requires an access token with the extended permission ads_read

Creating

Examples

use FacebookAds\Object\ProductCatalog;
use FacebookAds\Object\Fields\ProductCatalogFields;

$product_catalog = new ProductCatalog(null, <BUSINESS_ID>);

$product_catalog->setData(array(
  ProductCatalogFields::NAME => "Catalog",
));

$product_catalog->create();
from facebookads.adobjects.productcatalog import ProductCatalog

product_catalog = ProductCatalog(parent_id=<BUSINESS_ID>)

product_catalog[ProductCatalog.Field.name] = 'Catalog'

product_catalog.remote_create()
ProductCatalog catalog = new Business(<BUSINESS_ID>, context).createProductCatalog()
  .setName("Catalog")
  .execute();
String catalog_id = catalog.getId();
curl \
  -F 'name=Catalog' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<BUSINESS_ID>/product_catalogs
You can make a POST request to owned_product_catalogs edge from the following paths:
When posting to this edge, a ProductCatalog will be created.

Parameters

NameDescription
da_display_settings
Object

da_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

Required
vertical
enum {commerce, destinations, flights, home_listings, hotels, vehicles}
Default value: commerce

vertical

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
onsite_commerce_merchant: Struct {
id: numeric string,
},
}
You may perform a POST request to the following edges from this node:

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error

Updating

You can update a ProductCatalog by making a POST request to /{product_catalog_id}.

Parameters

NameDescription
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

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error

Deleting

Examples

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":"840962462523962/external_event_sources?external_event_sources=["21344423883497713536356"]' \
'https://graph.facebook.com'


To remove the association between the catalog and a pixel or app, make an HTTP DELETE:

use FacebookAds\Object\ProductCatalog;

$product_catalog = new ProductCatalog(<PRODUCT_CATALOG_ID>);
$product_catalog->deleteExternalEventSources(array(), array(
  <PIXEL_ID>,
  <APP_ID>,
));
from facebookads.adobjects.productcatalog import ProductCatalog

product_catalog = ProductCatalog(<PRODUCT_CATALOG_ID>)
product_catalog.remove_external_event_sources([
    <PIXEL_ID>,
    <APP_ID>,
])
curl -X DELETE \
  -d '0=<PIXEL_ID>' \
  -d '1=<APP_ID>' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PRODUCT_CATALOG_ID>/external_event_sources


To see all pixel and apps associated with a product catalog, make an HTTP GET:

use FacebookAds\Object\ProductCatalog;

$product_catalog = new ProductCatalog(<PRODUCT_CATALOG_ID>);
$sources = $product_catalog->getExternalEventSources();
from facebookads.adobjects.productcatalog import ProductCatalog

product_catalog = ProductCatalog(<PRODUCT_CATALOG_ID>)
product_catalog.get_external_event_sources()
APINodeList<ExternalEventSource> externalEventSources = new ProductCatalog(<PRODUCT_CATALOG_ID>, context).getExternalEventSources()
  .execute();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PRODUCT_CATALOG_ID>/external_event_sources
You can delete a ProductCatalog by making a DELETE request to /{product_catalog_id}.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}
You can dissociate a ProductCatalog from a ProductCatalog by making a DELETE request to /{product_catalog_id}/external_event_sources.

Parameters

NameDescription
external_event_sources
list<numeric string or integer>

external event sources

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
3970You must be assigned as an admin of this product catalog before you can delete it.