Reference - Catalog

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.

Format	Description
CSV	Comma-separated value. Works with most spreadsheet programs. 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. See examples for CSV feed for dynamic ads and CSV feed for commerce. Download (Right-click > Save Link As) You can reference our CSV (.csv) example files as you're creating your feed, but we recommend using Catalog Manager as your primary source.
TSV	Tab-separated value. Works with most spreadsheet programs. See guidelines for CSV. Download (Right-click > Save Link As)
RSS XML	Rich-Site Summary, Extensible Markup Language. 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. Typically generated by automated feed provider systems or web servers. Download (Right-click > Save Link As)
Atom XML	The Atom Syndication Format is an XML language used for web feeds, while the Atom Publishing Protocol (AtomPub or APP) is a simple HTTP-based protocol for creating and updating web resources. 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. Typically generated by automated feed provider systems or web servers. See example XML Feed (Atom) for commerce. 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,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,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,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,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,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,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,published,200

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>

Feed Format — Schedule Data Feed Fetches

For scheduling data feed fetches, see suggested formats below.

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)

Supported Fields

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 affects taxes and return policy, but not 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 added support for more use cases from catalog fields. Learn more about Google Product Category for Catalog Items, Ads Help Center.

Supported Fields for Products - 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 best practice column-naming conventions, use U.S. English for all fields.

Name Description

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. The `id` field must match the content ID for your pixel. Example: `FB_product_0001`
`title` type: string	Required for dynamic ads and commerce. Max character limit: 150 Name that's relevant and specific to each item. Include keywords and variants, such as brand names, item areas, attributes, or condition. Make sure that product titles satisfy catalog requirements. Example: `Blue Facebook T-Shirt (Unisex)`
`description` type: string	Required for dynamic ads and commerce. Max character limit: 5000 Short text describing item. Ensure that the description has enough information for the customer to make an informed decision to buy the product. For example, add material, sizes, other details, if needed. 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. Make sure that product descriptions satisfy catalog requirements. For commerce - To support HTML, use the `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` - Not available in current stock `discontinued` - Discontinued Example: `in stock`
`condition` type: string	Required for dynamic ads and commerce. Item's current condition in your store: `new`, `refurbished`, `used`, `used_fair`, `used_good`, `used_like_new`. 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. Recommendation for best quality is 1024 x 1024 resolution. 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 600px x 600px, and Facebook crops it to a 1:1 aspect ratio. Make sure that product images satisfy catalog requirements. 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. Example: `FB1234_shirts`
`google_product_category` type: string	Optional but recommended for dynamic ads (may contribute to improved ad performance). Optional for Instagram Shopping and Page shops, but required to enable onsite checkout on these channels (US only). Required for Marketplace (US only). Google product category (GPC) for the item. Use the category's taxonomy path or its ID number, listed here. If you use checkout on Instagram or Facebook (US only), an item's GPC affects its taxes and return policy. Learn more about the Google product category for catalog items, Ads Help Center. Example: `Apparel & Accessories > Clothing > Shirts & Tops` or `212`
`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 (Instagram Shopping, Page shops and Marketplace). Time range for your sale period, including the date, time, and time zone when your sale starts and ends. If you don't enter sale dates, any items with a `sale_price` remains on sale until you remove their sale price. Use this format: `YYYY-MM-DDT23:59+00:00/YYYY-MM-DDT23:59+00:00`: Enter the start date as `YYYY-MM-DD`. Enter "T" after start date. Enter the start time in a 24-hour format (00:00 to 23:59) followed by the UTC time zone (-12:00 to +14:00). Enter a "/" and then repeat the same format for your end date and time. The example below uses the PST time zone (-08:00). Example: `2020-04-30T09:30-08:00/2020-05-30T23:59-08:00`
`shipping` type: string	Optional for dynamic ads (but required to use a shipping-related overlay in your ads). N/A for commerce (Instagram Shopping, Page shops and Marketplace). Shipping details for the item, written as: `Country:Region:Service:Price`. Include the 3-digit ISO currency code after the price. To use the free shipping overlay, enter the price as `0.0`. Use "," to separate multiple shipping details for different regions or countries. Only people in the specified region or country will see shipping details for that region or country. You can leave out the region (keep the double "::") if your shipping details are the same for an entire country. Example (multiple shipping details for different regions): `US:CA:Ground:9.99 USD,US:NY:Air:15.99 USD` Example (no region): `SG::Air:14.99 SGD`
`size` type: string	Optional for dynamic ads and commerce, but 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. Required 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. Required for commerce 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. Required for commerce 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"}`
`launch_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	Optional for dynamic ads and 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.
`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. Example: `Scent:Fruity,Flavor:`

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. The id field must match the content ID for your pixel.

