Marketing API Version

Product Catalog

Reading

A Product Catalog object

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
  • manage_pages
  • user_managed_groups
Other Apps
Permissions are not usually requested.

Examples

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"


To associate pixels and apps with a product catalog, make an HTTP POST call to:

use FacebookAds\Object\ProductCatalog;

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

product_catalog = ProductCatalog(<PRODUCT_CATALOG_ID>)
product_catalog.add_external_event_sources([
    <PIXEL_ID>,
    <APP_ID>,
])
curl \
  -F 'fields=1000002,101' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/<PRODUCT_CATALOG_ID>/external_event_sources


To remove the association between a pixel and/or app with a product catalog, make an HTTP DELETE call to:

use FacebookAds\Object\ProductCatalog;

$product_catalog = new ProductCatalog(<PRODUCT_CATALOG_ID>);
$product_catalog->deleteExternalEventSources(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 'fields=1000002,101' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/<PRODUCT_CATALOG_ID>/external_event_sources


To get all pixel and app associations for a product catalog, make an HTTP GET call:

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.8/<PRODUCT_CATALOG_ID>/external_event_sources
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 the product catalog

business

Business that owns the product catalog

default_image_url

string

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.

fallback_image_url

list<string>

The URL for the fallback image. This is used as the image for the auto-generated dynamic items.

feed_count

int32

The total number of feeds of this product catalog

image_padding_landscape

bool

Flag to enable padding for images in the 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 the catalog when used in carousel ads. The image will be padded to a 1:1 aspect ratio

name

string

The name given by the owner of this product catalog

product_count

int32

The total number of products of this product catalog

vertical

enum

The vertical of this catalog - hotels, commerce, etc

Edges

EdgeDescription

agencies

Business Manager is a way to help businesses and agencies manage their Facebook Pages, ad accounts and apps in one place. Learn how to use Business Manager APIs here

batch

batch

destinations

Destinations that this product catalog contains

external_event_sources

External Event Sources for Dynamic Ads.

hotel_rooms_batch

Batch operations with hotel rooms

hotels

Hotels that this product catalog contains

pricing_variables_batch

Batch operations with hotel room prices

product_feeds

Product feeds belonging to this catalog

product_groups

Product groups that this product catalog contains

product_sets

Product sets belonging to this catalog

product_sets_batch

Batch operations with product sets

products

Products that this product catalog contains

Validation Rules

ErrorDescription
100Invalid parameter

Creating

Permissions

To use the product catalog API, please ensure you have the appropriate Marketing API Access Level and that you have accepted the Terms of Service by creating your first catalog through Business Manager.

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

Parameters

NameDescription
name
Base64 UTF-8 encoded string

The name of the Product Catalog

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

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

Return Type

Struct {
id: numeric string,
}
You may perform a POST request to the following edges from this node:

Validation Rules

ErrorDescription
100Invalid parameter

Updating

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

Permissions

Developers usually request these permissions for this endpoint:

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

Parameters

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

name
Base64 UTF-8 encoded string

Name of the Product Catalog

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter

Deleting

Examples

You can delete a product catalog with the following API. You cannot remove a product catalog from a Business Manager, nor can you transfer one product catalog from one Business Manager to another Business Manager.

curl -X DELETE \
-F 'access_token=<ACCESS_TOKEN>' \
"https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>"


To do this in a batch call, you can specify the parameter in the query string of the URL as follows:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[{"method":"DELETE", relative_url":"840962462523962/external_event_sources?external_event_sources=["21344423883497713536356"]' \
'https://graph.facebook.com'
You can delete a ProductCatalog by making a DELETE request to /{graph_product_catalog_node_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
  • business_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 GraphProductCatalogNode by making a DELETE request to /{graph_product_catalog_node_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.