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 (and Best Practices — Commerce Ads) to set up your catalog feed:

Learn More


Supported Feed Formats

Inventory should be uploaded to Facebook using a catalog. For each catalog, a product feed should be provided in one of the supported formats (CSV, TSV, RSS XML, ATOM XML).

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 — Dynamic Ads

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

Example CSV Feed — Commerce

id,title,description,rich_text_description,availability,condition,price,link,image_link,brand,additional_image_link,age_group,color,gender,item_group_id,google_product_category,product_type,sale_price,sale_price_effective_date,size,offer_price,offer_price_effective_date,return_policy_info,visibility,inventory
FB_product_1234,Facebook T-Shirt (Unisex),A vibrant crewneck for all shapes and sizes. Made from 100% cotton.,"<p>A vibrant crewneck for all shapes and sizes. Made from 100% cotton.</p> <p> Made of 52% combed and ringspun cotton, 48% polyester.</p>",in stock,new,9.99 USD,https://www.facebookswagstore.com/American-Apparel-T-Shirt-P395.aspx,https://www.facebookswagstore.com/GetImage.ashx?Path=%7e%2fAssets%2fFB00-0967-Group_Full.jpg&maintainAspectRatio=true&maxHeight=400&maxWidth=400,Facebook,https://www.facebookswagstore.com/Assets/ProductImages/FB00-0475.jpg,adult,blue,unisex,FB1234_shirts,Apparel & Accessories > Clothing > Shirts & Tops,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,"{is_final_sale: ""false"", return_policy_days: ""30""}",published,200
FB_product_1235,Facebook T-Shirt (Unisex),A vibrant crewneck for all shapes and sizes. Made from 100% cotton.,"<p>A vibrant crewneck for all shapes and sizes. Made from 100% cotton.</p> <p> Made of 52% combed and ringspun cotton, 48% polyester.</p>",in stock,new,9.99 USD,https://www.facebookswagstore.com/American-Apparel-T-Shirt-P395.aspx,https://www.facebookswagstore.com/GetImage.ashx?Path=%7e%2fAssets%2fFB00-0967-Group_Full.jpg&maintainAspectRatio=true&maxHeight=400&maxWidth=400,Facebook,https://www.facebookswagstore.com/Assets/ProductImages/FB00-0475.jpg,adult,blue,unisex,FB1234_shirts,Apparel & Accessories > Clothing > Shirts & Tops,Apparel & Accessories > Clothing > Shirts,4.99 USD,2017-12-01T0:00-23:59/2017-12-31T0:00-23:59,medium,2.99 USD,2018-11-01T12:00-0300/2018-12-01T00:00-0300,"{is_final_sale: ""false"", return_policy_days: ""30""}",published,200
FB_product_1236,Facebook T-Shirt (Unisex),A vibrant crewneck for all shapes and sizes. Made from 100% cotton.,"<p>A vibrant crewneck for all shapes and sizes. Made from 100% cotton.</p> <p> Made of 52% combed and ringspun cotton, 48% polyester.</p>",in stock,new,9.99 USD,https://www.facebookswagstore.com/American-Apparel-T-Shirt-P395.aspx,https://www.facebookswagstore.com/GetImage.ashx?Path=%7e%2fAssets%2fFB00-0967-Group_Full.jpg&maintainAspectRatio=true&maxHeight=400&maxWidth=400,Facebook,https://www.facebookswagstore.com/Assets/ProductImages/FB00-0475.jpg,adult,blue,unisex,FB1234_shirts,Apparel & Accessories > Clothing > Shirts & Tops,Apparel & Accessories > Clothing > Shirts,4.99 USD,2017-12-01T0:00-23:59/2017-12-31T0:00-23:59,large,2.99 USD,2018-11-01T12:00-0300/2018-12-01T00:00-0300,"{is_final_sale: ""false"", return_policy_days: ""30""}",published,200
FB_product_1237,Facebook T-Shirt (Unisex),A vibrant crewneck for all shapes and sizes. Made from 100% cotton.,"<p>A vibrant crewneck for all shapes and sizes. Made from 100% cotton.</p> <p> Made of 52% combed and ringspun cotton, 48% polyester.</p>",in stock,new,9.99 USD,https://www.facebookswagstore.com/American-Apparel-T-Shirt-P395.aspx,https://www.facebookswagstore.com/GetImage.ashx?Path=%7e%2fAssets%2fFB00-0967-Group_Full.jpg&maintainAspectRatio=true&maxHeight=400&maxWidth=400,Facebook,https://www.facebookswagstore.com/Assets/ProductImages/FB00-0475.jpg,adult,black,unisex,FB1234_shirts,Apparel & Accessories > Clothing > Shirts & Tops,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,"{is_final_sale: ""false"", return_policy_days: ""30""}",published,200
FB_product_1238,Facebook T-Shirt (Unisex),A vibrant crewneck for all shapes and sizes. Made from 100% cotton.,"<p>A vibrant crewneck for all shapes and sizes. Made from 100% cotton.</p> <p> Made of 52% combed and ringspun cotton, 48% polyester.</p>",in stock,new,9.99 USD,https://www.facebookswagstore.com/American-Apparel-T-Shirt-P395.aspx,https://www.facebookswagstore.com/GetImage.ashx?Path=%7e%2fAssets%2fFB00-0967-Group_Full.jpg&maintainAspectRatio=true&maxHeight=400&maxWidth=400,Facebook,https://www.facebookswagstore.com/Assets/ProductImages/FB00-0475.jpg,adult,black,unisex,FB1234_shirts,Apparel & Accessories > Clothing > Shirts & Tops,Apparel & Accessories > Clothing > Shirts,4.99 USD,2017-12-01T0:00-23:59/2017-12-31T0:00-23:59,medium,2.99 USD,2018-11-01T12:00-0300/2018-12-01T00:00-0300,"{is_final_sale: ""false"", return_policy_days: ""30""}",published,200
FB_product_1239,Facebook T-Shirt (Unisex),A vibrant crewneck for all shapes and sizes. Made from 100% cotton.,"<p>A vibrant crewneck for all shapes and sizes. Made from 100% cotton.</p> <p> Made of 52% combed and ringspun cotton, 48% polyester.</p>",in stock,new,9.99 USD,https://www.facebookswagstore.com/American-Apparel-T-Shirt-P395.aspx,https://www.facebookswagstore.com/GetImage.ashx?Path=%7e%2fAssets%2fFB00-0967-Group_Full.jpg&maintainAspectRatio=true&maxHeight=400&maxWidth=400,Facebook,https://www.facebookswagstore.com/Assets/ProductImages/FB00-0475.jpg,adult,black,unisex,FB1234_shirts,Apparel & Accessories > Clothing > Shirts & Tops,Apparel & Accessories > Clothing > Shirts,4.99 USD,2017-12-01T0:00-23:59/2017-12-31T0:00-23:59,large,2.99 USD,2018-11-01T12:00-0300/2018-12-01T00:00-0300,"{is_final_sale: ""false"", return_policy_days: ""30""}",published,200

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) — Commerce

<?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

Catalog fields are instrumental to the quality of the experience for customers buying products on your Facebook Shop or Instagram Shopping channels. This information is used in many ways, and will affect both the user experience and the business logic, including how tax is calculated.

Catalog fields are used to populate the Product Details Page for each item. This includes important information such as the product description, images, size/color variants, price, and inventory. Missing or bad data can negatively affect the user experience, impact conversion to purchases, or could be misleading and erode trust.

For commerce catalogs, some fields are used to inform business logic on our backend. For example, the google_product_category field identifies the tax rate for your product; it is also used to determine if the product is eligible for Purchase Protection. A wrong product category can affect tax calculations, and ultimately lead to remitting incorrect tax amounts. As we expand platform capabilities, you can expect us to add support for more use cases from catalog fields.

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.

Catalogs don't currently support using the Batch API for CREATEs at this time. To create inventory, use the Feed API, Reference, Dynamic Ads or Feed API, Reference, Commerce Platform.

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


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 Description

id

type: string

Required for dynamic ads and commerce.

Max character limit: 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

title

type: string

Required for dynamic ads and commerce.

Max character limit: 100

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)

description

type: string

Required for dynamic ads and commerce.

Max character limit: 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.

availability

type: string

Required for dynamic ads and commerce.

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

  • in stock - Item ships immediately

  • available for order - Ships in 1-2 weeks

  • preorder - Available in future

  • out of stock - No plan to restock

  • discontinued - Discontinued

Example: in stock

condition

type: string

Required for dynamic ads and commerce.

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

Example: new

price

type: string

Required for dynamic ads and commerce.

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

link

type: string

Required for dynamic ads and commerce.

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

image_link

type: string

Required for dynamic ads and commerce.

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 x 00px, and Facebook crops it to a 1:1 aspect ratio.

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

brand

type: string

Required for dynamic ads. For commerce, required if no manufacturer assigned gtin.

