Update Catalog Options

To keep your catalog data feed information current, use one of the following options:

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

Set Microdata Tags in Catalog (Optional)

There are two protocols that you can use to add the microdata: OpenGraph or Schema.org. Depending on the type of protocol you choose, the microdata needs to be in the right location on your website:

  • OpenGraph: Place the microdata in the header of your website.
  • Schema.org: Place the microdata across the product page where the products are located.
  • JSON-LD for Schema.org: Place the microdata within the script tag (see the example below).

OpenGraph – Required Tags

NameDescription

og:title

Title of the item.

og:description

Description of the item.

og:url

Complete URL for the product page.

og:image

Link to the image used on the product page.

product:brand

Brand name of the item.

product:availability

Current availability of the item: in stock, out of stock, preorder, available for order, discontinued.

product:condition

Current condition of the item: new, refurbished, used.

product:price:amount

Current price of the item. Don't include symbols, such as “$” in the price.

product:price:currency

Currency for the price in ISO format (for example, USD).

product:retailer_item_id

Retailer's ID for the item.

Example - OpenGraph

curl \

<header>

...

<!-- Open Graph Metadata -->

 <meta property="og:title" content="Facebook T-Shirt">

 <meta property="og:description" content="Unisex Facebook T-shirt, Small">

 <meta property="og:url" content="https://example.org/facebook">

 <meta property="og:image" content="https://example.org/facebook.jpg">

 <meta property="product:brand" content="Facebook">

 <meta property="product:availability" content="in stock">

 <meta property="product:condition" content="new">

 <meta property="product:price:amount" content="9.99">

 <meta property="product:price:currency" content="USD">

 <meta property="product:retailer_item_id" content="facebook_tshirt_001">

<!-- End Open Graph Metadata -->

...

</header>

Schema.org – Required Tags

NameDescription

name

Title of the item.

brand

Brand of the item.

description

Description of the item.

productID

Retailer's ID for the item.

url

Complete URL for the product page.

image

Link to the image used on the product page.

price

Current price of the item. Don't include symbols, such as “$” in the price. Include this entry under “offers”.

priceCurrency

Currency for the price, in ISO format (for example, USD). Include this entry under “offers”.

availability

Current availability of the item: in stock, out of stock, preorder, available for order, discontinued. Include this entry under “offers”.

condition

Current condition of the item: new, refurbished, or used. Include this entry under “offers”.

Example - Schema.org {#schema.org}

curl \
    <div itemscope itemtype="http://schema.org/Store">
<div id="..." class="..." itemscope="" itemtype="http://schema.org/Product">
...
<meta itemprop="brand" content="facebook">
<meta itemprop="name" content="Facebook T-Shirt">
<meta itemprop="description" content="Unisex Facebook T-shirt, Small">
<meta itemprop="productID" content="facebook_tshirt_001">
<meta itemprop="url" content="https://example.org/facebook">
<meta itemprop="image" content="https://example.org/facebook.jpg">
...
<span itemprop="offers" itemscope itemtype="http://schema.org/Offer" itemref="schema-offer">
<link itemprop="availability" href="http://schema.org/InStock">
<link itemprop="itemCondition" href="http://schema.org/NewCondition">
<div class="..." itemprop="price"&gt;7.99&lt;/div>
<meta itemprop="priceCurrency" content="USD">
...
        </span>
        ...
       </div><div itemscope itemtype="">

JSON-LD for Schema.org

Extracted from schema.org/Product

NameDescription

name

Title of the item.

brand

Brand of the item.

description

Description of the item.

productID

Retailer's ID for the item.

url

Complete URL for the product page.

offers

Vector of objects of type schema.org/Offer.

image

Link to the image used on the product page.

Extracted from schema.org/Offer (as a part of product offers)

NameDescription

price

Current price of the item. Don't include symbols, such as “$” in the price. Include this entry under “offers”.

priceCurrency

Currency for the price, in ISO format (for example, USD). Include this entry under “offers”.

availability

Current availability of the item: in stock, out of stock, preorder, available for order, discontinued. Include this entry under “offers”.

condition

Current condition of the item: new, refurbished, or used. Include this entry under “offers”.

Example — schema.org/Offer

curl \
<script type="application/ld+json">

       {
  
        "@context":"https://schema.org",
        "@type":"Product",
        "productID":"facebook_tshirt_001",
        "name":"Facebook T-Shirt",
        "description":"Unisex Facebook T-shirt, Small",
        "url":"https://example.org/facebook",
        "image": "https://example.org/facebook.jpg",
        "brand":"facebook",
        "offers":[
        {
        "@type":"Offer",
        "price":"7.99",
        "priceCurrency":"USD",
        "itemCondition":"https://schema.org/NewCondition",
        "availability":"https://schema.org/InStock"
        }
        ]
        <script>

Set Metadata Tags in Item 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>
...

Set Up Country and Language Feeds via the API (Optional)

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


Test Your Feed

Test your feed through our 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.

Upload Your Feed

To upload a feed, you need ads_management permission. See Marketing API, Permissions. After you create a catalog, use catalog id to create and schedule a Product Feed:

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.3/{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 how to read the Product Feed Upload Error Report

Schedule Data Feed Fetches

We fetch item feeds from your system on a schedule you define. There are two types of schedules you can define:

  • update_schedule — The uploads create new items or update existing ones with the information provided in the data feed file.
  • schedule — The uploads result in a complete refresh operation on your data feed. We delete items 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 data feed file for faster processing of feed. This is particularly better for holiday sales and faster price and availability updates. It's also recommended to mark items as "out of stock" rather than deleting from the feed so that we can retarget the user with similar available items.

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" : {FEED_ID} }

See Data Feed Reference, Data Feed Schedule Reference.

Direct Upload an Item Feed

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

Example — Feed files 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}/{FEED_ID}/uploads

Example — 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}/{FEED_ID}/uploads

Optionally, you can set update_only to true. We create new items and update existing ones, but don't 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 support all listed file formats; the most common ones are TSV and CSV. See Supported Feed Formats for more information.

Feed Format per Use Case


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 feed, see Feed Upload Errors, Reference.

Update an Individual Item

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

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

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

Do not provide item feeds with individual item updates, creation, or deletion with the API. This can disrupt any updates or deletes of items you created with the API because we don't track these with the feed.

See also: