Marketing API Version

Setup Catalog

To set up Dynamic Ads, you will need a catalog, catalog feeds and product sets.

Your catalog is a structured data file with a list of items that you would like to advertise. Each line contains all information needed to create a Dynamic Ad. Product feeds are dynamic uploads of your data to keep your product catalog up to date.

In this document we will walk you through how to set up a catalog:

Step 1: Create Catalog

To create a catalog for Dynamic Ads:

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.9/<BUSINESS_ID>/product_catalogs

To use Catalog API, you need the appropriate Marketing API Access Level and you must accept the Terms of Service by creating your first catalog through Business Manager. Also see Catalog Reference.

Step 2: Setup Feed

This is a set of items uploaded or fetched from a business so your product catalog up to date. A product item is a single item represented in your online store, such as a SKU. You can have a single product feed to represent all products in your catalog; or multiple product feeds with each feed representing a single country or division's products.

After you create a product catalog, use catalog id to create and schedule a product feed:

use FacebookAds\Object\ProductFeed;
use FacebookAds\Object\Fields\ProductFeedFields;
use FacebookAds\Object\Fields\ProductFeedScheduleFields;

$product_feed = new ProductFeed(null, <PRODUCT_CATALOG_ID>);

$product_feed->setData(array(
  ProductFeedFields::NAME => 'Test Feed',
  ProductFeedFields::SCHEDULE => array(
    ProductFeedScheduleFields::INTERVAL => 'DAILY',
    ProductFeedScheduleFields::URL =>'http://www.example.com/sample_feed.tsv',
    ProductFeedScheduleFields::HOUR => 22,
  ),
));

$product_feed->create();
from facebookads.adobjects.productfeed import ProductFeed

product_feed = ProductFeed(parent_id=<PRODUCT_CATALOG_ID>)

product_feed[ProductFeed.Field.name] = 'Test Feed'
product_feed[ProductFeed.Field.schedule] = {
    'interval': 'DAILY',
    'url': 'http://www.example.com/sample_feed.tsv',
    'hour': 22,
}

product_feed.remote_create()
ProductFeed productFeed = new ProductCatalog(<PRODUCT_CATALOG_ID>, context).createProductFeed()
  .setName("Test Feed")
  .setSchedule("{\"interval\":\"DAILY\",\"url\":\"http://www.example.com/sample_feed.tsv\",\"hour\":\"22\"}")
  .execute();
String product_feed_id = productFeed.getId();
curl \
  -F 'name=Test Feed' \
  -F 'schedule={ 
    "interval": "DAILY", 
    "url": "http:\/\/www.example.com\/sample_feed.tsv", 
    "hour": 22 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PRODUCT_CATALOG_ID>/product_feeds

Supported Formats

Provide the product feed in one of these formats:

Feed FormatDescriptionSample Feed

CSV

Comma-separated value. The first row specifies the column header. Fields containing commas should be enclosed in "double quotes"

Download (Right-Click and Save Link As)

TSV

Tab-separated values. The first row specifies the column header. Fields containing spaces should be enclosed in "double quotes"

Download (Right-Click and Save Link As)

RSS XML

This format would typically be generated by automated feed provider systems or web servers. The product list is represented by a set of XML nodes and must begin with the <?xml declaration tag.

Download (Right-Click and Save Link As)

ATOM XML

This format would typically be generated by automated feed provider systems or web servers. The product list is represented by a set of XML nodes and must begin with the <?xml declaration tag.

Download (Right-Click and Save Link As)

Required Fields

All column names must be in English.

NameTypeDescription

id
Max size: 100

string

A unique ID for this item (which can be a variant for a product). If there are multiple instances of the same ID, all instances will be ignored. This maps to retailer_id after the product has been imported.

availability

string

Whether or not the item is in stock. Accepted values are:
in stock - Item ships immediately.
out of stock - No plan to restock.
preorder- Available in future.
available for order - Ships in 1-2 weeks.
discontinued - Discontinued

condition

string

The condition of the product: new, refurbished, or used

description
Max size: 5000

string

A short paragraph describing the item.

image_link

string

Link to item image used in the ad. Carousel format uses a square 1:1 aspect ratio images (600x600px) while single product ad uses 1.91:1 aspect ratio image (1200x630px). Provide the proper images which best fit your need.

link

string

Link to merchant's site where you can buy the item.

title
Max size: 100

string

Title of the item.

price

string

Cost of the item and currency. Currency should follow ISO 4217 currency codes e.g. 9.99 USD

gtin, mpn, or brand
Max size: 70

string

gtin - Global Trade Item Number (GTINs) can include UPC, EAN, JAN, and ISBN.

mpn - The number which uniquely identifies a product to its manufacturer.

brand - Name of the brand.

Note: Either gtin, mpn, or brand are required.

Optional Fields

Product Deep Links

You can specify deep links in the Product Feed following the App Links specification. Deep link information in the Product Feed takes precedence over any information collected through App Links metadata by our web crawler on webpages.

