Reference - Catalog

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.

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)

CSV

Update price and availability for a subset of items.

Download (Right-Click and Save Link As)

id

type: string

Required for dynamic ads and commerce.

Max character limit: 100

Unique ID for item. Can be a variant for a product. If you can, use the product's existing SKU. If there are multiple instances of the same ID, we ignore all instances. This maps to retailer_id after the product is imported. The id field must match the content ID for your pixel.

Example: FB_product_0001

description

type: string

Required for dynamic ads and commerce.

Max character limit: 5000

Short text describing item. Ensure that the description has enough information for the customer to make an informed decision to buy the product. For example, add material, sizes, other details, if needed. Don't include promotional text or any links. Use plain text (without HTML tags) for this field. Don't enter text in all capital letters. Make sure that product descriptions satisfy catalog requirements.

For commerce - To support HTML, use the rich_text_description.

Example: A vibrant crewneck for all shapes and sizes. Made from 100% cotton.

condition

type: string

Required for dynamic ads and commerce.

Item's current condition in your store: new, refurbished, used, used_fair, used_good, used_like_new. Must be written in U.S. English. You must provide one of the values in this field; it can’t be left empty. Marketplace B2C products should mostly be new.

Example: new

link

type: string

Required for dynamic ads and commerce.

URL link to merchant's site (website landing page) where you can purchase or learn more about the item. Provide a graceful fallback if you don't have a URL (example: a link to the merchant's Facebook page).

Example: https://www.fb.com/t_shirt

brand

type: string

Required for dynamic ads. For commerce, required if no manufacturer assigned gtin.

Max characters: 100

Product's brand name. You can use unique manufacturer part number (MPN), Global Trade Item Number (GTIN), or brand name for your product. You only need to use one of these values for this column (not all of them).

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

Example: Facebook

age_group

type: string

Optional for dynamic ads. N/A for commerce.

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

gender

type: string

Optional for dynamic ads. Required for commerce.

Determines gender for sizing. Supported values: Female, Male, Unisex.

google_product_category

type: string

Optional for dynamic ads. Required for commerce.

Max character limit: 250

For dynamic ads, represents predefined values (string or category ID) from Google's product taxonomy. Learn more about product categories for commerce.

For commerce, represents the category of your product according to the Google's product taxonomy. You must ensure that this value is accurate as it's being used for important business logic in the Commerce Platform, such as tax calculations and Purchase Protection.

Example: Apparel & Accessories > Clothing > Dresses or 2271

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

sale_price

type: string

Optional for dynamic ads and commerce.

Discounted price if the item is on sale. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency. Use "." as the decimal for the sale price. The sale price is required if you plan to use an overlay for discounted prices.

Example: 9.99 USD, 25.00 EUR

shipping_profile_id

type: string

Optional for commerce. N/A for dynamic ads.

Unique ID that represents shipping settings you have created in Commerce Manager Shipping Settings to associate with this product. This is a limited availability feature. Please contact your Facebook representative to get whitelisted.

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_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_4

type: string

Optional for dynamic ads. N/A for commerce.

Max character limit: 100

Additional information about the item you want to include.

inventory

type: integer

N/A for dynamic ads. Optional for commerce.

Number of inventory count of the product (quantity). Your product is not buyable unless the inventory number is positive.

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

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

launch_date

type: date

N/A for dynamic ads. Optional for commerce.

For item with preorder availability, determines when the item will become available. 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.

offer_price_effective_date

type: string as two ISO-8601 timestamps

N/A for dynamic ads. For commerce, Required for Daily Deals.

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

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

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:

og:title

Required.

Title of the item. Supports pixel-based catalogs.

og:url

Required.

Complete URL for the product page. 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:currency

Required.

Currency for the price in ISO format. Supports pixel-based catalogs.

Example: USD

product:availability

Required.

Current availability of the item: in stock, out of stock, preorder, available for order, discontinued. 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. You must ensure that this value is accurate as it's being used for important business logic in the Commerce Platform, such as tax calculations and Purchase Protection. Learn more about product categories for commerce.

product:custom_label_[0-4]

Optional.

Max character limit: 100

Additional information about the item you want to include. 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:isbn

Optional.

International Standard Book Number. ISBNs consist of 13 digits. Supports pixel-based catalogs.

material

Optional.

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

Example: cotton

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:retailer_item_id

Required.

Retailer's ID for the item. Supports pixel-based catalogs.

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

name

Title of the item.

description

Description of the item.

url

Complete URL for the product page.

price

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

availability

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

name

Title of the item.

description

Description of 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”.

availability

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