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

Use this guide to learn more about additional field requirements and recommendations:

How to Use Catalog Fields

Catalog fields are instrumental to the quality of the experience for customers buying products on your Facebook Shop or Instagram Shopping channels:

  • Product details — 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 inaccurate data can negatively affect the user experience, impact conversion to purchases, or could be misleading and erode trust.

  • Business logic — 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.

  • Optional fields — All catalog fields are considered recommended, but some are identified as required or optional, per the use case for the field.

For Facebook Shops, there is a minimum set of information customers need to provide about their product items to upload into a Shop. This is the same requirement to run a dynamic ads campaign. If your business is using onsite checkout, there are more required fields; for example, inventory. Learn more about supported fields for your catalog.

  • Category-specific information — Providing detailed, high-quality information about your products ensures customers can discover your products and make well-informed purchase decisions. This means enhancing your catalog by providing category-specific information about your products and making sure the information in each field is accurate and up-to-date.

When using category-specific fields, you must provide a category identifier — a Google Product Category or a Facebook product category. If you provide one of these category fields, you can also use additional fields specific to that category to provide more detailed information about your items.

As we expand platform capabilities, you can expect added support for more use cases from catalog fields.

Universal Basic Attributes

Each item in your product feed supports the following universal basic attributes.

Attribute and TypeDescription

id

Type: string

Required for all categories.

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. Supported value is numerical.

Example: FB_tshirt_001

title

Type: string

Required for all categories.

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. Supported value is open text.

Example: Blue Facebook T-Shirt (Unisex)

description

Type: string

Required for all categories.

Max character limit: 9999

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. Supported value: open text.

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 all categories.

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

quantity_to_sell_on_facebook

Type: integer

N/A for dynamic ads. Required only if you sell directly on Facebook or Instagram with checkout.

The quantity of this item that you have available to sell on Facebook and Instagram. Enter a whole number. We automatically reduce an item's quantity each time a purchase order is confirmed through checkout. Note: To display as in stock for checkout, an item's quantity_to_sell_on_facebook must be 1 or higher and its availability field must also be set to in stock.


Example: 150

Only include this field if you sell with checkout. This field was previously called inventory. While we still support the old field name, we recommend that you use the new name.

condition

Type: string

Required for all categories.

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

Example: new

price

Type: string

Required for all categories.

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 commerce channels.

Example: 9.99 USD, 25.00 EUR

link

Type: string

Required for all categories.

URL of the specific product page where people can buy the item. If 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 all categories.

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

video

Type: string

Optional.

The URL and tags for the video of your item. Videos must be in formats: 3g2, 3gp, 3gpp, asf, avi, dat, divx, dv, f4v, flv, gif, m2ts, m4v, mkv, mod, mov, mp4, mpe, mpeg, mpeg4, mpg, mts, nsv, ogm, ogv, qt, tod, ts, vob, and wmv.


Video size should be a minimum of 1KB and a maximum of 2GB.


Example:

{url: 'https://www.facebook.com/sample-file.avi', tag: ['Tag1', 'Tag2']}

brand

Type: string

Required for all categories 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

fb_product_category

Type: string

The Facebook product category represents the item according to the Facebook product taxonomy. This taxonomy organizes products for sale into categories and subcategories. For example, Health & Beauty > Beauty > Makeup > Eye Makeup > Mascara.


To provide a Facebook product category for your items, add the fb_product_category field in your data feed file. In this field, enter a supported category from the list below. Facebook product categories are available in multiple languages. Download the list of categories in your language below; for example, U.S. English (Plain text (.txt) | Spreadsheet (.csv)).


For each category, you can provide either the taxonomy path (such as Health & Beauty > Beauty > Makeup > Eye Makeup > Mascara) or the category ID number (such as 281). Category names are not case sensitive.


When you provide a Facebook product category, you can also use additional fields specific to that category to provide more detailed information about your items.

If you use checkout on Instagram or Facebook (U.S. only):

google_product_category

Type: string

Optional for Instagram Shopping and Page Shops, but required to enable onsite checkout on these channels (U.S. only). Required for Marketplace (U.S. only).


The Google product category (GPC) (google_product_category) represents the item according to the Google's product taxonomy.


Use the category's taxonomy path or its category ID number, listed here.

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