If deep link information already exists from App Links metadata in your website, specifying this data in the Product Feed is not necessary. We will use the collected information to display the correct deep link. To setup deep links in Ad Creative see Dynamic Creative, Ad Template.

NameDescriptionExample

ios_url

A custom scheme for the iOS app

example-ios://electronic

ios_app_store_id

The app ID for the App Store

1234

ios_app_name

The name of the app, suitable for display

Electronic Example iOS

iphone_url

A custom scheme for the iPhone app

example-iphone://electronic

iphone_app_store_id

The app ID for the App Store

5678

iphone_app_name

The name of the app, suitable for display

Electronic Example iPhone

ipad_url

A custom scheme for the iPhone app

example-ipad://electronic

ipad_app_store_id

The app ID for the App Store

9010

ipad_app_name

The name of the app, suitable for display

Electronic Example iPad

android_url

A custom scheme for the Android app

example-android://electronic

android_package

A fully-qualified package name for intent generation

com.electronic

android_app_name

The name of the app, suitable for display

Electronic Example Android

windows_phone_url

A custom scheme for the Windows Phone app

example-windows://electronic

windows_phone_app_id

The app ID, as a GUID, for app store

ee728e01-7727-4168-9c8f-85c7eef40112

windows_phone_app_name

The name of the app, suitable for display

Electronic Example Windows

For iOS you only need to specify the iPhone or iPad app information if they are different from the general iOS app.

The following are optional fields you can include in your field file.

NameTypeMax Size

additional_image_link
Max size: 2000

string

More images. You can include up to 10 additional images. If you supply multiple images, send them as comma separated URLs.

age_group

string

The age group the product is meant for. Accepted values are newborn, infant, toddler, kids, and adult.

color
Max size: 100

string

The color of the item.

expiration_date

ISO‑8601 (YYYY‑MM‑DD)

The expiration date of the product in the catalog. If the product is expired, it'll be excluded from all the proudct sets and will not be shown in the ads.

gender

string

Acceptable values are male, female, and unisex

item_group_id

string

Is this item a variant of a product? If so, all of the items in a group should share an item_group_id. e.g. the Red Polo Shirt is a variant of Polo Shirt. This maps to retailer_product_group_id after the product has been imported.

google_product_category
Max size: 250

string

Predefined values from Google's product taxonomy. For example, Apparel & Accessories > Clothing > Dresses

material
Max size: 200

string

The material or fabric that a product is made out of. For example, a jacket might have values like leather, denim, or cotton.

pattern
Max size: 100

string

The pattern or graphic print featured on a product.

product_type
Max size: 750

string

The retailer-defined category of the product as a string

Examples

TSV

Home & Garden > Kitchen & Dining > Appliances > Refrigerators

XML

<product_type>Home &amp; Garden &gt; Kitchen & Dining &gt; Appliances &gt; Refrigerators</product_type>

sale_price

string

The discounted price if the item is on sale. Currency should be specified as the ISO 4217 currency code. Specified as 9.99 USD

sale_price_effective_date

ISO‑8601 (YYYY‑MM‑DD)

The start and end date/time of the sale, separated by slash. e.g.
2014-11-01T12:00-0300/2014-12-01T00:00-0300

shipping

string

A blob with different prices for each country and region. Different regions are comma separated. The format should be COUNTRY:STATE:SHIPPING_TYPE:PRICE.

Examples

US:CA:Ground:9.99 USD,
US:NY:Air:15.99 USD

shipping_weight

string

The weight of the item for shipping. We only accept the following units of weight: lb, oz, g, kg. e.g. 3 lbs

size
Max size: 100

string

The size of the item. For example, a shirt may be Small or XL.

custom_label_0
Max size: 100

string

Can contain additional information about the item.

custom_label_1
Max size: 100

string

Can contain additional information about the item.

custom_label_2
Max size: 100

string

Can contain additional information about the item.

custom_label_3
Max size: 100

string

Can contain additional information about the item.

custom_label_4
Max size: 100

string

Can contain additional information about the item.

Product Group is the way you group all product variants. You use product group to distinguish products that are almost identical but have variations such as color, material, size or pattern. Groups make it easier to advertise additional colors, styles, or patterns for a particular product.
All products in a product group share the same item_group_id.

Test your product feed through our product feed debug page. For CSV / TSV, copy the first row (column header row) and a few products; for XML, copy the XML with a few item / entry, paste the lines into the text area and validate.

Step 3: Update Options

To keep the product information in a catalog always fresh and updated, use one of the following:

  1. Scheduled Product Feed Fetches
  2. Direct Upload a Product Feed
  3. Update a Product

Scheduled Product Feed Fetches

Facebook fetches product feeds from your system on a schedule you define. Each fetch is a complete refresh operation. Products not present in the file are deleted from the feed, existing ones are updated and new ones created:

