Set Up Your Catalog Feed

A feed is a set of items uploaded or fetched from a business so that your catalog is current. A item is a single item in your online store, such as a SKU. You can have a single product feed represent all items in your catalog, or multiple feeds with each feed represents a single country or division's items.

Each line in your feed contains all the information needed to create a dynamic ad. Data feed files are dynamic uploads of your data to keep your catalog up to date.

We recommend following these steps and guidelines to set up your catalog feed:

Learn More


Supported Feed Formats

Provide your feed in one of these formats:

Feed Format Description & Guidelines Sample Feed

CSV

Comma-separated value.

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

Download > Right-click > Save Link As

TSV

Tab-separated value. See guidelines for CSV.

Download > Right-click > Save Link As

RSS XML

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.

Download > Right-click > Save Link As

ATOM XML

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

Download > Right-click > Save Link As

Supported Fields by Catalog Type

This section defines the required and optional fields for each catalog type:

For the purpose of column naming conventions, you should provide all fields in U.S. English.


Products - Dynamic Ads & Commerce

You should upload your inventory to Facebook using a catalog. For each catalog type, a product feed should be provided in one of the supported formats (CSV, TSV, RSS XML, ATOM XML). See Supported Feed Formats.

The following table defines the fields used to create a dynamic ads or commerce catalog, including the requirement level (required vs. optional). For more information about the commerce platform, see Inventory Management.

Name DescriptionDynamic AdsCommerce

id

type: string

Required.

Max characters: 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.


Example: FB_product_0001

Y

Y

item_group_id type: string

Optional, but required for variants (commerce).


For dynamic ads - Items that are variants of a product. With dynamic ads, we pick only one item out of the group based on the signal we received from the pixel or app.

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. We map this to retailer_product_group_id once we get your feed.

Y

Y

short_description

type: string

Optional.

Max size: 1000

More concise description of your item.

Y

Y

rich_text _description

type: string

Optional.

Max characters: 5000.

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.

Y

Y

inventory

type: string

Optional.

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

Y

Y

availability

type: string

Required.

Item's current availability. If item in stock, use one of these accepted values:

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

Example: in stock

Y

Y

description

type: string

Required.

Max size: 5000

Short text describing item. 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. Use line breaks or italics to format your description.

For commerce - To support HTML, use rich_text_description.

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

Y

Y

condition

type: string

Required.

Item's current condition: new, refurbished, used. Marketplace B2C products should mostly be new. Example: new

Y

Y

image_link

type: string

Required.

URL link to item image used in the ad. Provide proper image sizes.


For square (1:1) aspect ratios in the carousel ad format - Image should be 600x600. For single-image, dynamic ads - The minimum image resolution requirement is 1200x630. The minimum aspect ratio requirement is 4:5 and the maximum aspect ratio requirement is 1:91:1. If the image is outside this aspect ratio, Facebook crops it to be closest to either the minimum aspect ratio or the maximum aspect ratio, depending on its original aspect ratio.


For carousel image, dynamic ads - The minimum image resolution requirement is 500px * 500px, and Facebook crops it to a 1:1 aspect ratio.

Example: https://www.fb.com/t_shirt_1.jpg

Y

Y

additional_image_link

type: string

Optional.

For dynamic ads, you can include up to 20 additional images. For commerce, you can include up to 10 additional images. For both, provide the images as comma-separated URLs.

Y

Y

link

type: string

Required.

URL link to merchant's site (website landing page) where you can purchase the product 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

Y

Y

title

type: string

Required.

Max size: 150

Title that's relevant and specific to each item. Include keywords and variants, such as brand names, item areas, attributes, or condition.

Example: Blue Facebook T-Shirt (Unisex)

Y

Y

price

type: string

Required.

Cost and currency of item. Format price as the cost, followed by the ISO currency code, with a space between cost and currency.

Example: 9.99 USD, 25.00 EUR

Y

Y

gtin

type: string

Required 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 buide. Supported values are UPC (North America, 12 digits), EAN (Europe, 13 digits), JAN (Japan, 8 or 13 digits), ISBN (books, 13 digits).

Example: 4011200296908

Y

Y

mpn

type: string

Required if no manufacturer assigned gtin.

Max characters: 100.

Product's unique manufacturer part number. Daily Deals inventory must also include brand if mpn is provided.

Example: 100020003

Y

Y

brand

type: string

Required if no manufacturer assigned gtin.

Max characters: 100

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

Example: Facebook

Y

Y

size

type: string

Required for variants with sizes.

Size of product. Example: Small, Large Numeric. Example: 8, 12.5, 23 string

N

Y

color

type: string

Optional, but Required for variants with colors.

Max size: 200.

Color of item. Use a language description. Don't use alphanumeric descriptions, such as FF0000; use only one color.
Example: Green, Mauve, Midnight Blue

N

Y

expiration_date

type: ISO‑8601

Optional

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

Y

Y

age_group

type: string

Optional

Age group for product. Accepted values are newborn, infant, toddler, kids, adult, ages, teen.

Y

N

gender

type: string

Optional

Determine gender for sizing. Values include Female, Male, Unisex. Example: Female

N

Y

pattern

type: string

Required for variants with patterns.

Pattern of product. Example: Flannel, Gingham, Polka dots.

N

Y

google_product_ category

type: string

Optional (ads), Required (commerce)

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

N

Y

offer_price

type: string

Required for Daily Deals

Discounted price if the item is offered as a Daily Deal. Currency should follow the ISO 4217 standards. Example: 9.99 USD. The offer_price field value must be lower than the price field value by at least 15%.

N

Y

offer_price_ effective_date

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

N

Y


Provide deep links in feed following the App Links specification. Deep link information in feed takes precedence over any information Facebook collects with App Links metadata with our web crawler.

If you already have deep link information from App Links, you do not need to specify this data. Facebook uses information from App Links to display the correct deep link. To display deep links in your ads see Dynamic Ads, Ad Template.

NameDescriptionExampleRequirement Level

android_app_name

Name of app for display

Electronic Android

Optional

android_package

Fully-qualified package name for intent generation

com.electronic

Optional

android_url

Custom scheme for Android app as URL

android://electronic

Optional

ios_app_name

Name of app to display

Electronic iOS

Optional

ios_app_store_id

App ID for App Store

1234

Optional

ios_url

Custom scheme for iOS app as URL

ios://electronic

Optional

ipad_app_name

Name of app to display

Electronic iPad

Optional

ipad_app_store_id

App ID for App Store

9010

Optional

ipad_url

Custom scheme for iPhone app

ipad://electronic

Optional

iphone_url

Custom scheme for iPhone app as URL

iphone://electronic

Optional

iphone_app_store_id

App ID for App Store

5678

Optional

iphone_app_name

Name of app to display

Electronic iPhone

Optional

windows_phone_app_id

App ID, as a GUID, for app store

ee728e01-7727-4168-9c8f-85c7eef40112

Optional

windows_phone_app_name

Name of app for display

Electronic Windows

Optional

windows_phone_url

Custom scheme for Windows Phone app as URL

windows://electronic

Optional

For iOS, only provide iPhone or iPad app information if they are different from the general iOS app.

Use product group to group all product variants. Provide product group to identify products that are almost identical but have variations such as color, material, size or pattern. Groups make it easier to advertise additional colors, styles, or patterns for a particular product. All products in a product group share the same item_group_id. In dynamic ads, we pick only one item out of the group based on the signal we received from the pixel or app.