If you use checkout on Instagram or Facebook (U.S. only):

product_type

Type: string

Optional for all categories.

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 all categories, Required if sale.

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 all categories, Required if checkout.

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

unit_price

Type: string

Optional for dynamic ads and commerce (Instagram Shopping, Page shops and Marketplace).

Provide this information for any products customarily sold by a unit of measurement (for example "$10 / pound"). To specify this information, provide the following:

Amount value: this is a float
Currency: any supported currency
Unit type: any of the following measurements:


Centiliters: cl
Centimeters: cm
Count: ct
Cubic Meters: cbm
Feet: ft
Fluid Ounces: fl oz
Gallons: gal
Grams: g
Inches: in
Kilograms: kg
Liters: l
Meters: m
Milligrams: mg
Milliliters: ml
Ounces: oz
Pints: pt
Pounds: lb
Quarts: qt
Square Feet: sqft
Square meters: sqm
Yards: yd


This information is uploaded via feed uploads in the unit_price field in a JSON format as follows:

{value: 10.0, currency: "USD", unit: "lb"}

It can also be uploaded via XML as follows:

<unit_price>
 <value>10</value>
 <currency>USD</currency>
 <unit>lb</unit>
</unit_price>

Download a sample CSV file with an example of adding unit_price to products.

shipping

Type: string

Optional.

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.

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

Example: 10 kg

item_group_id

Type: string

Optional, but Required for variants.

Max character limit: 100

Group ID if item is a variant. 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

size

Type: string

Optional, but required for variants with sizes.

Max character limit: 200.

Size of the item written as a word, abbreviation or number, such as small, XL or 12.

Example size: Small, Medium, Large.

Example numeric: 8, 12, 23

marked_for_product_launch

Type: string

Optional.

Indicates whether an item will be used in a product launch. Supported values:

  • marked: The item will be hidden from buyers until the product launch is created. This prevents the item from becoming available to view and purchase before the desired launch time.
  • not_marked (default): The item will not be part of a product launch.

rich_text_description

Type: string

N/A for dynamic ads. Optional for commerce.

Max characters: 9999

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.


Example:

<html>
<p>Unisex cotton T-shirt with 3/4 length sleeves in royal blue. Great for everyday casual wear. Features graphic print of logo in white on upper left sleeve.</p>
<ul>
<li>100% Cotton</li>
<li>Relaxed Fit</li>
</ul>
</html>

age_group

Type: string

Optional.

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

color

Type: string

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

Determines gender for sizing. Supported values: female, male, unisex.

material

Optional.

Primary material the item is made from. Supported values: cotton, denim, leather. Supports pixel-based catalogs.

Example: cotton

disabled_capabilities

Optional.

Used to control the channel visibility of each specific product in your catalog. With this feature, you can enable or disable your products from being displayed in Shops, Marketplace Shops, Instagram Product Tagging, Dynamic Ads, and Mini Shops.

Learn more about disabled_capabilities.

origin_country
Type: ISOCountryCode (2 letter country code)

Optional.

This field is available in feeds only. Example value: US

This field is required for Sellers selling in India.

importer_name
Type: string

Optional.

This field is available in feeds only. Example value: Facebook Inc.

This field is required for Sellers selling in India if the product is imported.

importer_address
Type: JSON structure

Optional.

This field is available in feeds only. The JSON structure contains the following fields:


street1 - string, required
street2 - string, optional
city - string, required
region - string, optional (in the US this is to be used for US State)
postal_code - string, optional (in the US this is to be used for Zip Code)
country - ISOCountrycode (2 letter country code), required


The overall importer_address field is optional (can be left blank or empty object). If specifying an actual address, then street1, city and country are required at a minimum.


The overall address will be displayed to users in the following format: street1, street2 (if present), city, region (if present) postal_code (if present), country (full name, localized for the user).


This example value: `

{ street1: "1 Hacker Way", street2: "Building 18", city: "Menlo Park", region: "CA", postal_code: "94025", country: "US" }

will be rendered as "1 Hacker Way, Building 18, Menlo Park, CA 94025 United States of America"

This field is required for Sellers selling in India if the product is imported.

Supported Feed Formats

Learn more about supported feed formats.

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

    </channel>
</rss>