Set Up Your Catalog Feed

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

Each line in your feed 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.

We recommend following these steps and guidelines to set up your catalog feed:

Learn More


Supported Feed Formats

Provide your feed in one of these formats:

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

Example CSV Feed

id,title,description,availability,condition,price,link,image_link,brand,additional_image_link,age_group,color,gender,item_group_id,google_product_category,pattern,product_type,sale_price,sale_price_effective_date,size,offer_price,offer_price_effective_date
FB_product_1234,Facebook T-Shirt (Unisex),A vibrant crewneck for all shapes and sizes. Made from 100% cotton.,in stock,new,9.99 USD,https://www.facebook.com/facebook_t_shirt,https://www.facebook.com/t_shirt_image_001.jpg,Facebook,https://www.facebook.com/t_shirt_image_002.jpg,adult,blue,unisex,FB1234_shirts,Apparel & Accessories > Clothing > Shirts,stripes1,Apparel & Accessories > Clothing > Shirts,4.99 USD,2017-12-01T0:00-23:59/2017-12-31T0:00-23:59,small,2.99 USD,2018-11-01T12:00-0300/2018-12-01T00:00-0300

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

Example XML Feed (Atom)

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel> 
    <title>My Deal Shop Products</title>
    <description>Product Feed for Facebook</description> 
    <link>https://www.mydealsshop.foo</link>
    <atom:link href="https://www.mydealsshop.foo/pages/test-feed" rel="self" type="application/rss+xml" />
    
     
        <item>
            <g:item_group_id>SKU-123123</g:item_group_id>
            <g:gtin>12345678912345</g:gtin>
            <g:google_product_category>Toys &amp; Games > Toys > Executive Toys > Magnet Toys</g:google_product_category>            
            <g:id>SKU-123123-RED</g:id>
            <g:title>WidgetThing</g:title>            
            <g:description>This product is the product you need to do the thing</g:description>
            <g:link>https://www.mydealsshop.foo/products/widgetthing</g:link>
            <g:image_link>https://cdn.mycdn.foo/files/123123123.jpg</g:image_link>  
            
            <additional_image_link>https://cdn.mycdn.foo/files/123123123_image2.jpg</additional_image_link>            
            <additional_image_link>https://cdn.mycdn.foo/files/123123123_image3.jpg</additional_image_link>
                        
            <color>Red</color>           
                    
            <additional_variant_attribute>
                <label>Style</label>
                <value>Cool</value>
            </additional_variant_attribute>
                    
            <g:brand>AcmeCo</g:brand>
            <g:condition>New</g:condition>  
          
            <g:availability>in stock</g:availability>
            
            <g:price>19.99 USD</g:price>
            <g:sale_price>9.99 USD</g:sale_price>
            <g:offer_price>7.99 USD</g:offer_price>
            <offer_price_effective_date>2018-07-25T01:35/2018-09-16T17:07</offer_price_effective_date>           
        </item>  

        <item>
            <g:item_group_id>SKU-123123</g:item_group_id>
            <g:gtin>12345678912346</g:gtin>
            <g:google_product_category>Toys &amp; Games > Toys > Executive Toys > Magnet Toys</g:google_product_category>            
            <g:id>SKU-123123-GREEN</g:id>
            <g:title>WidgetThing</g:title>            
            <g:description>This product is the product you need to do the thing</g:description>
            <g:link>https://www.mydealsshop.foo/products/widgetthing</g:link>
            <g:image_link>https://cdn.mycdn.foo/files/123123123.jpg</g:image_link>  
            
            <additional_image_link>https://cdn.mycdn.foo/files/123123123_image2.jpg</additional_image_link>            
            <additional_image_link>https://cdn.mycdn.foo/files/123123123_image3.jpg</additional_image_link>
                        
            <color>Green</color>           
                    
            <additional_variant_attribute>
                <label>Style</label>
                <value>Cool</value>
            </additional_variant_attribute>
                    
            <g:brand>AcmeCo</g:brand>
            <g:condition>New</g:condition>  
          
            <g:availability>in stock</g:availability>
            
            <g:price>19.99 USD</g:price>
            <g:sale_price>9.99 USD</g:sale_price>
            <g:offer_price>7.99 USD</g:offer_price>
            <offer_price_effective_date>2018-07-25T01:35/2018-09-16T17:07</offer_price_effective_date>           
        </item>   
         

    </channel>
</rss>

Supported Fields by Catalog Type

This section defines the required and optional fields for each catalog type:

For the purpose of column naming conventions, you should provide all fields in U.S. English.


Products - Dynamic Ads & Commerce

You should upload your inventory to Facebook using a catalog. For each catalog type, a product feed should be provided in one of the supported formats (CSV, TSV, RSS XML, ATOM XML).

For commerce catalogs, set up your catalog during merchant onboarding, and upload or configure your products using the Product Feed API.

The product feed will be used as the source of truth for updating product catalogs on Facebook, and fetched by Facebook periodically according to the configured interval. You should store the product feed ID, and use it to get upload status, errors and to change upload schedule.

