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

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
Permissions are not usually requested.
If you want to learn how to use the Graph API, read our Using Graph API guide.

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.

image_padding_landscape

bool

Flag to enable padding for images in a catalog when used in single image ads. The image will be padded to a 1.91:1 aspect ratio.

image_padding_square

bool

Flag to enable padding of images in a catalog when used in carousel ads. The image will be padded to a 1:1 aspect ratio.

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.

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.

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error

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.10/<BUSINESS_ID>/product_catalogs
You can make a POST request to product_catalogs edge from the following paths:
When posting to this edge, a ProductCatalog will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • pages_show_list
Page management Apps
No data
Other Apps
No data

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
destination_catalog_settings
JSON object

Catalog setting for destination catalogs.

generate_items_from_pages
boolean
Default value: false
flight_catalog_settings
JSON object

Catalog setting for flight catalogs.

generate_items_from_events
boolean
Default value: false
name
UTF-8 encoded string

The name of the Product Catalog

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

The vertical of the catalog determining the type of data it can hold.

Return Type

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

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter

Updating

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

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
No data
Page management Apps
No data
Other Apps
Permissions are not usually requested.

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
200Permissions error
100Invalid parameter

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.10/<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.10/<PRODUCT_CATALOG_ID>/external_event_sources
You can delete a ProductCatalog by making a DELETE request to /{product_catalog_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
Permissions are not usually requested.

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.
200Permissions error