Max characters: 100

Product's brand name. You can use unique manufacturer part number (MPN), Global Trade Item Number (GTIN), or brand name for your product. You only need to use one of these values for this column (not all of them).

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

Example: Facebook

additional_image_link

type: string

Optional for dynamic ads and commerce.

Maximum character limit: 2000

Additional image URLs for the item. You can include up to 10 image URLs. Use "," to separate each URL.

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.

age_group

type: string

Optional for dynamic ads. N/A for commerce.

Age group associated to the item. Accepted values: newborn, infant, toddler, kids, adult.

color

type: string

Optional for dynamic ads and commerce, but required for variants with colors.

Max size: 100.

Color of item. Use a language description. Don't use alphanumeric descriptions, such as FF0000; use only one color.

Example: Green, Mauve, Midnight Blue

gender

type: string

Optional for dynamic ads, required for commerce.

Determines gender for sizing. Supported values: Female, Male, Unisex.

item_group_id

type: string

Optional for dynamic ads and commerce, but required for variants.


For dynamic ads - Items that are variants of a product. Provide the same item_group_id for all items that are variants. For example, a red Polo Shirt is a variant of Polo Shirt. Facebook maps this to the retailer_product_group_id once we get your feed. With dynamic ads, Facebook picks only one item out of the group based on the signal we receive from the pixel or app event.

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. Facebook maps this to retailer_product_group_id once we get your feed. Learn more about Product Variants, Commerce Platform.

Example: FB1234_shirts

google_product_category

type: string

Optional for dynamic ads, Required for commerce.

Max character limit: 250

For dynamic ads, represents predefined values (string or category ID) from Google's product taxonomy. Learn more about product categories for commerce.

For commerce, represents the category of your product according to the Google's product taxonomy. You must ensure that this value is accurate as it's being used for important business logic in the Commerce Platform, such as tax calculations and Purchase Protection.

Example: Apparel & Accessories > Clothing > Dresses or 2271

material

type: string

Optional for dynamic ads, N/A for commerce.

Max character limit: 200

The material the item is made from. Supported values: cotton, denim, leather.

Example: cotton

pattern

type: string

Optional for dynamic ads. For dynamic ads and commerce, required for variants with patterns.

Max character limit: 100

Pattern or graphic print on an item.

Example: Flannel, Gingham, Polka dots, stripes

product_type

type: string

Optional for dynamic ads and commerce.

Max character limit: 750

Retailer-defined category for product. For commerce, represents the product category in your internal system. Learn more about product categories for commerce.

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

sale_price

type: string

Optional for dynamic ads and commerce.

Discounted price if the item is on sale. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency. Use "." as the decimal for the sale price. The sale price is required if you plan to use an overlay for discounted prices.

Example: 9.99 USD, 25.00 EUR

sale_price_effective_date

type: two ISO-8601 timestamp

Optional for dynamic ads and commerce.

Start and end date and time for your sale, written as YYYY-MM-DDT0:00-23:59/YYYY-MM-DDT0:00-23:59, 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

shipping

type: string

Optional for dynamic ads, N/A for commerce.

Type of shipping for an item. Written as COUNTRY:STATE:SHIPPING_TYPE:PRICE. Use ";" to separate different regions. Use "::" for specific countries. For free shipping, write the shipping price as 0.0. For every region where you ship your items, separate them with a comma.

Example: UK::Standard:9.95 GBP, US:CA:Ground:9.99 USD

shipping_weight

type: string

Optional for dynamic ads, N/A for commerce.

Shipping weight of an item. Supported values: lb, oz, g, kg.

Example: 0.3 lb

size

type: string

Optional for dynamic ads and commerce, required for variants with sizes.

Size of an item.

Example size: Small, Large, 'XL'.

Example numeric: 8, 12, 23

custom_label_0

type: string

Optional for dynamic ads, N/A for commerce.

Max character limit: 100

Additional information about the item you want to include.

custom_label_1

type: string

Optional for dynamic ads, N/A for commerce.

Max character limit: 100

Additional information about the item you want to include.

custom_label_2

type: string

Optional for dynamic ads, N/A for commerce.

Max character limit: 100

Additional information about the item you want to include.

custom_label_3

type: string

Optional for dynamic ads, N/A for commerce.

Max character limit: 100

Additional information about the item you want to include.

custom_label_4

type: string

Optional for dynamic ads, N/A for commerce.

Max character limit: 100

Additional information about the item you want to include.

rich_text_description

type: string

N/A for dynamic ads, Optional for commerce.

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.

