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:

See also Getting Started with Dynamic Ads and Dynamic Ads Setup via UI.

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

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

Step 2: Setup Feed

This is a set of items uploaded or fetched from a business so your product catalog is current. A product item is a single item in your online store, such as a SKU. You can have a single product feed represent all products in your catalog; or multiple product feeds with each feed represents a single country or division's products. See Feed, Reference and Item, Reference.

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.10/<PRODUCT_CATALOG_ID>/product_feeds

Supported Formats

Provide the product feed in one of these formats:

Feed Format Description Sample Feed

CSV

Comma-separated value. The first row is the column header. Enclose fields containing commas in "double quotes"

Download (Right-Click and Save Link As)

TSV

Tab-separated values. The first row is the column header. Enclose fields containing commas in "double quotes"

Download (Right-Click and Save Link As)

RSS XML

Format typically generated by automated feed provider systems or web servers. A set of item XML nodes represents a product list and must begin with the <?xml declaration tag.

Download (Right-Click and Save Link As)

ATOM XML

Format typically generated by automated feed provider systems or web servers. A set of item XML nodes represents a product list and must begin with the <?xml declaration tag.

Download (Right-Click and Save Link As)

Required Fields

Provide all column names in English.

Name Type Description

id


Max size: 100

String

Unique ID for item. Can be a variant for a product. If there are multiple instances of the same ID, we ignore all instances. This maps to retailer_id after the product is imported.

availability

String

If item 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

Product condition: new, refurbished, or used

description


Max size: 5000

string

Short text describing product.

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 proper images for your use.

link


string

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

title


Max size: 100

string

Title of item.

price

string

Cost of item and currency. Currency should follow ISO 4217 currency codes such as 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 - Unique manufacturer ID for product.



brand - Name of the brand.



Either gtin, mpn, or brand required.

Optional Fields, Product Deep Links

Provide deep links in Product Feed following the App Links specification. Deep link information in Product Feed takes precedence over any information Facebook collects with App Links metadata with our web crawler.

If you already have deep link information from App Links, you do not need to specify this data. Facebook uses information from App Links to display the correct deep link. To display deep links in your ads see Dynamic Ads, Ad Template.

Name Description Example

ios_url

Custom scheme for iOS app as URL

example-ios://electronic

ios_app_store_id

App ID for App Store

1234

ios_app_name

Name of app to display

Electronic Example iOS

iphone_url

Custom scheme for iPhone app as URL

example-iphone://electronic

iphone_app_store_id

App ID for App Store

5678

iphone_app_name

Name of app to display

Electronic Example iPhone

ipad_url

Custom scheme for iPhone app

example-ipad://electronic

ipad_app_store_id

App ID for App Store

9010

ipad_app_name

Name of app to display

Electronic Example iPad

android_url

Custom scheme for Android app as URL

example-android://electronic

android_package

Fully-qualified package name for intent generation

com.electronic

android_app_name

Name of app for display

Electronic Example Android

windows_phone_url

Custom scheme for Windows Phone app as URL

example-windows://electronic

windows_phone_app_id

App ID, as a GUID, for app store

ee728e01-7727-4168-9c8f-85c7eef40112

windows_phone_app_name

Name of app for display

Electronic Example Windows

For iOS, only provide iPhone or iPad app information if they are different from the general iOS app.

Use product group to group all product variants. Provide product group to identify 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. In Dynamic Ads, we pick only one item out of the group based on the signal we received from the pixel or app.

These are optional fields you can include:

Name Type Max Size

additional_image_link


Max size: 2000

string

You can include up to 10 additional images; provide them as comma-separated URLs.

age_group

string

Age group for product. Accepted values are newborn, infant, toddler, kids, and adult.

color


Max size: 100

string

Item color.

expiration_date

ISO‑8601 (YYYY‑MM‑DD)

Product expiration. If the product is expired, Facebook excludes it from all product sets and does not display it in ads.

gender

string

Options include: male, female, and unisex

item_group_id

string

