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 Commerce 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 content ID for item. 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

description

type: string

Required for dynamic ads and commerce.

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.

For commerce - To support HTML, use the rich_text_description.

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

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

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-letter ISO currency code (ISO 4217 standards), with a space between cost and currency. Use a period (".") as the decimal point, not a comma (",").

Example: 9.99 USD, 25.00 EUR

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

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']}

age_group

Type: string

Optional for dynamic ads and commerce.

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

gender

Type: string

Optional for dynamic ads and commerce.

The gender of a person that the item is targeted towards. Supported values: female, male, unisex.

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

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

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

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

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

return_policy_info

Type: string

N/A for dynamic ads. Optional for commerce.

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"}

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.

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:

origin_country
Type: ISOCountryCode (2 letter country code)

Optional.

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

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"

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, 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. Learn more about product categories for commerce.

Learn more about Google Product Category for Catalog Items, Ads Help Center.

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.

Currency of the discounted price if the item is on sale in3-digit ISO currency code. Supports pixel-based catalogs.

Example: USD

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

availability

Current availability of the item: in stock, out of stock, 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, available for order, discontinued. Include this entry under “offers”.