Note: Catalogs don't currently support using the Batch API for CREATEs at this time. To create inventory, use the Feed API.

POST https://graph.facebook.com/vX.X/{product-catalog-id}/product_feeds
Token: PAGE_ACCESS_TOKEN

Request


`Request` Attribute`schedule` object {#schedule}

name

type: string

Required

schedule

type: schedule

Required

interval

type: string

Required

hour

type: number

Optional

url

type: string

Required

Scheduled feeds do not support uploads more frequently than once per hour. If you need to update inventory faster, please use the Direct Upload API.

Response

{
  "id": 215042069082048
}

Supported Fields — Dynamic Ads & Commerce


The following table defines the fields used to create a dynamic ads or commerce catalog, including the requirement level (required vs. optional). For more information about the commerce platform, see Inventory Management.

Name DescriptionDynamic AdsCommerce

id

type: string

Required.

Max characters: 100

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


Example: FB_product_0001

Y

Y

item_group_id

type: string

Optional, but required for variants (commerce).


For dynamic ads - Items that are variants of a product. With dynamic ads, we pick only one item out of the group based on the signal we received from the pixel or app.

For commerce - Provide the same product_group_id for all items that are variants. For example, Red Polo Shirt is a variant of Polo Shirt. We map this to retailer_product_group_id once we get your feed.

Y

Y

short_description

type: string

Optional.

Max size: 1000

More concise description of your item.

Y

Y

rich_text_description

type: string

Optional.

Max characters: 5000.

Rich text (HTML) description for item. Supported tags include <b>, <i>, <em>, <strong>, <header>. Includes all Header tags (<h1> thru <h6>), <br>, <p>, <ul>, and <li>. If this field is provided, we use it instead of description; however, the description field is still required because it's a fallback.

Y

Y

inventory

type: string

Optional.

Number of inventory count of the product (quantity). Note: Your product is not buyable unless the inventory number is positive.

Y

Y

availability

type: string

Required.

Item's current availability. Must be written in U.S. English. Provide one of the following values in this field; it can’t be left empty. If item in stock, use one of these accepted values:

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

Example: in stock

Y

Y

description

type: string

Required.

Max size: 5000

Short text describing item. Don't include promotional text or any links. Use plain text (without HTML tags) for this field. Don't enter text in all capital letters. Use line breaks or italics to format your description.

For commerce - To support HTML, use rich_text_description.

Example: A vibrant crewneck for all shapes and sizes. Made from 100% cotton.

Y

Y

condition

type: string

Required.

Item's current condition: new, refurbished, used. Must be written in U.S. English. Provide one of the values in this field; it can’t be left empty. Marketplace B2C products should mostly be new.

Y

Y

image_link

type: string

Required.

URL link to item image used in the ad. Provide proper image sizes.


For square (1:1) aspect ratios in the carousel ad format - Image should be 600x600. For single-image, dynamic ads - The minimum image resolution requirement is 1200x630. The minimum aspect ratio requirement 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.

Example: https://www.fb.com/t_shirt_1.jpg

Y

Y

additional_image_link

type: string

Optional.

For dynamic ads, you can include up to 20 additional images. For commerce, you can include up to 10 additional images. For both, provide the images as comma-separated URLs.

Y

Y

link

type: string

Required.

URL link to merchant's site (website landing page) where you can purchase or learn more about the item. Provide a graceful fallback if you don't have a URL (example: a link to the merchant's Facebook page).

Example: https://www.fb.com/t_shirt

Y

Y

title

type: string

Required.

Max size: 150

Name that's relevant and specific to each item. Include keywords and variants, such as brand names, item areas, attributes, or condition.

Example: Blue Facebook T-Shirt (Unisex)

Y

Y

price

type: string

Required.

Price of the item. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency.

Example: 9.99 USD, 25.00 EUR

Y

Y

sale_price

type: string

Optional, but required to use the Overlay feature for dynamic ads.

Discounted price for the product. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency. Use for overlays.

Example: 9.99 USD, 25.00 EUR

Y

Y

sale_price_effective_date

type: two ISO-8601 timestamp

Optional.

Start and end date and time for the sale, separated by a slash. Write the start and end dates as YYYY-MM-DD. Add a "T" after each date and then include the time. Write the time in a 24-hour format (0:00 to 23:59).

Example: 2017-11-01T12:00-03:00/2017-12-01T00:00-03:00

Y

Y

shipping

type: string

Optional.

Shipping price of the item. For free shipping, write the shipping price as 0.0. For every region where you ship your items, separate them with a comma. Add a "T" after each date and then include the time. Write the time in a 24-hour format (0:00 to 23:59). Use "::" for specific countries.

Example: US:CA:Ground:0.0,US:NY:Air:0.0, UK::Standard:9.95 GBP

Y

Y

gtin

type: string

Required for all new products with a GTIN assigned by the manufacturer.

Product's Global Trade Item Number (GTINs). Exclude dashes and spaces. Submit only valid GTINs as defined by the GTIN validation buide. Supported values are UPC (North America, 12 digits), EAN (Europe, 13 digits), JAN (Japan, 8 or 13 digits), ISBN (books, 13 digits).

Example: 4011200296908

Y

Y

mpn

type: string

Required if no manufacturer assigned gtin.

Max characters: 100.

Product's unique manufacturer part number. Daily Deals inventory must also include brand if mpn is provided.

Example: 100020003

Y

Y

brand

type: string

Required if no manufacturer assigned gtin.

Max characters: 100

Product's brand name. Daily Deals inventory must also include mpn if brand is provided. Required if no manufacturer assigned gtin.

Example: Facebook

Y

Y

size

type: string

Required for variants with sizes.

Size of product. Example: Small, Large Numeric. Example: 8, 12.5, 23 string

N

Y

color

type: string

Optional, but Required for variants with colors.

Max size: 200.

Color of item. Use a language description. Don't use alphanumeric descriptions, such as FF0000; use only one color.
Example: Green, Mauve, Midnight Blue

N

Y

return_policy_info

type: string

Optional.

Note: This is a limited availability feature. Please contact your FB representative to get whitelisted.

Product return policy information For "final sale" status, use string {is_final_sale: "true", return_policy_days: "0"}. Products that are "final sale" are not eligible for returns.

Ex: {is_final_sale: "false", return_policy_days: "30"} .

N

Y

availability_date

type: date

Optional. For item with preorder availability, when the item will become available. This date should follow the ISO‑8601 (YYYY‑MM‑DD) format.

N

Y

expiration_date

type: ISO‑8601

Optional

Product expiration. If the product is expired, it won't be shown on Facebook. This date should follow the ISO‑8601 (YYYY‑MM‑DD) format.

Y

Y

age_group

type: string

Optional

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

Y

N

gender

type: string

Optional

Determine gender for sizing. Values include Female, Male, Unisex.

Example: Female

N

Y

pattern

type: string

Required for variants with patterns.

Pattern of product.

Example: Flannel, Gingham, Polka dots.

N

Y

google_product_category

type: string

Optional (ads), Required (commerce)

Predefined values (string or category ID) from Google's product taxonomy.

Example: Apparel & Accessories > Clothing > Dresses or 2271.

N

Y

visibility

type: string

Optional.

Toggle visibility on product.

  • published - Default. Enables the item to be visible to users.
  • staging - For commerce only — Item remains hidden from the user, but present in the catalog.
  • hidden - For dynamic ads and commerce — Item remains hidden from the user, but present in the catalog.
  • whitelist_only - Item is hidden from the user until it's manually approved by a reviewer (policy).

Items in staging mode are not visible to buyers, and are not available for product tagging on Instagram, nor for dynamic ads.

Y

Y

offer_price

type: string

Required for Daily Deals

Discounted price if the item is offered as a Daily Deal. The offer_price field value must be lower than the price field value by at least 15%. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency. Example: 9.99 USD.

N

Y

offer_price_effective_date

type: string as two ISO-8601 timestamps

Required for Daily Deals

Start and end date and time for the deal, separated by slash.

Example: 2018-06-01T12:00-0300/2018-12-01T00:00-0300.

N

Y

custom_label_0

type: string

Optional

Max character limit: 100

Additional information about the product you want to include.

Example: Made in Waterford, IE

Y

N

custom_label_1

type: string

Optional

Max character limit: 100

Additional information about the product you want to include.

Example: Made in Waterford, IE

Y

N

custom_label_2

type: string

Optional

Max character limit: 100

Additional information about the product you want to include.

Example: Made in Waterford, IE

Y

N

custom_label_3

type: string

Optional

Max character limit: 100

Additional information about the product you want to include.

Example: Made in Waterford, IE

Y

N

custom_label_4

type: string

Optional

Max character limit: 100

Additional information about the product you want to include.

Example: Made in Waterford, IE

Y

N


Provide deep links in feed following the App Links specification. Deep link information in 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.

NameDescription

android_app_name

Optional.

Name of app for display

Example: Electronic Android

android_package

Optional.

Fully-qualified package name for intent generation

Example: com.electronic

android_url

Optional.

Custom scheme for Android app as URL

Example: android://electronic

ios_app_name

Optional.

Name of app to display

Example: Electronic iOS

ios_app_store_id

Optional.

App ID for App Store

Example: 1234

ios_url

Optional.

Custom scheme for iOS app as URL

Example: ios://electronic

ipad_app_name

Optional.

Name of app to display

Example: Electronic iPad

ipad_app_store_id

Optional.

App ID for App Store

Example: 9010

ipad_url

Optional.

Custom scheme for iPhone app

Example: ipad://electronic

iphone_url

Optional.

Custom scheme for iPhone app as URL

Example: iphone://electronic

iphone_app_store_id

Optional.

App ID for App Store

Example: 5678

iphone_app_name

Optional.

Name of app to display

Example: Electronic iPhone

windows_phone_app_id

Optional.

App ID, as a GUID, for app store

Example: ee728e01-7727-4168-9c8f-85c7eef40112

windows_phone_app_name

Optional.

Name of app for display

Example: Electronic Windows

windows_phone_url

Optional.

Custom scheme for Windows Phone app as URL

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