Inventory Management

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

In this section:

Uploading Inventory

Set Up your product catalog during merchant onboarding, and upload or configure your products using the Product Feed API.

The product feed will be used as the source of truth for updating product catalogs on Facebook, and fetched by Facebook periodically according to the configured interval. You should store the product feed ID, and use it to get upload status, errors and to change upload schedule.

Note: Catalogs do not currently support using the Batch API for CREATEs at this time. To create inventory, use the Feed API.

POST https://graph.facebook.com/vX.X/{product-catalog-id}/product_feeds
Token: PAGE_ACCESS_TOKEN

Request

AttributeTypeRequiredDescription

name

string

Required

schedule

schedule

Required

schedule object

Read the Product Feed Schedule specification for more details.

AttributeTypeRequiredDescription

url

string

Required

interval

string

Required

hour

number

Optional

Response

{
  "id": 215042069082048
}

Product Feed Data Model

Each item in the product feed supports the following attributes.

AttributeTypeRequiredDescription

id

string

Required

Unique ID for item. Can be a variant for a product. If there are multiple instances of the same ID, we ignore all instances. This maps to retailer_id after the product is imported.

gtin

string

See notes

Global Trade Item Number (GTINs); can include UPC, EAN, JAN, and ISBN. Required for all new products with a GTIN assigned by manufacturer.

mpn

string

See notes

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

brand

string

See notes

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

title

string

Required

Title of item.

description

string

Required

Short text describing product. Use plain text (without HTML tags) for this field. If you want to support HTML, please use rich_text_description field.

rich_text_description

string

Optional

Optional rich text (HTML) description for product. Supported tags include: <b>, <i>, <em>, <strong>, <header> as well as all Header tags (<h1> thru <h6>), as well as <br>, <p>, <ul>, and <li>. If this field is provided, we will use it instead of description.

link

string

Required

Link to item on the merchant's website. Provide a graceful fallback if you do not have a product URL (e.g. link to the merchant's Facebook page).

mobile_link

string

Optional

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

image_link

string

Required

URL of product image.

additional_image_link

string

Optional

You can include up to 10 additional images; provide them as comma-separated URLs.

size

string

Required for variants with sizes

Size of product e.g. Small, Large, or numeric, e.g. 8, 12.5, 23

color

string

Required for variants with colors

Color of product e.g. Green, Mauve, Midnight Blue, etc

gender

string

Required

Female

Male

Unisex

pattern

string

Required for variants with patterns

Pattern of product e.g. Flannel, Gingham, Polka dots, etc

inventory

integer

Optional, see note

Number of inventory count of the product (quantity). Note that your product will not be buyable unless inventory number is positive.

visibility

string

Optional

Toggle visibility on product. Options are published or staging (default is published). Products that are in staging visibility will not be shown to buyers, will not be available for product tagging on Instagram, and are not available for Dynamic Ads.

availability

string

Required

Whether item is in stock; Accepted values are:

  • 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

condition

string

Required

Product condition: new, refurbished, or used. Marketplace B2C products should mostly be new.

price

string

Required

Cost of item and currency. Currency should follow ISO 4217 currency codes such as 9.99 USD

return_policy_info

string

Optional

Product return policy info. Ex: {is_final_sale: "false", return_policy_days: "50"} . For "final sale" status, use string {is_final_sale: "true", return_policy_days: "0"} . Products that are "final sale" are not eligible for returns.

Note: This is a limited availability feature. Please contact your FB representative to get whitelisted.

availability_date

date

Optional

For item with preorder availability, when the item will become available. This date should follow the ISO‑8601 (YYYY‑MM‑DD) format.

expiration_date

date

Optional

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.

sale_price

string

Optional

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

sale_price_effective_date

date

Optional

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

google_product_category

string

Required

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

product_type

string

Optional

Retailer-defined category for product, e.g. Home & Garden > Kitchen & Dining > Appliances > Refrigerators

