Catalog Fields

A Product Catalog is a container of information about your products. Each individual product is described using a set of fields, that will be utilized differently depending on how you are consuming your catalog.

You may already have a catalog for Facebook Dynamic Ads for Products. This catalog contains a set of required fields that can be used as the foundation for your Commerce Catalog. Read the Data Model section to learn about additional fields requirements for your Commerce Catalog.

How Fields are used

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.

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

Commerce Catalog Data Model

Each item in the product feed supports the following attributes.

AttributeTypeRequiredDescription

id

string

Required

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

gtin

string

See notes

Global Trade Item Number (GTINs); can include UPC, EAN, JAN, and ISBN. Required for all new products with a GTIN assigned by manufacturer.

mpn

string

See notes

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

brand

string

See notes

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

title

string

Required

Title of item.

description

string

Required

Short text describing product. Use plain text (without HTML tags) for this field. If you want to support HTML, please use rich_text_description field.

rich_text_description

string

Optional

Optional rich text (HTML) description for product. Supported tags include: <b>, <i>, <em>, <strong>, <header> as well as all Header tags (<h1> thru <h6>), as well as <br>, <p>, <ul>, and <li>. If this field is provided, we will use it instead of description,

however the

description

field is still required

as it's a fallback.

link

string

Required

Link to item on the merchant's website. Provide a graceful fallback if you do not have a product URL (e.g. link to the merchant's Facebook page).

mobile_link

string

Optional

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

image_link

string

Required

URL of product image.

additional_image_link

string

Optional

You can include up to 10 additional images; provide them as comma-separated URLs.

size

string

Required for variants with sizes

Size of product e.g. Small, Large, or numeric, e.g. 8, 12.5, 23

color

string

Required for variants with colors

Color of product e.g. Green, Mauve, Midnight Blue, etc

gender

string

Required

Female

Male

Unisex

pattern

string

Required for variants with patterns

Pattern of product e.g. Flannel, Gingham, Polka dots, etc

inventory

integer

Optional, see note

Number of inventory count of the product (quantity). Note that your product will not be buyable unless inventory number is positive.

visibility

string

Optional

Toggle visibility on product. Options are published or staging (default is published). Products that are in staging visibility will not be shown to buyers, will not be available for product tagging on Instagram, and are not available for Dynamic Ads.

availability

string

Required

Whether item is in stock; Accepted values are:

  • in stock - Item ships immediately
  • out of stock - No plan to restock
  • preorder - Available in future
  • available for order - Ships in 1-2 weeks
  • discontinued - Discontinued

condition

string

Required

Product condition: new, refurbished, or used. Marketplace B2C products should mostly be new.

price

string

Required

Cost of item and currency. Currency should follow ISO 4217 currency codes such as 9.99 USD

return_policy_info

string

Optional

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

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

availability_date

date

Optional

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

expiration_date

date

Optional

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

sale_price

string

Optional

Discounted price if the item is on sale. Currency should follow ISO 4217 currency codes such as 9.99 USD

sale_price_effective_date

date

Optional

Start and end date and time for the sale, separated by slash 2014-11-01T12:00-0300/2014-12-01T00:00-0300

shipping_profile_id

string

Optional

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.

google_product_category

string

Required

Predefined values (string or category ID) from Google's product taxonomy. For example, Apparel & Accessories > Clothing > Dresses or 2271

product_type

string

Optional

Retailer-defined category for product, e.g. Home & Garden > Kitchen & Dining > Appliances > Refrigerators

item_group_id

string

Optional, Required for variants

For items that are variants of a product. Provide the same item_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

additional_variant_attribute

key-value pairs

Optional

Additional attributes that are not core attributes (size, color, gender, pattern, etc). Do not use a core attribute as an additional attribute. Ex: Scent:Fruity,Flavor:Apple

offer_price

string

Required for Daily Deals

Discounted price if the item is offered as a Daily Deal. Currency should be specified as the ISO 4217 currency code. Specified as 9.99 USD. The "offer_price" field value must be lower than the "price" field value by at least 15%

offer_price_effective_date

string as two ISO‑8601 timestamps

Required for Daily Deals

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

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

Example CSV Feed

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)

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