For items that are varients of a product. Provide the same item_group_id for all items that are varients. For example, Red Polo Shirt is a variant of Polo Shirt. Facebook maps this to retailer_product_group_id once we get your feed. In Dynamic Ads, we pick only one item out of the group based on the signal we received from the pixel or app.

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

Material product is made of such as leather, denim, or cotton.

pattern


Max size: 100

string

Pattern or graphic print on a product.

product_type


Max size: 750

string

Retailer-defined category for product.

e.g. in TSV
Home & Garden > Kitchen & Dining > Appliances > Refrigerators

e.g. in XML <product_type>Home & Garden > Kitchen & Dining > Appliances > Refrigerators</product_type>

sale_price

string

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)

Start and end date and time for the sale, separated by slash:


2014-11-01T12:00-0300/2014-12-01T00:00-0300

shipping

string

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

e.g.

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

shipping_weight

string

Shipping weight of item. We only accept these units of weight: lb, oz, g, kg. Example: 3 lbs

size

string

Size of item. For example, a shirt may be Small or XL.

custom_label_0


Max size: 100

string

Optional, additional information about item.

custom_label_1


Max size: 100

string

Optional, additional information about item.

custom_label_2


Max size: 100

string

Optional, additional information about item.

custom_label_3


Max size: 100

string

Optional, additional information about item.

custom_label_4


Max size: 100

string

Optional, additional information about item.

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 product information current, 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. There are two types of schedule you can define - update_schedule and schedule. The uploads created via update_schedule would either create new items or update existing ones with the information provided in the feed file. The uploads created via schedule would result in a complete refresh operation on your feed - we delete products not present in the file, update existing ones, and create new ones. You can use either of the schedules or both depending on your needs.

e.g: update_schedule with frequency HOURLY and a replace schedule with frequency DAILY.

We recommend setting up an update_schedule with only changed data in the feed file for faster processing of feed. This is especially better for holiday sales and faster price and availability updates. It's also recommended to mark product items as "out of stock" rather than deleting from the feed so Facebook can re-target the user with similar available products.

curl \
  -F 'name=Test Feed' \
  -F 'schedule={ 
    "interval": "DAILY", 
    "url": "http:\/\/www.example.com\/sample_feed.tsv"
  }' \
  -F 'update_schedule={ 
    "interval": "HOURLY", 
    "url": "http:\/\/www.example.com\/sample_feed_updates.tsv",
    "hour": 22
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PRODUCT_CATALOG_ID>/product_feeds

The response is:

{ "id" : {PRODUCT_FEED_ID} }

See Product Feed Reference, Product Feed Schedule Reference.


Direct Upload a Product Feed

Along with scheduled feed fetches, you can manually perform one-time uploads:

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. We create new items and update existing ones but do not delete items from the feed. You only need to provide id to update existing items. This reduces time to fetch and process your file.

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

Example files:

Feed Format Use-Case Sample Feed

CSV

Update price and availability for a subset of items.

Download (Right-Click and Save Link As)

TSV

Reset sale_price and update custom_label_0 for a subset of items

Download (Right-Click and Save Link As)

See Manual Uploads, Reference.

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


Update Individual Product

Update an individual product's data in real time. Include the updated fields in an HTTP POST:

https://graph.facebook.com/catalog:{PRODUCT_CATALOG_ID}:{base64urlencode(retailer_id)}

Where retailer_id is the product ID from your product feed. It must be base64url-encoded. See mutable product fields in the Product Catalog Products, Reference.

Do not provide product feeds with individual product updates, creation, or deletion with the API. This can disrupt any updates or deletes of items you created with the API since we do not track these with the feed.

See also: * Scheduled Feed Fetch Reference * Direct Upload Feed Reference * Product Feed Reference * Product Feeds in Catalog * Product Item Reference * Product Search in Catalog

Batch Upload for Large Catalogs

Upload very large catalogs with millions of products and quickly-changing inventory. You can create, update and delete numerous products in a single HTTP request. The API has two endpoints:

  • POST [/{product_catalog_id}/batch](#send-batch-request) - Send a batch of requests to create, update, delete items in a catalog.
  • GET [/{product_catalog_id}/check_batch_request_status](#batch-request-status) - Check status of request.

Send product updates

To create, update or delete products in your catalog, make an HTTP POST with the changes you want to make. You can make up to 500 updates in one call. For each catalog, you can make up to 100 calls per hour.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$requests =  array(
    array(
        'method' => 'CREATE',
        'retailer_id' => 'retailer-product-id-123',
        'data' => array(
          'availability' => 'in stock',
          'brand' => 'Niky',
          'category' => 't-shirts',
          'currency' => 'USD',
          'description' => 'This is the product description.',
          'image_url' => 'http://www.images.example.com/t-shirts/1.png',
          'name' => 'My product name',
          'price' => '100',
          'url' => 'http://www.example.com/t-shirts/1.html',
        ),
    ),
);


$data = Api::instance()->call(
  '/'.<CATALOG_ID>.'/batch',
  RequestInterface::METHOD_POST,
  array('requests' => $requests))->getContent();
curl \
  -F 'requests=[ 
    { 
      "method": "CREATE", 
      "retailer_id": "retailer-product-id-123", 
      "data": { 
        "availability": "in stock", 
        "brand": "Niky", 
        "category": "t-shirts", 
        "currency": "USD", 
        "description": "This is the product description.", 
        "image_url": "http:\/\/www.images.example.com\/t-shirts\/1.png", 
        "name": "My product name", 
        "price": "100", 
        "url": "http:\/\/www.example.com\/t-shirts\/1.html" 
      } 
    } 
  ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CATALOG_ID>/batch

This call returns a handle that you can use to check the status of the batch request. See Get Request Status:

{
  "handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26I"]
}
Parameter Type Description

requests

Object

JSON object containing all requests.

requests.method

string

Either CREATE, UPDATE or DELETE.

requests.retailer_id

string

Product id given by a retailer.

requests.data

Object

JSON object containing fields and values for the product. When method is CREATE, this must contain all required fields for a product. When method is UPDATE it can contain any fields. Facebook updates only the fields you provide.

The values supported in the data field you can use to CREATE and UPDATE items:

  • additional_image_urls
  • availability
  • age_group
  • applinks
  • brand
  • category
  • color
  • condition
  • currency
  • custom_label_0
  • custom_label_1
  • custom_label_2
  • custom_label_3
  • custom_label_4
  • description
  • gender
  • gtin
  • image_url
  • manufacturer_part_number
  • name
  • pattern
  • price
  • product_type
  • sale_price
  • sale_price_end_date
  • sale_price_start_date
  • shipping
  • size
  • url

You can use applinks for deep link information, which functions similarly to Product Deep Links. The format is the following:

"applinks" : {
  "ios": [{
    "url":"example-ios://electronic",
    "app_store_id":42,
    "app_name":"Electronic Example iOS"
  }],
  "iphone": [{
    "url":"example-iphone://electronic",
     "app_store_id":43,
     "app_name":"Electronic Example iPhone"
  }],
  "ipad": [{
    "url":"example-ipad://electronic",
     "app_store_id":44,
     "app_name":"Electronic Example iPad"
  }],
  "android": [{
    "url":"example-android://electronic",
     "package":"com.electronic",
     "class":"com.electronic.Example",
     "app_name":"Electronic Example Android",
  }],
  "windows_phone": [{
    "url":"example-windows://electronic",
     "app_id":"64ec0d1b-5b3b-4c77-a86b-5e12d465edc0",
     "app_name":"Electronic Example Windows"
  }]
}

See Product Catalog, Creating, Reference.

Get Request Status

To get the status of a batch request, use the handle returned from the call to {product_catalog_id}/batch:

curl -G \
-d 'handle=AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26I'
-d 'access_token={ACCESS_TOKEN}'
https://graph.facebook.com/{API_VERSION}/{PRODUCT_CATALOG_ID}/check_batch_request_status

Response:

{
  "data": [
    {
      "handle": "AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q",
      "status": "finished",
      "errors_total_count": 1,
      "errors": [
        {
          "line": 0,
          "id": "retailer-4",
          "message": "Invalid value: Value passed at position 0 (id=retailer-199) is invalid: \"You cannot create a EntProductItem without required field Availability\""
        }
      ]
    }
  ]
}

See Product Catalog, Reference, Check Batch Status.

Product Feed Rules

Fix and prevent ongoing feed upload errors with rules. You can provide rules that Facebook applies to each feed upload. Specify your rules by the attribute (column) they should apply to, by the type of rule, and by parameters. You currently cannot use rules with Batch API. You can provide these types of rules:

  • Mapping Rule - Maps attributes (column names) in a feed file to attributes we can recognize.
  • Value Mapping Rule - Maps fields (column values) in a feed file to fields we can recognize.
  • Letter Case Rule - Change case of words in a field. For example, change all uppercase descriptions to lower case.

For example, you can fix these issues with Mapping and Value Mapping Rules:

  • Attribute typos from gavailability to availability
  • Fix unrecognized enums InStock to in stock
  • Price format from 45$ to 45.00 USD
  • Translate Condition: Neu under Condition: New

You can use Letter Case Rules to address these types of issues:

  • Change descriptions in all caps BRAND NEW WITH LEATHER DETAIL... to Brand new with leather detail...
  • Fix titles in all caps FACEBOOK T-SHIRT to Facebook T-shirt

Suggested Rules

You can get suggested rules from Facebook to fix errors in your feed. To see suggested rules for your upload session, follow next steps.

  • Retrieve upload sessions:
https://graph.facebook.com/{API_VERSION}/{PRODUCT_FEED_ID}/uploads
  • Retrieve errors for upload session:
https://graph.facebook.com/{API_VERSION}/{UPLOAD_SESSION_ID}/errors
  • Retrieve suggested rules for upload error:
curl -i -X GET 
 "https://graph.facebook.com/{API_VERSION}/{UPLOAD_ERROR_ID}/suggested_rules?access_token={ACCESS_TOKEN}

An example response with a suggestion looks like this:

"data": [
  
    "attribute": "description",
    "type": "letter_case_rule",
    "params": [
      
        "key": "type",
        "value": "capitalize_first"
      
    ]
  
]

For details Suggested Rules API, Reference.

Endpoints

Adding Rules to Feeds

To apply rules to a feed, you need to associate the rule to the feed. Make an HTTP POST call to:

https://graph.facebook.com/{API_VERSION}/{PRODUCT_FEED_ID}/rules?attribute={ATTRIBUTE}&amp;rule_type={RULE_TYPE}&amp;params={PARAMS}

For example:

curl -i -X POST 
 -d "attribute=google_product_category" 
 -d "rule_type=mapping_rule" 
 -d "params=%7B'map_from'%3A%20'gcategory'%7D" 
 -d "access_token={ACCESS_TOKEN}" 
 "https://graph.facebook.com/v2.9/{PRODUCT_FEED_ID}/rules" 
 // sample response
 
  "id": "{RULE_ID}"

You should format params as follows:

Rule Type Format Example Notes

Mapping Rule

"map_from": <string>

"map_from": "gavailability"

Value Mapping Rule

<string> : <string>

"InStock": "in stock"

For value mapping rule number of mappings is limited to 10 and length of strings to 20.

Letter Case Rule

"type": one of : "capitalize_first", "capitalize_all", "to_upper", "to_lower"

"type": "capitalize_first"

For details, see Product Feed Rules API, Reference.

Get Current Rules

To list all rules associated with a feed, make a HTTP GET call to:

https://graph.facebook.com/{API_VERSION}/{PRODUCT_FEED_ID}/rules

For details, see Product Feed Rules API, Reference.

Updating and Deleting Rules

To change a rule associated with a feed, make an HTTP POST call to update any parameters and HTTP DELETE to delete it. You can only update parameters. If you want to change attribute or rule_type, you must delete and re-create the rule.

https://graph.facebook.com/{API_VERSION}/{PRODUCT_FEED_RULE_ID}?params={PARAMS}

For details, See Product Feed Rule API, Reference

Next: Collect audience Signals and Build Product Audience

Build Product Audiences