Graph 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

Example

Graph API Explorer
GET /v5.0/{product-catalog-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{product-catalog-id}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{product-catalog-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{product-catalog-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{product-catalog-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
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 that owns a catalog

cpas_parent_catalog_settings
CPASParentCatalogSettings

CPAS parent catalog settings

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

name
string

The name of a catalog given by the creator

product_count
int32

The total number of products in a catalog

store_catalog_settings

Catalog settings for a store catalog that promotes physical in-store items

vertical
enum

The type of catalog (for example: hotels, commerce, etc)

Edges

EdgeDescription

Agencies that have access to a catalog

Users assigned to this catalog

Automotive models that a catalog contains

Categories within the catalog for a given categorization criteria

Checks the status of a batch request

All the collaborative ads share settings for a catalog segment

Destinations that a catalog contains

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 (including pixels) for catalog events like ViewContent

Flights that a catalog contains

Home listings that a catalog contains

Batch operations with hotel rooms

Hotels that a catalog contains

Batch operations with hotel room prices

Product groups that a catalog contains

Product sets belonging to a catalog

Batch operations with product sets

Products that a catalog contains

Vehicle offers that a catalog contains

Vehicles that a catalog contains

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.

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

ParameterDescription
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
store_catalog_settings
JSON object

Store catalog settings.

page_id
page ID

page_id

Required
vertical
enum {bookable, commerce, destinations, flights, home_listings, hotels, offline_commerce, ticketed_experiences, transactable_items, vehicles}
Default value: commerce

The catalog's industry or vertical, such as commerce.

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,
},
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
You can make a POST request to assigned_users edge from the following paths:
When posting to this edge, a ProductCatalog will be created.

Parameters

ParameterDescription
tasks
array<enum {MANAGE, ADVERTISE}>

Catalog permission tasks to assign this user

Required
user
UID

Business user id or system user id

Required

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

Parameters

ParameterDescription
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_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 method and data fields

Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
handles: List [
string
],
validation_status: List [
Struct {
errors: List [
Struct {
message: string,
}
],
retailer_id: string,
warnings: List [
Struct {
message: string,
}
],
}
],
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to vehicles edge from the following paths:
When posting to this edge, a ProductCatalog will be created.

Parameters

ParameterDescription
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

android

ios

ipad

iphone

windows_phone

availability
enum {AVAILABLE, NOT_AVAILABLE}

availability

body_style
enum {CONVERTIBLE, COUPE, CROSSOVER, HATCHBACK, MINIVAN, SMALL_CAR, TRUCK, SUV, SEDAN, 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

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter

Updating

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

Parameters

ParameterDescription
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

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
page ID

page_id

Required

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,
}

Validation Rules

ErrorDescription
3970You must be assigned as an admin of this product catalog before you can delete it.
100Invalid parameter
You can dissociate a ProductCatalog from a ProductCatalog by making a DELETE request to /{product_catalog_id}/external_event_sources.

Parameters

ParameterDescription
external_event_sources
list<numeric string or integer>

SELF_EXPLANATORY

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can dissociate a ProductCatalog from a ProductCatalog by making a DELETE request to /{product_catalog_id}/assigned_users.

Parameters

ParameterDescription
user
UID

Business user id or system user id

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter