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.

FormatDescription

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)

If you receive an error, it means that a line in your XML data feed file is too long and exceeds our size limit of 5,242,880 bytes or characters. Please reformat your XML into multiple lines with 1 field per line and upload your file again. For more information, see Troubleshoot Data Feed Errors.

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)

Google Sheets

Catalog Manager also now supports Google Sheets for scheduled feeds:

  1. Create your data feed as a spreadsheet in Google Sheets and get the shareable link.
  2. When you add products in Catalog Manager, select the Google Sheets option. Copy and paste in your shareable link and finish your upload.
  3. Continue managing your inventory in the Google spreadsheet in future and we'll fetch from it at scheduled times.

Learn More

Example Feeds

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 Catalog 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.

Attribute and Type 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. Use the SKU if you can. Enter each ID only once or the item won't upload. If there are multiple instances of the same ID, we ignore all instances. For dynamic ads, this ID must exactly match the content ID for the same item in your Facebook pixel.

Example: FB_tshirt_001

title

Type: string

Required for dynamic ads and commerce.

Max character limit: 150

A specific, relevant title for the item. Include keywords, such as brand, 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

A short, relevant description of the item. Include specific or unique product features, such as like material or color. Don't include promotional text or any links. Use plain text and don't enter text in all capital letters. Ensure 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.

Current availability of the item in your store. Must be written in U.S. English. You must provide one of the following values in this field:

  • in stock - Item ships immediately

  • available for order - Ships in 1-2 weeks

  • out of stock - Not available in current stock

  • discontinued - Discontinued

Example: in stock

inventory

Type: integer

N/A for dynamic ads and commerce. Required for Instagram Shopping with checkout, Page shops, and Marketplace. Optional for Instagram Shopping with product tagging only.

Quantity of this item in your inventory. People can't buy this item unless the inventory is 1 or higher.

In a Page shop or Facebook Shops, an item shows as out of stock if inventory is 0, even if its availability is in stock.

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

Example: 75

condition

Type: string

Required for dynamic ads and commerce.

Condition of the item in your store. Supported values: new, refurbished, used.

Example: new

price

type: string

Required for dynamic ads and commerce.

Cost and currency of the item. Format the price as a number, followed by the 3-digit ISO currency code (ISO 4217 standards), with a space between cost and currency. Use a period (".") as the decimal point.

We recommend that you include only one (1) currency in your catalog so customers don't see mixed currencies for products in your ads or commerce channels. To add product information and prices that will display for other countries or languages, upload a country feed or language feed to your catalog instead.

Example: 9.99 USD, 25.00 EUR

link

Type: string

Required for dynamic ads and commerce.

URL of the specific product page where people can buy the item. f you don't have a URL, provide a fallback, like a link to your Facebook business Page.

Example: https://www.facebook.com/facebook_t_shirt

image_link

Type: string

Required for dynamic ads and commerce.

URL for the main image of your item. Follow these image specifications:

  • All images must be in JPG, GIF, or PNG format.
  • For Shops on Facebook and Instagram, carousel ads, and collection ads: Product images display in square (1:1) format. The minimum image size is 500 x 500 px. We recommend 1024 x 1024 px for best quality.
  • For single image ads: Images display at a 1.91:1 aspect ratio. Minimum image resolution is 500 x 500 px. We recommend 1200 x 628 px for best quality.
  • Image file size limit: 8 MB.

Learn more about product image recommendations.

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

Brand name, unique manufacturer part number (MPN), or Global Trade Item Number (GTIN) of the item. You only need to enter one of these, not all of them. For GTIN, enter the item's UPC, EAN, JAN, or ISBN.

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

URLs for additional images of the item. Include up to 20 image URLs. Use a comma to separate multiple URLs. Follow the same image specifications as the image_link field. Character limit: 2,000.

Example: https://www.fb.com/t_shirt_2.jpg,https://www.fb.com/t_shirt_3.jpg

age_group

Type: string

Optional for dynamic ads. N/A for commerce.

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

color

Type: string

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

Max character limit: 200.

Color of item. Use one or more words to describe the color, not a hex code.

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

Max character limit: 100


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, based on relevance or popularity.


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

commerce_tax_category

Type: string

N/A for dynamic ads. Optional for commerce.

An alternative to google_product_category, you can use commerce_tax_category to set an item-level tax category to individual items. The individual tax category will replace the default tax category set in Commerce Manager. Learn more about Facebook tax categories, Commerce Manager. See also full list of tax categories.

Example: FB_APRL_SHOE

material

Type: string

Optional for dynamic ads and commerce.

Max character limit: 200

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

Category the item belongs to according to your business's product categorization system, if you have one. You can also enter a Google product category. 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 and currency of the item, if the item is on sale. Format the price as a number, followed by the 3-digit ISO currency code (ISO 4217 standards), with a space between cost and currency. Use "." as the decimal for the sale price. A sale price is required if you want to use an overlay for discounted prices.

Example: 7.99 USD

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, as follows:

  1. Type the start date as YYYY-MM-DD.
  2. Type "T" after start date.
  3. Type the start time in a 24-hour format (00:00 to 23:59), followed by the UTC time zone (-12:00 to +14:00).
  4. Type 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.

Format the price as a number, followed by the 3-digit ISO currency code (ISO 4217 standards), with a space between cost and currency.

To use the free shipping overlay, type 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

shipping_weight

Type: string

