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.

To learn more about additional field requirements and recommendations for your catalog, see also:

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 the customer is using onsite checkout, there are more required attribute fields; for example, inventory and shipping. 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: 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. 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.

  • preorder - Limited availability feature. Please contact your Facebook representative to get access.

  • out of stock - Not available in current stock.

  • discontinued - Discontinued.

Example: in stock

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:

  • For Instagram Shopping: Images display in square (1:1) format. Minimum image resolution is 500 x 500 px. We recommend 1024 x 1024 px for best quality.
  • For carousel ads: Images display in square (1:1) format. Minimum image resolution 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 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

inventory

Type: integer

Required for Instagram Shopping with checkout, Page Shops, and Marketplace. Optional for Instagram Shopping with product tagging only.

Quantity of an 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

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

shipping

Type: string

Optional, but Required for checkout.

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, but Required for checkout.

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

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

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