item_group_id

string

Optional, Required for variants

For items that are variants of a product. Provide the same item_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

additional_variant_attribute

key-value pairs

Optional

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

offer_price

string

Required for Daily Deals

Discounted price if the item is offered as a Daily Deal. Currency should be specified as the ISO 4217 currency code. Specified as 9.99 USD. The "offer_price" field value must be lower than the "price" field value by at least 15%

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

Example CSV Feed

id,title,description,availability,condition,price,link,image_link,brand,additional_image_link,age_group,color,gender,item_group_id,google_product_category,pattern,product_type,sale_price,sale_price_effective_date,size,offer_price,offer_price_effective_date
FB_product_1234,Facebook T-Shirt (Unisex),A vibrant crewneck for all shapes and sizes. Made from 100% cotton.,in stock,new,9.99 USD,https://www.facebook.com/facebook_t_shirt,https://www.facebook.com/t_shirt_image_001.jpg,Facebook,https://www.facebook.com/t_shirt_image_002.jpg,adult,blue,unisex,FB1234_shirts,Apparel & Accessories > Clothing > Shirts,stripes1,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

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>

Handling Product Feed Upload Errors

Read the Product Feed Upload Errors documentation.

Request

To get errors and warning from a feed upload, you must first query for recent upload sessions.

GET https://graph.facebook.com/vX.X/{product-feed-id}/uploads
Token: PAGE_ACCESS_TOKEN

Then, use upload_session_id to retrieve errors and warnings.

GET https://graph.facebook.com/vX.X/{upload-session-id}/errors
Token: PAGE_ACCESS_TOKEN

Sample Response

A fatal severity here means the item cannot be ingested by Facebook; a warning severity means some recommended attributes are missing or malformed.

{
  "data": [
    {
      "id": 1510567479166488,
      "summary": "A required field is missing: price.",
      "description": "Products need to have prices to run in ads. Include a price for each product in your data feed file and upload it again. Prices must include cost and an ISO currency code (for example: 10 USD instead of $10 for American dollars).",
      "severity": "fatal",
      "samples": {
        "data": [
          {
            "row_number": 2,
            "retailer_id": "yj9bpbpub5t8t22kgbq6",
            "id": "1677559492523068"
          },
          {
            "row_number": 5,
            "retailer_id": "ujn33tvbyv2vmdpo7ecb",
            "id": "1529743440653137"
          }
        ]
      }
    },
    {
      "id": 275241589314958,
      "summary": "GTIN is incorrectly formatted",
      "description": "Check that the GTIN (Global Trade Identification Number) for each of your products is in the correct format. Accepted types include UPC, EAN, JAN, and ISBN.",
      "severity": "warning",
      "samples": {
        "data": [
          {
            "row_number": 4,
            "retailer_id": "bxwb1pho9o43uxjxikcg",
            "id": "538700559625644"
          }
        ]
      }
    }
  ]
}

Updating Inventory in Real-time

Note: Catalogs do not currently support using the Batch API for CREATEs at this time. To create inventory, use the Feed API.

Note: System user (owner of the token) must be admin of the catalog that you will be changing by API.

Read the Catalog Batch API documentation.

To update products more frequently than the periodic fetches supported by the Product Feed API, the Catalog Batch API may be used to perform real-time updates to individual products using retailer IDs. Any updates made through the Catalog Batch API should also be reflected in the product feed so that the updates are preserved after it is next fetched.

The Catalog Batch API supports updates to both availability and inventory parameters.

The Batch API does not provide errors information that's as rich as Feed API, so you should use the errors from feed upload as source of truth.

The availability parameter is used in conjunction with inventory numbers. Items with availability of Out of Stock will not be purchasable even if inventory numbers are greater than zero. Items with availability of In Stock will not be purchasable if inventory is zero.

It is highly recommended not to remove Out of Stock items from your feed until a reasonable time has passed, since removing it will break deep links to the product from other sources.