Example: FB_product_0001

title

type: string

Required for dynamic ads and commerce.

Max character limit: 150

Name that's relevant and specific to each item. Include keywords and variants, such as brand names, item areas, attributes, or condition. Make sure that product titles satisfy catalog requirements.

Example: Blue Facebook T-Shirt (Unisex)

description

type: string

Required for dynamic ads and commerce.

Max character limit: 5000

Short text describing item. Ensure that the description has enough information for the customer to make an informed decision to buy the product. For example, add material, sizes, other details, if needed. 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. Make sure that product descriptions satisfy catalog requirements.

For commerce - To support HTML, use the 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 - Not available in current stock
discontinued - Discontinued

Example: in stock

condition

type: string

Required for dynamic ads and commerce.

Item's current condition in your store: new, refurbished, used, used_fair, used_good, used_like_new. 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. Recommendation for best quality is 1024 x 1024 resolution.

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

Make sure that product images satisfy catalog requirements.

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.

Example: FB1234_shirts

google_product_category

type: string

Optional but recommended for dynamic ads (may contribute to improved ad performance). Optional for Instagram Shopping and Page shops, but required to enable onsite checkout on these channels (US only). Required for Marketplace (US only).

Google product category (GPC) for the item. Use the category's taxonomy path or its ID number, listed here.

If you use checkout on Instagram or Facebook (US only), an item's GPC affects its taxes and return policy. Learn more about the Google product category for catalog items, Ads Help Center.

Example: Apparel & Accessories > Clothing > Shirts & Tops or 212

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 (Instagram Shopping, Page shops and Marketplace).

Time range for your sale period, including the date, time, and time zone when your sale starts and ends. If you don't enter sale dates, any items with a sale_price remains on sale until you remove their sale price.

Use this format: YYYY-MM-DDT23:59+00:00/YYYY-MM-DDT23:59+00:00:

Enter the start date as YYYY-MM-DD.
Enter "T" after start date.
Enter the start time in a 24-hour format (00:00 to 23:59) followed by the UTC time zone (-12:00 to +14:00).
Enter a "/" and then repeat the same format for your end date and time.

The example below uses the PST time zone (-08:00).

Example: 2020-04-30T09:30-08:00/2020-05-30T23:59-08:00

shipping

type: string

Optional for dynamic ads (but required to use a shipping-related overlay in your ads). N/A for commerce (Instagram Shopping, Page shops and Marketplace).

Shipping details for the item, written as: Country:Region:Service:Price.

Include the 3-digit ISO currency code after the price.

To use the free shipping overlay, enter the price as 0.0.

Use "," to separate multiple shipping details for different regions or countries. Only people in the specified region or country will see shipping details for that region or country. You can leave out the region (keep the double "::") if your shipping details are the same for an entire country.

Example (multiple shipping details for different regions): US:CA:Ground:9.99 USD,US:NY:Air:15.99 USD

Example (no region): SG::Air:14.99 SGD

size

type: string

Optional for dynamic ads and commerce, but 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. Required 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. Required for commerce 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. Required for commerce 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"}

launch_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

Optional for dynamic ads and 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.

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.

Example: Scent:Fruity,Flavor:

OpenGraph Tags

Each field has a maximum of 500 characters.

The primary image link is required. Any additional image links are optional.

