Upload Inventory

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 data feed; that is, upload your inventory:

For troublshooting tips, see Troubleshoot Your 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

Required Fields

This section defines the required fields for each catalog type. For the purpose of column naming conventions, you should provide all fields in U.S. English.

For the purpose of this guide, see the list of catalog types and their respective (required) fields:


Products - Dynamic Ads & Commerce

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

Name TypeDescriptionDynamic AdsCommerce

id

string

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


Example: FB_product_0001

Y

Y

availability

string

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

string

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.Max size: 5000

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

Y

Y

condition

string

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

Y

Y

image_link


string

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

link

string

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.facebook.com/t_shirt

Y

Y

title

string

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

Example: Blue Facebook T-Shirt (Unisex)

Y

Y

price

string

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

string

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). Required for all new products with a GTIN assigned by the manufacturer.

Example: 4011200296908

Y

Y

mpn

string

Product's unique manufacturer part number. Required if no manufacturer assigned gtin. Daily Deals inventory **must also include brand if mpn is provided.** Max characters: 100. Example: 100020003

Y

Y

brand

string

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

Example: Facebook

Y

Y

size

string

Required for variants with sizes. Size of product. Example: Small, Large. Numeric. Example: 8, 12.5, 23 string

N

Y

color

string

Required for variants with colors. Color of item. Example: Green, Mauve, Midnight Blue

N

Y

gender

string

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

N

Y

pattern

string

Required for variants with patterns. Pattern of product. Example: Flannel, Gingham, Polka dots.

N

Y

google_product_ category

string

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

N

Y

offer_price

string

Required for Daily Deals. Discounted price if the item is offered as a Daily Deal. Currency should follow the ISO 4217 standards. Specified as 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

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


Hotels

NameDescription

hotel_id

Unique ID number for the hotel. Don't use duplicate IDs. Max characters: 100 Example: FB_hotel_1234

name

Name of the hotel

image[0].url

URL link to the image of the item that will appear in your ads. Max items: 20. * For square (1:1) aspect ratios in the carousel ad format, your image should be 600x600. * For single image ads, your image should be at least 1200x630. * If you have more than one image, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of images. Example: image[0].url; image[1].url

url

URL link to the website where people can book the hotel room. Example: https://www.facebook.com/hotel

address.addr1

Hotel's street address. Example: 1 Hacker Way

address.city

City where the hotel is located. Example: Menlo Park

address.region

State, county, province, where the hotel is located. Example: California

address.postal_code

Postal or zip code desginated for the hotel location. Optional for countries without a postal code system. Example: United States

neighborhood[0]

Neighborhood where the hotel is located. If there's more than one neighborhood, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of neighborhoods. Max neighborhoods allowed: 20

Example: neighborhood[0]; neighborhood[1]

latitude

Latitude of hotel

Example: 37.4841

longitude

Longitude of hotel

Example: -122.14825

brand

Brand name of the hotel chain.

Example: Hilton

description

Description of the hotel. Max characters: 5000.

Example: Only 30 minutes away from San Francisco

Destinations

NameDescription

destination_id

Enter a unique ID for each destination.Max characters: 100 Example: FB_destination_1234

name

Name of the destination. Example: Bay Area Peninsula

address.city

Destination's city. Example: Menlo Park

address.region

Destination's state, county, province, or region. Example: California

address.country

Destination's country. Example: United States

address.postal_code

Postal or zip code for the destination. This is not required for countries without a postal code system. Example: 94025

image[0].url

  • For square (1:1) aspect ratios in the carousel ad format, your image should be 600x600.

  • For single image ads, your image should be at least 1200x630. If you have more than one image, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of images. Example: type[0], type[1])

type[0]

Type of destination. A destination can have multiple types. If you have more than one type to add, add additional columns for each type and use JSON-path syntax in each column name to indicate the number of types. Max types: 20 Example: city, beach

url

URL link to a website landing page where you can book the destination or learn more about it. Example: https://www.facebook.com/destination


Flights

NameDescription

origin_airport

Origin airport for the flight, written as an IATA code Example: SFO

destination_airport

Destination airport for the flight, written as an IATA code. Example: JFK

destination_city

Destination city for the flight, written as an IATA code. Example: SFO

origin_city

Origin city for the flight, written as an IATA code Example: SJC

address.city

Destination's city. Example: Menlo Park

image[0].url

URL link to the image of the product that will appear in your ads. Max items: 20. * For square (1:1) aspect ratios in the carousel ad format, your image should be 600x600. * For single image ads, your image should be at least 1200x630. If you have more than one image, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of images. Example: -image[0].url; image[1].url - https://www.facebook.com/image_001.jpg

description

description of the flight. Max characters: 5000. Example: Non-stop from SFO to JFK. Book your ticket now.

price

Cost and currency of the flight. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 850.00 USD

one_way_price

One-way cost and currency of the flight. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 150.00 USD

url

URL link to a website landing page where you can book the flight. Example: https://www.facebook.com/flights


Home Listings

NameDescription

home_listing_id

Unique ID for the home listing. Example: FB_home_1234

image[0].url

URL link to the image of the product that will appear in your ads. Max items: 20. * For square (1:1) aspect ratios in the carousel ad format, your image should be 600x600. * For single image ads, your image should be at least 1200x630. If you have more than one image, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of images. Example: -image[0].url; image[1].url - https://www.facebook.com/image_001.jpg

address.addr1

Street address of the listing. Example: 1 Hacker Way

address.city

City where the home is located. Example: Menlo Park

address.region

State, county, region, or province where the listing is located. Example: California.

address.country

Country where the listing is located. Example: United States

address.postal_code

Postal code (for outside of U.S. or zip code (within the U.S.) for the home listing. Example: 94025

neighborhood[0]

Neighborhood where the home listing is located. If it's located in more than one neighborhood, add additional columns for each one and use JSON-path syntax in each column name to indicate the number of neighborhoods. Max number of neighborhoods allowed: 20. Example: neighborhood[0]; neighborhood[1], Belle Haven

latitude

Latitude of the listing. Example: 37.4845

longitude

Longitude of the listing. Example: -122.14789

price

Cost and currency of the home. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 125000000.00 USD

availability

Current availability of the home listing. Supported values: for_sale, for_rent, sale_pending, recently_sold, off_market, available_soon. Example: for_sale

url

URL link to a website landing page where you can view the listing. Example: https://www.facebook.com/home_listing


Vehicles

NameDescription

vehicle_id

Unique ID for the vehicle. Max characters: 100. Example: 2017 Volvo XC90

year

Year the vehicle was made, written in "yyyy" form. Example: 2017

make

Vehicle make or brand. Example: Volvo

model

Vehicle model. Example: XC90

description

Description of the vehicle. Max characters: 5000. Example: Used 2017 Volvo XC90 in great condition, available now.

drivetrain

Vehicle's drivetrain. Supported values: 4x2, 4x4, AWD, FWD, RWD, Other. Example: FWD

image[0].url

URL link to an image of the vehicle that will appear in ads. * For square (1:1) aspect ratios in the carousel ad format, your image should be 600x600. * For single image ads, your image should be at least 1200x630. Example: https://www.facebook.com/image001.jpg

mileage.value

Current mileage on the vehicle. For used vehicles, this is mileage in kilometers (KM) or miles (MI). For new vehicles, use zero. Example: zero, 1700

mileage.unit

Mileage units. Supported values: MI, KM. Example: MI

url

URL link to a website landing page where you can view or purchase the vehicle. Example: https://www.facebook.com/vehicle

title

title of the vehicle listing. Max characters: 500. Example: Available now: 2017 Volvo XC90

price

Cost and currency of the vehicle. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 32000.00 USD

state_of_vehicle

Current state of the vehicle. Vehicles can be New, Used, or CPO (certified pre-owned). Example: New

price

Cost and currency of the home. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 125000000.00 USD

exterior_color

Exterior color of the vehicle. Example: White

address.addr1

Street address where the dealership is located. Example: Menlo Park

address.city

City where the dealership is located. Example: Menlo Park

address.region

State, county, region, or province where the dealership is located. Example: CA.

address.country

Country where the dealership is located. Example: United States

address.postal_code

Postal code (for oustide of U.S. or zip code (within the U.S.) for the home listing. Example: 94025

url

URL link to a website landing page where you can view the listing. Example: https://www.facebook.com/home_listing

latitude

Latitude of the dealership. Example: 37.4845

longitude

Longitude of the dealership. Example: -122.14789


Optional Fields

For the purpose of this guide, see the list of catalog types and their respective (optional) fields:


Products - Dynamic Ads & Commerce

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

Name Type Max Size Dynamic AdsCommerce

additional_image_link


string

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

short_description

string

More concise description of your item. Max size: 1000

Y

Y

rich_text_description

string

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

Y

Y

inventory

string

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

Y

Y

age_group

string

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

Y

N

color

string

Item color. Use a language description. Don't use alphanumeric descriptions, such as FF0000; use only one color. Max size: 200. Example: red

Y

N

expiration_date

ISO‑8601 (YYYY‑MM‑DD)

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

Y

Y

gender

string

Gender that the item is best identified with: male, female, unisex

item_group_id

string

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 - Optional, Required for variants.

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

google_product_category

string

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

Y

N

material

string

Material product is made of, such as leather, denim, cotton. Max size: 200

Y

N

pattern

string

Description of pattern or graphic print on a product. Max size: 100. Example: plaid, paisley

Y

N

product_type

string

Retailer-defined category for product. Max size: 1000.

Example in TSV: Home & Garden > Kitchen & Dining > Appliances > Refrigerators

Example in XML: <product_type>Home & Garden > Kitchen & Dining > Appliances > Refrigerators</product_type>

Y

Y

sale_price

string

Discounted price if the item is on sale. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 9.99 USD

Y

Y

sale_price_effective_date

ISO‑8601 (YYYY‑MM‑DD)

Start and end date and time for the sale, separated by slash:


2014-11-01T12:00-0300/2014-12-01T00:00-0300

Y

Y

shipping

string

Blob with different prices for each country and region. Different regions are comma-separated. The format should be COUNTRY:STATE:SHIPPING_TYPE:PRICE.

Example:

US:CA:Ground:9.99 USD, US:NY:Air:15.99 USD

Y

N

shipping_weight

string

Shipping weight of item. Acceptable units of weight: lb, oz, g, kg. Example: 3.12 lbs, 4.2 oz, 5 kg

Y

N

size

string

Size of item. Max length: 200. Example: Small or XL

Y

N

custom_label_0

string

Additional information about item. Max size: 100

Y

N

custom_label_1

string

Additional information about item. Max size: 100

Y

N

custom_label_2

string

Additional information about item. Max size: 100

Y

N

custom_label_3

string

Additional information about item. Max size: 100

Y

N

custom_label_4

string

Additional information about item. Max size: 100

Y

N

product_delivery_method

string

Two values that describe whether the product is a shipped good or digital good. Example: shipping, redemption code.

Y

N

vendor_id

string

For marketplaces that sell other people's goods; for example, Amazon, where id is the vendor for the platform.

Y

N

visibility

string

Toggle visibility on product. Options are published (default) or staging. Products that are in staging visibility are not shown to buyers, and are not available for product tagging on Instagram, nor for dynamic ads.

Y

Y

mobile_link

string

Link to mobile-optimized page for item on the merchant's website.

N

Y

sale_price

string

Discounted price if the item is on sale. Currency should follow ISO 4217 currency codes such as 9.99 USD.

Y

Y

sale_price_effective_date

date

Start and end date and time for the sale, separated by slash 2014-11-01T12:00-0300/2014-12-01T00:00-0300.

Y

Y

additional_variant_attribute

key-value pairs

Additional attributes that are not core attributes (size, color, gender, pattern, and so on). Do not use a core attribute as an additional attribute. Example: Scent:Fruity,Flavor:Apple.

Y

Y

return_policy_info

string

Product return policy info. For "final sale" status, use string {is_final_sale: "true", return_policy_days: "0"}. Products that are "final sale" are not eligible for returns. This is a limited availability feature. Please contact your Facebook representative to get whitelisted. Example: {is_final_sale: "false", return_policy_days: "30"}

Y

Y

availability_date

date

For item with preorder availability, determines when the item is available. Date should follow the ISO‑8601 (YYYY‑MM‑DD) format.

Y

Y


Hotels

To add optional hotel room and pricing information to your catalog, add the following columns to your feed:

NameDescription

room_id

Enter a unique ID for the hotel room type. Max characters: 100 Example: FB_hotel_room_1234

name

Name of the room type. Example: King Bed Suite

description

Brief description of the room type. Example: King Bed Suite with a view of the bay. Sleeps 2 guests.

base_price

Lowest base price of the hotel room per night. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 199.00 EUR

price

Total cost and currecy of the hotel stay, based on checkin_date and length_of_stay. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 1393.00 USD

sale_price

Discounted sale cost and currecy of the hotel stay, based on checkin_date and length_of_stay. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 300.00 USD

checkin_date

Check-in date for the stay. You can add up to 180 days from the date you upload your feed. Format as YYYY‑MM‑DD. Example: 8/1/2017

length_of_stay

Number of nights of the stay in the hotel. Max number of days allowed: 14. Example: 7

tax

Applicable tax rate for the price. Example: 14

fees

Applicable fees for the price. Example: 253.00 USD

loyalty_program

Written in text.

margin_level

Number between 0 and 10 that indicates the hotel's profitability.

phone

Phone number of the hotel.

star_rating

Official star rating for hotel, between 0 and 5, numerically written. Round number or multiples of 0.5.

custom_label_0

Additional information about item. Max size: 100


Destinations

NameDescription

description

Description of the destination. Max characters: 5000 Example: This destination is a perfect family getaway for those looking for an adventure.

price

Total cost and currecy of the destination, based on hotel price checkin_date and length_of_stay. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 1393.00 USD

price_change

Change in cost (in percentage) for the average price of a hotel in a destination, primarily used for bidding purposes. Negatives indicate a price drop, written numerically and indicates a percentage. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Minimum -100 and maximum 100 Example: 1393.00 USD

custom_field(0)

Fields that you can customize. Allowed up to 3 custom fields (0-2).


Flights

NameDescription

destination_city

Destination city for the flight, written as an IATA code. Example: SFO

origin_city

Origin city for the flight, written as an IATA code Example: SJC

price

Cost and currency of the flight. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 850.00 USD

one_way_price

One-way cost and currency of the flight. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: 150.00 USD


Home Listings

NameDescription

home_listing_group_id

Home listings that are variants of an item. Max characters: 5000

num_bed

Number of beds for home listing. Values must be multiples of 0.5 and non-negative.

num_bath

Number of baths for home listing. Values must be multiples of 0.5 and non-negative.

property_type

Property type of home listing. Values include: apartment, builder_floor, condo, condo_room, house, house_in_condominium, house_in_villa, house_in_villa, house_room, land, loft, manufactured, other, other_room, penthouse, single_family_home, studio, townhouse, townhouse_room.


Vehicles

NameDescription

vin

Vehicle identification number. Max characters: 17. Example: 1FADP5AU6DL536022

vehicle_registration_ plate

Metal or plastic plate attached to a motor vehicle or trailer for official identification purposes. All countries require registration plates for road vehicles, such as cars, trucks, and motorcycles. Whether they are required for other vehicles, such as bicycles, boats, or tractors, may vary by jurisdiction. The registration identifier is a numeric or alphanumeric ID that uniquely identifies the vehicle owner within the issuing region's vehicle register. In some countries, the identifier is unique within the entire country, while in others it is unique within a state or province. Max characters: 64

transmission

Machine in a power transmission system, which provides controlled application of the power of a vehicle. Values include: Automatic, Manual, Other

previous_price

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

dealer_email

Dealer or dealerships' email address.

fuel_type

Fuel type designated for the vehicle. Values include plugin, hybrid.


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.

Name Description Example

android_app_name

Name of app for display

Electronic Android

android_package

Fully-qualified package name for intent generation

com.electronic

android_url

Custom scheme for Android app as URL

android://electronic

ios_app_name

Name of app to display

Electronic iOS

ios_app_store_id

App ID for App Store

1234

ios_url

Custom scheme for iOS app as URL

ios://electronic

ipad_app_name

Name of app to display

Electronic iPad

ipad_app_store_id

App ID for App Store

9010

ipad_url

Custom scheme for iPhone app

ipad://electronic

iphone_url

Custom scheme for iPhone app as URL

iphone://electronic

iphone_app_store_id

App ID for App Store

5678

iphone_app_name

Name of app to display

Electronic iPhone

windows_phone_app_id

App ID, as a GUID, for app store

ee728e01-7727-4168-9c8f-85c7eef40112

windows_phone_app_name

Name of app for display

Electronic Windows

windows_phone_url

Custom scheme for Windows Phone app as URL

windows://electronic

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.


Set Microdata Tags in Catalog {#microdata-tags} (Optional)

Note: You can only create eCommerce catalogs with the Facebook pixel. To create another type of catalog, upload a data feed instead.

There are two protocols that you can use to add the microdata: OpenGraph or Schema.org. Depending on the type of protocol you choose, the microdata needs to be in the right location on your website:

  • OpenGraph: Place the microdata in the header of your website.
  • Schema.org: Place the microdata across the product page where the products are located.
  • JSON-LD for Schema.org: Place the microdata within the script tag (see the example below).

OpenGraph – Required Tags

NameDescription

og:title

Title of the item.

og:description

Description of the item.

og:url

Complete URL for the product page.

og:image

Link to the image used on the product page.

product:brand

Brand name of the item.

product:availability

Current availability of the item: in stock, out of stock, preorder, available for order, discontinued.

product:condition

Current condition of the item: new, refurbished, used.

product:price:amount

Current price of the item. Don't include symbols, such as “$” in the price.

product:price:currency

Currency for the price in ISO format (for example, USD).

product:retailer_item_id

Retailer's ID for the item.

Example - OpenGraph

curl \

<header>

...

<!-- Open Graph Metadata -->

 <meta property="og:title" content="Facebook T-Shirt">

 <meta property="og:description" content="Unisex Facebook T-shirt, Small">

 <meta property="og:url" content="https://example.org/facebook">

 <meta property="og:image" content="https://example.org/facebook.jpg">

 <meta property="product:brand" content="Facebook">

 <meta property="product:availability" content="in stock">

 <meta property="product:condition" content="new">

 <meta property="product:price:amount" content="9.99">

 <meta property="product:price:currency" content="USD">

 <meta property="product:retailer_item_id" content="facebook_tshirt_001">

<!-- End Open Graph Metadata -->

...

</header>

Schema.org – Required Tags

NameDescription

name

Title of the item.

brand

Brand of the item.

description

Description of the item.

productID

Retailer's ID for 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”.

priceCurrency

Currency for the price, in ISO format (for example, USD). 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”.

condition

Current condition of the item: new, refurbished, or used. Include this entry under “offers”.

Example - Schema.org

curl \
    <div itemscope itemtype="http://schema.org/Store">
<div id="..." class="..." itemscope="" itemtype="http://schema.org/Product">
...
<meta itemprop="brand" content="facebook">
<meta itemprop="name" content="Facebook T-Shirt">
<meta itemprop="description" content="Unisex Facebook T-shirt, Small">
<meta itemprop="productID" content="facebook_tshirt_001">
<meta itemprop="url" content="https://example.org/facebook">
<meta itemprop="image" content="https://example.org/facebook.jpg">
...
<span itemprop="offers" itemscope itemtype="http://schema.org/Offer" itemref="schema-offer">
<link itemprop="availability" href="http://schema.org/InStock">
<link itemprop="itemCondition" href="http://schema.org/NewCondition">
<div class="..." itemprop="price"&gt;7.99&lt;/div>
<meta itemprop="priceCurrency" content="USD">
...
        </span>
        ...
       </div><div itemscope itemtype="">

JSON-LD for Schema.org

Extracted from schema.org/Product

NameDescription

name

Title of the item.

brand

Brand of the item.

description

Description of the item.

productID

Retailer's ID for the item.

url

Complete URL for the product page.

offers

Vector of objects of type schema.org/Offer.

image

Link to the image used on the product page.

**Extracted from

schema.org/Offer

(as a part of product offers)**

NameDescription

price

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

priceCurrency

Currency for the price, in ISO format (for example, USD). 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”.

condition

Current condition of the item: new, refurbished, or used. Include this entry under “offers”.

Example — schema.org/Offer

curl \
<script type="application/ld+json">

       {
  
        "@context":"https://schema.org",
        "@type":"Product",
        "productID":"facebook_tshirt_001",
        "name":"Facebook T-Shirt",
        "description":"Unisex Facebook T-shirt, Small",
        "url":"https://example.org/facebook",
        "image": "https://example.org/facebook.jpg",
        "brand":"facebook",
        "offers":[
        {
        "@type":"Offer",
        "price":"7.99",
        "priceCurrency":"USD",
        "itemCondition":"https://schema.org/NewCondition",
        "availability":"https://schema.org/InStock"
        }
        ]
        <script>

After you add the required microdata to your website, learn more about

using Catalog Manager to create a catalog with your Facebook pixel

.


Set Metadata Tags in Item Feed File (Optional)

You can optionally set metadata tags in your product feed files. This enables Facebook to attribute catalogs using this feed to your app. Once a catalog is attributed to your app, the meta tag is not required in subsequent feed uploads to that catalog.

Include the following two elements as space delimited comments at the top of TSV/CSV feeds or inside a metadata tag in your XML feeds:

  • ref_application_id - Your Facebook app ID
  • ref_asset_id - ID that uniquely identifies this feed in your system

Feed Formats


Feed Format Description

CSV

Sample CSV Feed file with reference information inside the metadata tag.

Download (Right-Click and Save Link As)

TSV

Sample TSV Feed file with reference information inside the metadata tag.

Download (Right-Click and Save Link As)

RSS XML

Sample RSS XML Feed file with reference information inside the metadata tag.

Download (Right-Click and Save Link As)

ATOM XML

Sample Atom XML Feed file with reference information inside the metadata tag.

Download (Right-Click and Save Link As)

Example - TSV feed format

# ref_application_id <YOUR_APP_ID>
# ref_asset_id <YOUR_ASSET_ID>
id  title  ios_url  ios_app_store_id  ios_app_name  android_url  android_package  android_app_name  windows_phone_url  windows_phone_app_id  windows_phone_app_name  description  google_product_category  product_type  link  image_link  condition  availability  price  sale_price  sale_price_effective_date  gtin  brand  mpn  item_group_id  gender  age_group  color  size  shipping  custom_label_0
DB_1  Dog Bowl In Blue  example-ios://electronic/db_1  123  Electronic Example iOS  example-android://electronic/db_1  com.electronic.example  Electronic Example Android  example-windows://electronic/db_1  64ec0d1b-5b3b-4c77-a86b-5e12d465edc0  Electronic Example Windows  Solid plastic Dog Bowl in marine blue color  Animals > Pet Supplies  Bowls & Dining > Food & Water Bowls  http://www.example.com/bowls/db-1.html  https://www.facebook.com/images/product_image_template.png?id=1  new  in stock  9.99 GBP        Example    DB_GROUP_1          UK::Standard:9.95 GBP  "Made in Waterford, IE"
...

Example - XML feed format

...
<?xml version="1.0"?>
<rss xmlns:g="http://base.google.com/ns/1.0" version="2.0">
  ...
  <metadata>
    <ref_application_id><YOUR_APP_ID></ref_application_id>
    <ref_asset_id><YOUR_ASSET_ID></ref_asset_id>
  </metadata>
  ...
</rss>
...

Set Up Country and Language Feeds via the API {#country-lang-feeds} (Optional)

Once you have created the country and language feeds, and made them available on your server, you will need to link them to your catalog following the same API calls presented in our documentation, with the override_type parameter.

For a full list of fields available to override in the country and language feeds, as well as supported language and country codes, see our guide on how to create your language and country feeds.

Example - Uploading the Language Feed

curl \
  -F 'name=Language feed' \
  -F 'schedule={ 
    "interval": "DAILY", 
    "url": "http:\/\/www.example.com\/sample_language_feed.tsv",
    "hour": 22
  }' \
  -F 'override_type=language'
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<YOUR_PRODUCT_CATALOG_ID>/product_feeds

Example - Uploading the Country Feed

curl \
  -F 'name=Country Feed' \
  -F 'schedule={ 
    "interval": "DAILY", 
    "url": "http:\/\/www.example.com\/sample_country_feed.tsv",
    "hour": 22
  }' \
  -F 'override_type=country'
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<YOUR_PRODUCT_CATALOG_ID>/product_feeds

Parameters


Parameter Value

url

Location where we can retrieve the feed file from

interval

Frequency at which we fetch from the feed file

hour

Hour of the day (based on a 24-hr clock) when we fetch the feed

For more options about scheduling fetches, see Set Up Feed, Schedule.


Test Your Feed

Test your feed through our feed debug page.

  • For CSV / TSV, copy the first row (column header row) and a few products.
  • For XML, copy the XML with a few item/entry, paste the lines into the text area and validate.

Upload Your Feed

To upload a feed, you need ads_management permission. See Marketing API, Permissions. After you create a catalog, use catalog id to create and schedule a Product Feed:

curl -X POST \ -F 'name="Test Feed"' \ -F 'schedule={ "interval": "DAILY", "url": "http://www.example.com/sample_feed.tsv", "hour": "22" }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.3/{product-catalog-id}/product_feeds
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const ProductCatalog = bizSdk.ProductCatalog; const ProductFeed = bizSdk.ProductFeed; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'Test Feed', 'schedule' : {'interval':'DAILY','url':'http://www.example.com/sample_feed.tsv','hour':'22'}, }; const product_feeds = (new ProductCatalog(id)).createProductFeed( fields, params ); logApiCallResult('product_feeds api call complete.', product_feeds);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\ProductCatalog; use FacebookAds\Object\ProductFeed; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'Test Feed', 'schedule' => array('interval' => 'DAILY','url' => 'http://www.example.com/sample_feed.tsv','hour' => '22'), ); echo json_encode((new ProductCatalog($id))->createProductFeed( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.productcatalog import ProductCatalog from facebook_business.adobjects.productfeed import ProductFeed from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'Test Feed', 'schedule': {'interval':'DAILY','url':'http://www.example.com/sample_feed.tsv','hour':'22'}, } print ProductCatalog(id).create_product_feed( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new ProductCatalog(id, context).createProductFeed() .setName(\"Test Feed\") .setSchedule(\"{\\"interval\\":\\"DAILY\\",\\"url\\":\\"http://www.example.com/sample_feed.tsv\\",\\"hour\\":\\"22\\"}\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end product_catalog = FacebookAds::ProductCatalog.get(id) product_feeds = product_catalog.product_feeds.create({ name: 'Test Feed', schedule: {'interval':'DAILY','url':'http://www.example.com/sample_feed.tsv','hour':'22'}, })

The schedule parameter enables you to schedule your feed upload. Options include interval, url, hour. It can also include day_of_week, minute, username, and password. For example:

schedule: {"day_of_week":"FRIDAY","hour":17,"interval_count":1,"interval":"DAILY","minute":42,"next_scheduled_upload_time":"","password":pwd123,"status":"active","timezone":"Atlantic/Canary","url":"https://www.abc.com","username":aname}

Learn how to read the Product Feed Upload Error Report.