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: 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: 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. |
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 Typically generated by automated feed provider systems or web servers. |
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 Typically generated by automated feed provider systems or web servers. |
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
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
<?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 & 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 & 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>For scheduling data feed fetches, see suggested formats below.
| Feed Format | Use Case | Sample Feed |
|---|---|---|
CSV | Update | |
TSV | Reset |
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's 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 added support for more use cases from catalog fields.
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 |
|---|---|
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 Example: |
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: |
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. Make sure that product descriptions satisfy catalog requirements. For commerce - To support HTML, use the Example: A vibrant crewneck for all shapes and sizes. Made from 100% cotton. |
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:
Example: |
type: string | Required for dynamic ads and commerce. Item's current condition in your store: Example: |
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: |
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: |
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. Make sure that product images satisfy catalog requirements. Example: |
type: string | Required for dynamic ads. For commerce, required if no manufacturer assigned 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 Example: |
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. |
type: string | Optional for dynamic ads. N/A for commerce. Age group associated to the item. Accepted values: |
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 Example: |
type: string | Optional for dynamic ads. Required for commerce. Determines gender for sizing. Supported values: |
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 For commerce - Provide the same Example: |
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: |
type: string | Optional for dynamic ads. N/A for commerce. Max character limit: 200 The material the item is made from. Supported values: Example: |
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: |
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: |
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: |
type: two ISO-8601 timestamp | Optional for dynamic ads and commerce. Start and end date and time for your sale in your timezone, written as Example: |
type: string | Optional for commerce. N/A for dynamic ads. Unique ID that represents shipping settings you have created in Commerce Manager Shipping Settings to associate with this product. This is a limited availability feature. Please contact your Facebook representative to get whitelisted. |
type: string | Optional for dynamic ads and commerce, but required for variants with sizes. Size of an item. Example size: Example numeric: |
type: string | Optional for dynamic ads. N/A for commerce. Max character limit: 100 Additional information about the item you want to include. |
type: string | Optional for dynamic ads. N/A for commerce. Max character limit: 100 Additional information about the item you want to include. |
type: string | Optional for dynamic ads. N/A for commerce. Max character limit: 100 Additional information about the item you want to include. |
type: string | Optional for dynamic ads. N/A for commerce. Max character limit: 100 Additional information about the item you want to include. |
type: string | Optional for dynamic ads. N/A for commerce. Max character limit: 100 Additional information about the item you want to include. |
type: string | N/A for dynamic ads. Optional for commerce. Max characters: 5000. Rich text (HTML) description for item. Supported tags include |
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. |
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 Example: |
type: string | N/A for dynamic ads. Required for commerce if no manufacturer assigned Max characters: 100. Unique manufacturer ID for item. For commerce, Daily Deals inventory must also include Example: |
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 Ex: |
type: date | N/A for dynamic ads. Optional for commerce. For item with |
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. |
type: string | N/A for dynamic ads. Optional for commerce. Toggle visibility on product. Supported values:
Items in |
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 Example: |
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:
|
type: string | N/A for dynamic ads. Optional for commerce. Link to mobile-optimized page for item on the merchant's website. |
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: |
| Name | Description |
|---|---|
| Title of the item. |
| Description of the item. |
| Complete URL for the product page. |
| Link to the image used on the product page. |
| Brand name of the item. |
| Current availability of the item: |
| Current condition of the item: |
| Current price of the item. Don't include symbols, such as “$” in the price. |
| Currency for the price in ISO format (for example, |
| Retailer's ID for the item. |
| Name | Description |
|---|---|
| Title of the item. |
| Brand of the item. |
| Description of the item. |
| Retailer's ID for the item. |
| Complete URL for the product page. |
| Link to the image used on the product page. |
| Current price of the item. Don't include symbols, such as “$” in the price. Include this entry under “offers”. |
| Currency for the price, in ISO format (for example, |
| Current availability of the item: |
| Current condition of the item: |
| Name | Description |
|---|---|
| Title of the item. |
| Brand of the item. |
| Description of the item. |
| Retailer's ID for the item. |
| Complete URL for the product page. |
| Vector of objects of type |
| Link to the image used on the product page. |
| Name | Description |
|---|---|
| Current price of the item. Don't include symbols, such as “$” in the price. Include this entry under “offers”. |
| Currency for the price, in ISO format (for example, |
| Current availability of the item: |
| Current condition of the item: |