Optional for dynamic ads.

Shipping weight of the item in lb, oz, g, or kg.

Example: 10 kg

size

Type: string

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

Max character limit: 200.

Size of an item, written as a word, abbreviation, or number.

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.

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 access.

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.

Example: {is_final_sale: "false", return_policy_days: "30"}

launch_date

Type: date

N/A for dynamic ads. Optional for commerce.

Note: This is a limited availability feature. Please contact your Facebook representative to get access.

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:

applink

Type: string

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 don't 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.

Supported applinks: applink.ios_url, applink.ios_app_store_id, applink.ios_app_name, applink.android_url, applink.android_package, applink.android_app_name, applink.windows_phone_url, applink.windows_phone_app_id, applink.windows_phone_app_name, applink.ipad_url, applink.ipad_app_store_id, applink.ipad_app_name. Learn more about product deep links.

Supported Fields — Localized Catalogs

Requirements

  • You must include an id field in your secondary data feed file. To run dynamic ads, the ID for each item must match its ID in your original catalog data feed and its content ID from your pixel.
  • You must include an override field. In this field, enter the ISO codes for the languages or countries that you want to provide localized information for. In this field, enter the ISO codes for the languages or countries that you want to provide localized information for. The value in the override column should be either a supported ISO language code or a supported ISO country code. Learn more about supported language codes and country codes.

Learn more about the id and override fields in Create a data feed with localized inventory information, steps 2 and 3.

Products

  • title
  • description
  • availability
  • link
  • brand
  • price
  • sale_price
  • sale_price_effective_date
  • color
  • size
  • material
  • pattern
  • custom_label_0
  • custom_label_1
  • custom_label_2
  • custom_label_3
  • custom_label_4
  • short_description
  • additional_variant_attribute
  • applink.ios_url, applink.ios_app_store_id, applink.ios_app_name, applink.android_url, applink.android_package, applink.android_app_name, applink.windows_phone_url, applink.windows_phone_app_id, applink.windows_phone_app_name, applink.ipad_url, applink.ipad_app_store_id, applink.ipad_app_name

To localize any applink fields, you must provide all of them. Learn more about product deep links.

  • image[0].url, image[0].tag[0]

To localize an image, you must use the image[0].url, image[0].tag[0] nested image fields. The image_link field isn't supported for localization.

For reference, see the main list of fields for products.


Hotels

  • name
  • description
  • base_price
  • sale_price
  • brand
  • url
  • city
  • country
  • neighborhood
  • longitude
  • latitude
  • image[0].url, image[0].tag[0]
  • applink.ios_url, applink.ios_app_store_id, applink.ios_app_name, applink.android_url, applink.android_package, applink.android_app_name, applink.windows_phone_url, applink.windows_phone_app_id, applink.windows_phone_app_name, applink.ipad_url, applink.ipad_app_store_id, applink.ipad_app_name

To localize any applink fields, you must provide all of them. Learn more about product deep links.

For reference, see the main list of fields for hotels.


Flights

  • description
  • url
  • origin_city
  • destination_city
  • price
  • one_way_price
  • image[0].url, image[0].tag[0]
  • applink.ios_url, applink.ios_app_store_id, applink.ios_app_name, applink.android_url, applink.android_package, applink.android_app_name, applink.windows_phone_url, applink.windows_phone_app_id, applink.windows_phone_app_name, applink.ipad_url, applink.ipad_app_store_id, applink.ipad_app_name

To localize any applink fields, you must provide all of them. Learn more about product deep links.

For reference, see the main list of fields for flights.


Destinations

  • name
  • description
  • url
  • price
  • city
  • country
  • neighborhood
  • longitude
  • latitude
  • image[0].url, image[0].tag[0]
  • applink.ios_url, applink.ios_app_store_id, applink.ios_app_name, applink.android_url, applink.android_package, applink.android_app_name, applink.windows_phone_url, applink.windows_phone_app_id, applink.windows_phone_app_name, applink.ipad_url, applink.ipad_app_store_id, applink.ipad_app_name

To localize any applink fields, you must provide all of them. Learn more about product deep links.

For reference, see the main list of fields for destinations.


Home Listings

  • name
  • description
  • price
  • url
  • image[0].url, image[0].tag[0]

For reference, see the main list of fields for home listings.


Vehicles

  • title
  • description
  • price
  • sale_price
  • url
  • image[0].url, image[0].tag[0]

For reference, see the main list of fields for vehicles.

OpenGraph Tags

Each field has a maximum of 500 characters.

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

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, 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.

NameDescription

name

Title of the item.

brand

Brand of the item.

description

Description of the item.

productID

Retailer's ID for the item.

url

Complete URL for the product page.

image

Link to the image used on the product page.

price

Current price of the item. Don't include symbols, such as “$” in the price. Include this entry under “offers”. Format the price as a number, followed by the 3-digit ISO currency code (ISO 4217 standards), with a space between cost and currency. Use a period (".") as the decimal point.

We recommend that you include only one (1) currency in your catalog so customers don't see mixed currencies for products in your ads or commerce channels. To add product information and prices that will display for other countries or languages, upload a country feed or language feed to your catalog instead.

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

NameDescription

name

Title of the item.

brand

Brand of the item.

description

Description of the item.

productID

Retailer's ID for the item.

url

Complete URL for the product page.

offers

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)

NameDescription

price

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

priceCurrency

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

availability

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

condition

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