Inventory

Use this guide to upload and manage your catalog inventory.

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/v5.0/{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.

Example — Schedule Your Feed Upload

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}

Update an Individual Item

Update an individual item's data in real time. Include the updated fields in an HTTP POST, where retailer_id is the item ID from your feed. It must be base64url-encoded.

https://graph.facebook.com/catalog:{CATALOG_ID}:{base64urlencode(retailer_id)}

See mutable fields in Products, Reference.

Do not provide item feeds with individual item updates, creation, or deletion with the API. This can disrupt any updates or deletes of items you created with the API because we don't track these with the feed.

Update Inventory in Real-time

Universal Checkout Catalogs don't currently support using the Batch API for CREATE functions at this time. To create inventory, use the Feed API.

The system user (owner of the token) must be the admin of the catalog that you will change via the API.

To update products more frequently than the periodic fetches supported by Product Catalog, the Catalog Batch API can 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.
  • Does not provide error information in as much detail as the Feed API. Use Feed Upload errors as the 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 them will break deep links to the product from other sources.

Update Inventory in Commerce Catalogs

The inventory field in your product catalog represents the stock level for each product available to sell on your Facebook Shop or Instagram Shopping account. This value is reflected in the Product Details Page (PDP) and helps buyers understand how many items are available. Keeping it accurate and up-to-date is instrumental to the experience, as it dictates when your products are out-of-stock or can lead to overselling if incorrect.

The product feed is 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.

Commerce catalogs don't currently support using the Batch API for CREATE functions at this time. To create inventory programatically, use the supported fields.

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

Request


AttributeTypeRequired

name

string

Required

schedule

schedule

Required

schedule object

Read the Product Feed Schedule specification for more details.

AttributeTypeRequired

url

string

Required

interval

string

Required

hour

number

Optional

Scheduled feeds do not support uploads more frequently than once per hour. If you need to update inventory faster, use the Catalog Batch API.

Response

{
  "id": 215042069082048
}

Inventory Management

This section describes important concepts associated with inventory management, including strategies to minimize over-selling.

Inventory Fluctuation

The inventory field is dynamic, which means that its value fluctuates as people buy products from your Facebook Shop or Instagram Shopping account. When a user places an order, the inventory level of the corresponding products is decremented.

The Commerce Platform automatically increment this value or restocks the product in case of user-initiated cancellations.

In the case of seller-initiated cancellations, you can restock a product at cancellation time and increment the corresponding inventory level, by setting the restock_items field of the cancellations API endpoint.

The value that you provide via your product catalog uploads or other techniques is considered the source of truth, and is always used to overwrite the value cached on our backend. Learn more about Inventory Update Strategies.

Out-Of-Stock Products

As people purchase products on your Facebook Shop or Instagram Shopping account, the inventory value is decremented. When this value reaches 0, we mark the product as "Out-Of-Stock" and restrict anyone from purchasing additional units. You should do a best-effort attempt at restocking your products regularly; "Out-Of-Stock" products negatively affect the user experience and your brand perception.

If a buyer finds an Out-Of-Stock product, we try our best to switch the product details page to a variant that has units In-Stock based on the inventory value of the product's variant in your product catalog.

Discontinued Products

Highly recommended — When a product is discontinued, don't delete it from your product catalog.

Deleting products from your catalog can cause undesirable effects, such as Instagram product tags disappearing or broken links. We strongly recommend that you only delete products after a significant time has passed (months). Instead of deleting products, you should set the visibility field of a discontinued product to staging. This ensures that the Commerce Platform can link your product back to a known entity and manage different situations gracefully.

Over-selling

To scale the Commerce Platform to thousands of merchants, we've made a conscious decision to not support synchronous inventory management. As a result, we don't support making atomic purchase transactions coupled with decrementing stock levels in your warehouse. If your inventory is shared across multiple channels, you may invariably over-sell products on Facebook or Instagram. This could happen for fast-selling products available in limited quantity.

When you can't fulfill orders due to over-selling situations, you should initiate a cancellation and set the reason_code to OUT_OF_STOCK.

An effective way to mitigate against over-selling is to track products being purchased on the Commerce Platform in an accurate and timely manner. Assuming that you're already tracking fulfilled orders (IN_PROGRESS or later stage), the real stock value for a given product can be calculated. Once this value is determined, you can override the inventory value in your product catalog accordingly.

A: Products available to sell
I: Inventory level in your warehouse
P: Quantity of products attached to orders in FB_PROCESSING state
C: Quantity of products attached to orders in CREATED state which you did not sync with your warehouse inventory

If you are frequently faced with overselling, you can fetch orders at a more frequent basis to identify the number of orders pending on the Commerce Platform, and adjust the inventory level of your products accordingly.

Inventory Update Strategies

Because of the asynchronous nature of distributed systems, the inventory value in your product catalog may go out-of-sync, regardless how fast you update your inventory levels. Here are some techniques that you may want to consider, to minimize race-conditions:

Pre-allocated Inventory

The most effective way to avoid over-selling is to pre-allocate inventory to your Facebook Shop or Instagram Shopping channels. Dedicating inventory for each of your sales channel guarantees that sales happening on any individual channel will not interfere with each other. This strategy can be applied to part or the totality of your product catalog.

Slow-Selling Products

For products that sell at a normal pace, or those with deep inventory, the risk of over-selling is relatively low. In this situation, you can keep your product catalog update strategy simple:

  • Configure a Replace Feed for daily updates. This feed should contain all fields, including the most up-to-date inventory value.
  • Configure a Update Feed with incremental updates (typically the inventory field) at a frequency that feels reasonable. You can start with updates every 12 hours, and increase the frequency as you see fit.

Fast-Selling Products

For fast-selling products, with shallow or very dynamic inventory, you may want to update volatile fields such as inventory in a more timely basis. You can use the Real-Time Batch API for this purpose. Here's a general strategy that you can follow:

  • Configure a Replace Feed for daily updates. This feed should contain all mandatory Product Catalog fields, and omit volatile fields such as inventory. The purpose of this feed is to update fields that are more static in nature, and defer the updates of volatile fields using the Real-Time API.
  • Use the Real-Time Batch API to update volatile fields such as inventory when the value changes in your backend, or at a fixed frequency. It is important that the fields updated using this technique are not included in your Replace Feed for consistency reasons.

Example — Updates using the Real-Time Batch API

curl \
  -d @body.json \
  -H "Content-Type: application/json"
  {
    "access_token": "<ACCESS_TOKEN>",
    "item_type": "PRODUCT_ITEM",
    "requests": [      
      {
        "method": "UPDATE",
        "retailer_id": "SKU1234567",
        "data": {
          "inventory": "1337",
        }
      }
    ]
  } https://graph.facebook.com/<CATALOG_ID/batch

Batch API requests are asynchronous. You should check for the request status and its result to make sure that all your updates are successful.

If you're managing a small number of products, you can also update each product individually using the Graph API directly in lieu of the Real-Time Batch API. Because of Graph API rate-limiting and throttling, this approach is only applicable to a small number of products. The exact number of products you can update using this approach depends on the quota applied to your Facebook app. We recommend that you use the Real-Time Batch API if you're updating more than a dozen of products at a time.

Example — Updates using the Graph API

curl -d "inventory=1337" -X POST https://graph.facebook.com/<FACEBOOK_PRODUCT_ID>
access_token: PAGE_ACCESS_TOKEN

If using the Graph API, use a Facebook product ID. If using the batch API, use your own ID (the retailer_id).

Hybrid Catalog (slow & fast selling products)

Not all of your products will sell at the same velocity. This obviously depends on the popularity of your products, but also how you market or promote them.

You can partition your products using multiple product feeds. For example, you may create one feed dedicated to fast-selling products, and another one specialized for slow-selling products. You could then apply different strategies described above to each of your product feeds. A given product (identified by the id field) can only exist in one and only one Product Feed at any time.

Inventory Thresholds

Another common technique to mitigate against over-selling is to take a pessimistic approach to inventory allocation. For example, when a particular item is close to running Out-Of-Stock as identified in your warehouse, you can set the inventory level in your Product Catalog to zero. This is effectively an optimization for under-selling, but can help if over-selling is a concern.

If you know how fast each of your products sell, you can partition them into different buckets and apply a different threshold for each bucket depending on its selling profile. Fast selling products typically need a higher threshold value, while slow selling products can probably use a lower threshold value for being marked "Out-Of-Stock".