inventory

type: integer

N/A for dynamic ads, Optional for commerce.

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

For more information about inventory, see Inventory, Commerce Platform.

gtin

type: string

N/A for dynamic ads. For commerce: 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 guide. Supported values are UPC (North America, 12 digits), EAN (Europe, 13 digits), JAN (Japan, 8 or 13 digits), ISBN (books, 13 digits).

Example: 4011200296908

mpn

type: string

****N/A for dynamic ads. For commerce: Required if no manufacturer assigned gtin.**

Max characters: 100.

Unique manufacturer ID for item. For commerce, Daily Deals inventory must also include brand if mpn is provided.

Example: 100020003

return_policy_info

type: string

N/A for dynamic ads, Optional for commerce.

Note: This is a limited availability feature. Please contact your Facebook 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"}

availability_date

type: date

N/A for dynamic ads, Optional for commerce.

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

expiration_date

type: date

N/A for dynamic ads, Optional for commerce.

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.

visibility

type: string

N/A for dynamic ads, Optional for commerce.

Toggle visibility on product. Supported values:

  • published - Default. Enables the item to be visible to users.
  • staging - Item remains hidden from the user, but present in the catalog.
  • hidden - 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.

offer_price

type: string

N/A for dynamic ads. For commerce, 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

offer_price_effective_date

type: string as two ISO-8601 timestamps

*N/A for dynamic ads. For commerce, 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

mobile_link

type: string

N/A for dynamic ads, Optional for commerce.

Link to mobile-optimized page for item on the merchant's website.

additional_variant_attribute

type: string

N/A for dynamic ads, Optional for commerce.

Additional attributes that are not core attributes (size, color, gender, pattern, and so on). Do not use a core attribute as an additional attribute. Learn more about Product Variants, Commerce Platform.

Example: Scent:Fruity,Flavor:


Product Categories

Two different catalog fields describe the type or category of products in your listing:

  • product_type
  • google_product_category

See Supported Fields — Dynamic Ads & for details about each field.

Tax Calculations

For the most part, we calculate tax on your behalf. Tax rates depend on individual state laws and may vary state by state, they also depend on the category of each product in your catalog listing. Destination-based tax are calculated using your state tax registration information (provided during set-up) and the google_product_category of the product. You must provide at minimum a level 2 sub-category (eg. Apparel & Accessories > Clothing > Dresses).

You are responsible for reviewing and determining the correct product category for your product listings. You can use our tax tool in Commerce Manager to verify our tax calculation logic.

Purchase Protection

If an item meets Facebook's eligibility requirements for Purchase Protection, buyers will see a “Covered by purchase protection” indication in the Product Detail Page for the item. We use the google_product_category field to determine the product's eligibility for Purchase Protection.

Read our Purchase Protection policy to learn more about the requirements and eligible product categories.


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.

Learn more about Product Variants, Commerce Platform.

Best Practices — Commerce Ads

We recommend to use this checklist to maximize the quality of your catalog:

  • Make sure that id, title, description, price, inventory, link, image_link fields are present.
  • Use additional_image_link to add more product images (up to 10).
  • Make sure that product images satisfy Instagram requirements.
  • Make sure that gtin or mpn plus brand fields are present.
  • Make sure that rich_text_description (preferably) or description fields are present, well formatted (no extra spacing, punctuation is correct), and informative (may contain information on item size, volume, origin, and so on).
  • Ensure that the description field must does not contain HTML tags or character entities.
  • Ensure that the availability and inventory fields are populated according a [agreed upon strategy](link to inventory section).
  • Ensure that the link URL responds with HTTP 200 OK.
  • Ensure that the price is in the correct format and currency.
  • Ensure that the sale_price is provided for items on sale.
  • Ensure that the google_product_category is at minimum 2 levels deep
  • Ensure that product variants are sharing the same item_group_id.
  • Ensure that the variant field's (such as size or color) value is present for every product variant sharing a common item_group_id, even those that are out of stock.
  • Ensure that the offer_price and offer_price_effective_date fields are present if you're planning for the product to be featured as a Daily Deal. Learn more about Daily Deals.
  • Check the Product Catalog diagnostics tool for the following information each time you upload a new product feed:
    • Fix all upload errors, a product marked with an error will be rejected from your catalog.
    • Verify all warnings, some of warnings may affect product ingestion and prevent your product from being tagged or available for purchase.
    • Ensure that each product complies with the Facebook Commerce Policies. Product that violate the policy will be marked as rejected and will not be available for tagging or purchase.