use FacebookAds\Object\ProductFeed;
use FacebookAds\Object\Fields\ProductFeedFields;
use FacebookAds\Object\Fields\ProductFeedScheduleFields;

$product_feed = new ProductFeed(null, <PRODUCT_CATALOG_ID>);

$product_feed->setData(array(
  ProductFeedFields::NAME => 'Test Feed',
  ProductFeedFields::SCHEDULE => array(
    ProductFeedScheduleFields::INTERVAL => 'DAILY',
    ProductFeedScheduleFields::URL =>'http://www.example.com/sample_feed.tsv',
    ProductFeedScheduleFields::HOUR => 22,
  ),
));

$product_feed->create();
from facebookads.adobjects.productfeed import ProductFeed

product_feed = ProductFeed(parent_id=<PRODUCT_CATALOG_ID>)

product_feed[ProductFeed.Field.name] = 'Test Feed'
product_feed[ProductFeed.Field.schedule] = {
    'interval': 'DAILY',
    'url': 'http://www.example.com/sample_feed.tsv',
    'hour': 22,
}

product_feed.remote_create()
ProductFeed productFeed = new ProductCatalog(<PRODUCT_CATALOG_ID>, context).createProductFeed()
  .setName("Test Feed")
  .setSchedule("{\"interval\":\"DAILY\",\"url\":\"http://www.example.com/sample_feed.tsv\",\"hour\":\"22\"}")
  .execute();
String product_feed_id = productFeed.getId();
curl \
  -F 'name=Test Feed' \
  -F 'schedule={ 
    "interval": "DAILY", 
    "url": "http:\/\/www.example.com\/sample_feed.tsv", 
    "hour": 22 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PRODUCT_CATALOG_ID>/product_feeds

The response is:

{ "id" : <PRODUCT_FEED_ID> }

Learn more about Product Feed schedules.


Direct Upload a Product Feed

Along with scheduled feed fetches, you can manually do a one-time upload:

curl \
-F "url=http://www.example.com/sample_feed.xml" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_FEED_ID>/uploads

Optionally, you can set update_only to true. New items are created and existing ones are updated but no items are deleted from the feed. Only id is required for updating existing items. This reduce the file fetching and processing time.

For example, to update only price and custom labels for 100 items in a feed, use the direct upload option. Provide a file with only id, price and custom_label_0 for those 100 items and update_only set to true. All file formats listed are supported. The most common ones are TSV and CSV.

Example files:

Feed FormatUse-CaseSample Feed

CSV

Update price and availability for a subset of items.

Download

TSV

Reset sale_price and update custom_label_0 for a subset of items

Download

See Manual Uploads, Reference.

If you get errors in your Product Feed, see Product Feed Upload Errors.


Update Individual Product

You can update an individual product's data in real time. To update a product, include the updated fields in an HTTP POST:

https://graph.facebook.com/catalog:<PRODUCT_CATALOG_ID>:<base64urlencode(







)>

Where retailer_id is the product ID field from your product feed. It must be base64url-encoded. The mutable product fields are defined in the Product Catalog Products.

Avoid mixing product feeds with individual product item updates/creation/deletion using API. This can cause problems with updates and deletion of items created with the API since they are not tracked by the feed.

Step 4: Filter Product Catalog to Product Sets

Reference Docs

A product set is a set of products in a Product Catalog that you advertise in a dynamic ad. Each Product Catalog can have many Product Sets.

Product sets are defined by filters in a product catalog. For example, you can create a product set that matches products with "Backpacks" in the product category or a product set that matches specific product IDs. Please note that regex_match filter rule is not supported for Product set.

To create a product set of shirts:

use FacebookAds\Object\ProductSet;
use FacebookAds\Object\Fields\ProductSetFields;

$product_set = new ProductSet(null, <PRODUCT_CATALOG_ID>);

$product_set->setData(array(
  ProductSetFields::NAME => 'Test Set',
  ProductSetFields::FILTER => array(
    'product_type' => array(
      'i_contains' => 'shirt',
    ),
  ),
));

$product_set->create();
from facebookads.adobjects.productset import ProductSet

product_set = ProductSet(None, <PRODUCT_CATALOG_ID>)

product_set[ProductSet.Field.name] = 'Test Set'
product_set[ProductSet.Field.filter] = {
    'product_type': {
        'i_contains': 'shirt',
    },
}

product_set.remote_create()
ProductSet productSet = new ProductCatalog(<PRODUCT_CATALOG_ID>, context).createProductSet()
  .setName("Test Set")
  .setFilter("{\"product_type\":{\"i_contains\":\"shirt\"}}")
  .execute();
String product_set_id = productSet.getId();
curl \
  -F 'name=Test Set' \
  -F 'filter={"product_type":{"i_contains":"shirt"}}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<PRODUCT_CATALOG_ID>/product_sets

The above filter is defined with Website Custom Audiences Rules Grammar.

Next: Collect audience Signals and Build Product Audience

Build Product Audiences