Name	Description
`og:title`	Required. Title of the item. Supports pixel-based catalogs.
`og:description`	Required. Description of the item. Supports pixel-based catalogs.
`og:url`	Required. Complete URL for the product page. Supports pixel-based catalogs.
`og:image`	Required for primary link. Optional for additional image links. Link to the image used on the product page. The primary image link is required. Any additional image links are optional. Supports pixel-based catalogs.
`og:locale`	Required if using multilanguage catalogs. Specifies which website version the product is from; for example, `en_GB` for the UK website. Supports pixel-based catalogs.
`og:price:amount`	Required. Current price of the item. For the separator, use '.' rather than ',' to indicate a decimal point. Don't include symbols, such as “$” in the price. Supports pixel-based catalogs. Example: `1500.00`
`og:price:currency`	Required. Currency for the price in ISO format. Supports pixel-based catalogs. Example: `USD`
`product:brand`	Required. Brand name of the item. Supports pixel-based catalogs.
`product:availability`	Required. Current availability of the item: `in stock`, `out of stock`, `preorder`, `available for order`, `discontinued`. Supports pixel-based catalogs.
`product:catalog_id`	Optional. Unique ID for item. Can be a variant for a product. This maps to `retailer_id` after the product is imported. The `id` field must match the content ID for your pixel. Supports pixel-based catalogs.
`product:category`	Optional. Max character limit: 250. Supports pixel-based catalogs. For dynamic ads, represents predefined values (string or category ID) from Google's product taxonomy. For commerce, represents the category of your product according to the Google's product taxonomy. Learn more about product categories for commerce. Learn more about Google Product Category for Catalog Items, Ads Help Center.
`product:condition`	Required. Current condition of the item: `new`, `refurbished`, `used`. Supports pixel-based catalogs.
`product:custom_label_[0-4]`	Optional. Max character limit: 100 Additional information about the item you want to include. Supports pixel-based catalogs.
`product:gender`	Optional. Determines gender for sizing: `Female`, `Male`, `Unisex`. Supports pixel-based catalogs.
`product:item_group_id`	Optional. 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. Supports pixel-based catalogs. Example: `FB1234_shirts`
`product:gtin`	Optional. 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). Supports pixel-based catalogs. Example: `4011200296908`
`product:isbn`	Optional. International Standard Book Number. ISBNs consist of 13 digits. Supports pixel-based catalogs.
`product:mfr_part_no`	Optional. Unique manufacturer part number for item. For commerce, Daily Deals inventory must also include brand if `mpn` is provided.Supports pixel-based catalogs. Example: `100020003`
`material`	Optional. Material the item is made from. Supported values: `cotton`, `denim`, `leather`. Supports pixel-based catalogs. Example: `cotton`
`product:locale`	Required if using multilanguage catalogs. Specifies which website version the product is from; for example, `en_GB` for the UK website. Supports pixel-based catalogs.
`product:price:amount`	Required. Current price of the item. For the separator, use '.' rather than ',' to indicate a decimal point. Don't include symbols, such as “$” in the price. Supports pixel-based catalogs. Example: `1500.00`
`product:price:currency`	Required. Currency for the price in ISO format. Supports pixel-based catalogs. Example: `USD`
`product:retailer_item_id`	Required. Retailer's ID for the item. Supports pixel-based catalogs.
`product:sale_price:amount`	Optional. 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. Supports pixel-based catalogs. Example: `9.99 USD`, `25.00 EUR`
`product:sale_price:currency`	Optional. 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. Supports pixel-based catalogs. Example: `9.99 USD`, `25.00 EUR`
`product:sale_price_dates:start`	Optional. Start date and time for your sale in your timezone, 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`. Write the time in a 24-hour format (0:00 to 23:59). Add a "T" after each date and then include the time, where the end time represents the time zone. In the example, `03:00` denotes the time zone. Supports pixel-based catalogs. Example: `2017-11-01T12:00-03:00/2017-12-01T00:00-03:00`
`product:sale_price_dates:end`	Optional. End date and time for your sale in your timezone, 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`. Write the time in a 24-hour format (0:00 to 23:59). Add a "T" after each date and then include the time, where the end time represents the time zone. In the example, `03:00` denotes the time zone. Supports pixel-based catalogs. Example: `2017-11-01T12:00-03:00/2017-12-01T00:00-03:00`

Schema.org – Required Tags

Each field has a maximum of 500 characters.

Name	Description
`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”. For the separator, use '.' rather than ',' to indicate a decimal point. Don't include symbols, such as “$” in the price. Example: 1500.00.
`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”.

JSON-LD for Schema.org — Required Tags

Each field has a maximum of 500 characters.

Extracted from schema.org/Product

Name	Description
`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`	Array 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)

Name	Description
`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”.

Learn More

Create a Data Feed for a Catalog
Methods to Add Catalog Items, Ads Help Center
Upload a Data Feed to a Catalog, Ads Help Center
Data Feed Specifications, Ads Help Center
Data Feed, Reference
Data Feeds in Catalog, Reference
Feed API, Reference
Item, Reference
Item Search in Catalog, Reference
Product Sets, Reference
Hotel Ads, Supported Fields
Flight Ads, Supported Fields
Destination Ads, Supported Fields
Automotive Inventory Ads, Supported Fields – Vehicle and Dealership
Real Estate Ads, Supported Fields