Catalog Setup

Your catalog is a structured data file with a list of inventory you want to advertise in different ways, within the Facebook family of apps. Each line contains all the information needed to create a dynamic ad. Data feed files are dynamic uploads of your data to keep your catalog up to date.

If you're using Catalog as part of your application, you may be affected by a couple of security-related breaking changes. See Breaking Changes, 1/30/2018, Catalog Permissions.

To set up a catalog, follow these steps:

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

Step 1: Create a Catalog

To create a catalog for dynamic ads:

curl -X POST \ -F 'name="Test Catalog"' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.2/{business-id}/owned_product_catalogs
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Business = bizSdk.Business; const ProductCatalog = bizSdk.ProductCatalog; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'Test Catalog', }; const owned_product_catalogs = (new Business(id)).createOwnedProductCatalog( fields, params ); logApiCallResult('owned_product_catalogs api call complete.', owned_product_catalogs);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Business; use FacebookAds\Object\ProductCatalog; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'Test Catalog', ); echo json_encode((new Business($id))->createOwnedProductCatalog( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.business import Business from facebook_business.adobjects.productcatalog import ProductCatalog from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'Test Catalog', } print Business(id).create_owned_product_catalog( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Business(id, context).createOwnedProductCatalog() .setName(\"Test Catalog\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end business = FacebookAds::Business.get(id) owned_product_catalogs = business.owned_product_catalogs.create({ name: 'Test Catalog', })

To use the Catalog Batch 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: Set Up Feed

A feed is a set of items uploaded or fetched from a business so that your 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.

curl -X POST \ -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/v3.2/{product-catalog-id}/product_feeds
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const ProductCatalog = bizSdk.ProductCatalog; const ProductFeed = bizSdk.ProductFeed; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'Test Feed', 'schedule' : {'interval':'DAILY','url':'http://www.example.com/sample_feed.tsv','hour':'22'}, }; const product_feeds = (new ProductCatalog(id)).createProductFeed( fields, params ); logApiCallResult('product_feeds api call complete.', product_feeds);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\ProductCatalog; use FacebookAds\Object\ProductFeed; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'Test Feed', 'schedule' => array('interval' => 'DAILY','url' => 'http://www.example.com/sample_feed.tsv','hour' => '22'), ); echo json_encode((new ProductCatalog($id))->createProductFeed( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.productcatalog import ProductCatalog from facebook_business.adobjects.productfeed import ProductFeed from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'Test Feed', 'schedule': {'interval':'DAILY','url':'http://www.example.com/sample_feed.tsv','hour':'22'}, } print ProductCatalog(id).create_product_feed( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new ProductCatalog(id, context).createProductFeed() .setName(\"Test Feed\") .setSchedule(\"{\\"interval\\":\\"DAILY\\",\\"url\\":\\"http://www.example.com/sample_feed.tsv\\",\\"hour\\":\\"22\\"}\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end product_catalog = FacebookAds::ProductCatalog.get(id) product_feeds = product_catalog.product_feeds.create({ name: 'Test Feed', schedule: {'interval':'DAILY','url':'http://www.example.com/sample_feed.tsv','hour':'22'}, })

The schedule parameter enables you to schedule your feed upload. Options include interval, url, hour. It can also include day_of_week, minute, username and password. For example:

schedule: {"day_of_week":"FRIDAY","hour":17,"interval_count":1,"interval":"DAILY","minute":42,"next_scheduled_upload_time":"","password":pwd123,"status":"active","timezone":"Atlantic/Canary","url":"https://www.abc.com","username":aname}

Learn More


Supported Feed Formats

Provide the product feed in one of these formats:

Feed Format Description & Guidelines Sample Feed

CSV

Comma-separated value.

  • The first row specifies the column header. Subsequent rows supply the corresponding values for each route.

  • Fields containing whitespace or commas should be enclosed in "double quotes". A double quote inside a double-quoted field must be escaped with two consecutive double quotes. Example: "Join our ""Royal"" membership program".

  • Nested or multi-value fields, such as image, can be represented using JSON-encoded values or by a set of "flattened" plain-text columns labeled using JSON-path syntax. Example: image[0].url, image[0].tag[0], image[0].tag[1])

  • Both conventions can be used interchangeably in the same file.

Download > Right-click > Save Link As

TSV

Tab-separated value. See guidelines for CSV.

Download > Right-click > Save Link As

RSS XML

A root XML node encloses a set of nodes, each of which represents a route. The file must begin with the declaration tag. The format is 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 > 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 > Save Link As

Required Fields

Provide all column names in English.

Name Type Description

id

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. Max size: 100

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

string

Short text describing product. Max size: 5000

image_link


string

Link to item image used in the ad. Provide proper image sizes.


For single-image, dynamic ads - The min image resolution requirement is 500px * 500px. The min aspect ratio requirement is is 4:5 and the maximum aspect ratio requirement is 1:91:1. If the image is outside this aspect ratio, Facebook crops it to be closest to either the minimum aspect ratio or the maximum aspect ratio depending on its original aspect ratio.


For carousel image, dynamic ads - The minimum image resolution requirement is 500px * 500px, and Facebook crops it to a 1:1 aspect ratio.

link


string

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

title

string

Title of item. Max size: 100

price

string

Cost of item and currency. Currency should follow ISO 4217 currency codes. Example: 9.99 USD

gtin, mpn, or brand

string

  • gtin - Global Trade Item Number (GTIN) can include UPC, EAN, JAN, and ISBN. Max size: 70

  • mpn - Unique manufacturer ID for product.

  • brand - Name of the brand.

Required: gtin, mpn, or brand.

Product Deep Links, Optional Fields

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

android_app_name

Name of app for display

Electronic Android

android_package

Fully-qualified package name for intent generation

com.electronic

android_url

Custom scheme for Android app as URL

android://electronic

ios_app_name

Name of app to display

Electronic iOS

ios_app_store_id

App ID for App Store

1234

ios_url

Custom scheme for iOS app as URL

ios://electronic

ipad_app_name

Name of app to display

Electronic iPad

ipad_app_store_id

App ID for App Store

9010

ipad_url

Custom scheme for iPhone app

ipad://electronic

iphone_url

Custom scheme for iPhone app as URL

iphone://electronic

iphone_app_store_id

App ID for App Store

5678

iphone_app_name

Name of app to display

Electronic iPhone

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 Windows

windows_phone_url

Custom scheme for Windows Phone app as URL

windows://electronic

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.

Optional Fields

Name Type Max Size

additional_image_link


string

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

age_group

string

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

color

string

Item color. Max size: 100

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: male, female, unisex

item_group_id

string

Items that are variants of a product. Provide the same item_group_id for all items that are variants. For example, Red Polo Shirt is a variant of Polo Shirt. Facebook maps this to retailer_product_group_id once we get your feed. With 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

string

Predefined values (string or category ID) from Google's product taxonomy. Max size: 250. Example: Apparel & Accessories > Clothing > Dresses or 2271

material

string

Material product is made of, such as leather, denim, cotton. Max size: 200

pattern

string

Pattern or graphic print on a product. Max size: 100

product_type

string

Retailer-defined category for product. Max size: 750.

Example: in TSV
Home & Garden > Kitchen & Dining > Appliances > Refrigerators

Example: 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. Example: 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.

Example:

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

shipping_weight

string

Shipping weight of item. Acceptable units of weight: lb, oz, g, kg. Example: 3 lbs

size

string

Size of item. Example: Small or XL

custom_label_0

string

Optional. Additional information about item. Max size: 100

custom_label_1

string

Optional. Additional information about item. Max size: 100

custom_label_2

string

Optional. Additional information about item. Max size: 100

custom_label_3

string

Optional. Additional information about item. Max size: 100

custom_label_4

string

Optional. Additional information about item. Max size: 100

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.


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

Sample Response

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

For details Suggested Rules API, Reference.


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

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

Update and Delete 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

Troubleshoot Missing Items in a Catalog

If Catalog Manager reports that some items in your catalog are missing or can't be found, you may need to check that your Facebook pixel or app have been set up properly. You may encounter this error when:

  • The content_id included in your pixel or app event doesn't match the ID in the catalog's data feed.
  • The pixel or app isn't associated to the catalog.
  • The item doesn't exist in the catalog.

Learn more here.

Product Feed Upload Error Report

You can use the Feed Upload Error Report API to request a full error report for any feed upload session. Once we receive the request, we run a background job to prepare these errors and store them in a CSV file.

The report contains information about:

  • Retailer ID of the item that had an error
  • Error message
  • Error severity (FATAL if the error caused item to be rejected, WARNING if item was uploaded but with an error)
  • Field names on which this error was thrown
  • Capabilities that are being affected by this error; for example, errors affecting dynamic ads that contain 'da' within this column
  • If the error blocks capability (true/false); for example, if the error prevents the item from being shown on this surface

Request a Full Error Report

To request a full error report, use POST /{upload_session_id}/error_report.

Example

curl -i -X POST \
  -F 'access_token=ACCESS_TOKEN' \
  https://graph.intern.facebook.com/<API_VERSION>/<upload session ID>/error_report

Response

The response indicates if the request was successful or not:

{
  "success": bool,
}

Get the Error Report Status

Once a report has been requested, use GET /{upload_session_id}?fields=error_report to get the status of the error report.

Example

curl -i -X GET \
 https://graph.intern.facebook.com/<API_VERSION>/<upload session ID>?fields=error_report&access_token=ACCESS_TOKEN

Response

{
  "error_report": {
    "report_status": string,
    "file_handle": string, // if available
  }
  "id": "332552650711532 (https://developers.intern.facebook.com/tools/explorer/690422434302374?method=GET&path=332552650711532%3Ffields%3Derror_report&version=v3.2#)"
}

Possible Values - Returned Status

ValueDescription

NOT_REQUESTED

The error report for this feed upload has not been requested.

REQUESTED

The request was received and is being processed.

CREATED

The report creation was successful and is waiting to be written to a CSV file.

WRITE_FINISHED

The report file has been prepared and is ready to be downloaded.

SESSION_DATA_NOT_FOUND

There was no data found for this feed upload session, it is likely that there were no items processed for this feed upload.

ERROR_REPORT_OUTDATED

The error report is older than 30 days and is no longer available.

FATAL_ERROR

Something went wrong on our end while trying to prepare this error report. You can request for an error report to retry.

Note: A CDN URL using this error report can be downloaded and will be returned as “file_handle” when the status of the error_report is WRITE_FINISHED.


Set Up Country and Language Feeds via the API

Once you have created the country and language feeds, and made them available on your server, you will need to link them to your catalog following the same API calls presented in our documentation, with the override_type parameter.

For a full list of fields available to override in the country and language feeds, as well as supported language and country codes, see our guide on how to create your language and country feeds.

Example - Uploading the Language Feed

curl \
  -F 'name=Language feed' \
  -F 'schedule={ 
    "interval": "DAILY", 
    "url": "http:\/\/www.example.com\/sample_language_feed.tsv",
    "hour": 22
  }' \
  -F 'override_type=language'
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<YOUR_PRODUCT_CATALOG_ID>/product_feeds

Example - Uploading the Country Feed

curl \
  -F 'name=Country Feed' \
  -F 'schedule={ 
    "interval": "DAILY", 
    "url": "http:\/\/www.example.com\/sample_country_feed.tsv",
    "hour": 22
  }' \
  -F 'override_type=country'
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<YOUR_PRODUCT_CATALOG_ID>/product_feeds

Parameters

Parameter Value

url

Location where we can retrieve the feed file from

interval

Frequency at which we fetch from the feed file

hour

Hour of the day (based on a 24-hr clock) when we fetch the feed

For more options about scheduling fetches, see Set Up Feed, Schedule.

Set Metadata Tags in Product Feed File (Optional)

You can optionally set metadata tags in your product feed files. This enables Facebook to attribute catalogs using this feed to your app. Once a catalog is attributed to your app, the meta tag is not required in subsequent feed uploads to that catalog.

Include the following two elements as space delimited comments at the top of TSV/CSV feeds or inside a metadata tag in your XML feeds:

  • ref_application_id - Your Facebook app ID
  • ref_asset_id - ID that uniquely identifies this feed in your system

Feed Formats


Feed Format Description

CSV

Sample CSV Feed file with reference information inside the metadata tag.

Download (Right-Click and Save Link As)

TSV

Sample TSV Feed file with reference information inside the metadata tag.

Download (Right-Click and Save Link As)

RSS XML

Sample RSS XML Feed file with reference information inside the metadata tag.

Download (Right-Click and Save Link As)

ATOM XML

Sample Atom XML Feed file with reference information inside the metadata tag.

Download (Right-Click and Save Link As)

Example - TSV feed format

# ref_application_id <YOUR_APP_ID>
# ref_asset_id <YOUR_ASSET_ID>
id  title  ios_url  ios_app_store_id  ios_app_name  android_url  android_package  android_app_name  windows_phone_url  windows_phone_app_id  windows_phone_app_name  description  google_product_category  product_type  link  image_link  condition  availability  price  sale_price  sale_price_effective_date  gtin  brand  mpn  item_group_id  gender  age_group  color  size  shipping  custom_label_0
DB_1  Dog Bowl In Blue  example-ios://electronic/db_1  123  Electronic Example iOS  example-android://electronic/db_1  com.electronic.example  Electronic Example Android  example-windows://electronic/db_1  64ec0d1b-5b3b-4c77-a86b-5e12d465edc0  Electronic Example Windows  Solid plastic Dog Bowl in marine blue color  Animals > Pet Supplies  Bowls & Dining > Food & Water Bowls  http://www.example.com/bowls/db-1.html  https://www.facebook.com/images/product_image_template.png?id=1  new  in stock  9.99 GBP        Example    DB_GROUP_1          UK::Standard:9.95 GBP  "Made in Waterford, IE"
...

Example - XML feed format

...
<?xml version="1.0"?>
<rss xmlns:g="http://base.google.com/ns/1.0" version="2.0">
  ...
  <metadata>
    <ref_application_id><YOUR_APP_ID></ref_application_id>
    <ref_asset_id><YOUR_ASSET_ID></ref_asset_id>
  </metadata>
  ...
</rss>
...

Step 3: Update Options

To keep product information current, use one of the following:

  1. Schedule Product Feed Fetches
  2. Direct Upload a Product Feed
  3. Update an Individual Product

Note: If you're using our API to create and manage your feeds, you need to send us an API request with details for the update schedule you want to create:

curl \
  -F 'name=Test Feed' \
  -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/<API_VERSION>/<CATALOG_ID>/product_feeds

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

For example: 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/<API_VERSION>/<CATALOG_ID>/product_feeds

Response:

{ "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.

This example is for feed files which are hosted on a public location.

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

This example is for uploading feed files directly from the local machine. The path to the file needs to be changed according to your use case.

curl \
  -F "file=@catalog.csv;type=text/csv" \
  -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 an 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 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: