Inventory

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.

Note: The item without inventory setup cannot be tagged or purchased, you still can use it for dynamics ads without checkout.

This section describes important concepts associated with inventory management:

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. Whenever a user places an order, the inventory level of the corresponding products is decremented.

The Commerce Platform automatically increment this value or re-stocks the product in case of user-initiated cancellations. In the case of seller-initiated cancellations, you can re-stock 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 Product Catalog uploads or other techniques (read Inventory Update Strategies for more information) is considered the source of truth, and is always used to overwrite the value cached on our backend.

We keep two types of inventory counts on our end: a provided inventory and an available inventory. The provided inventory is the value that you provide via Product Catalog uploads or other techniques (read Inventory Update Strategies for more information). The available inventory is the value that customers can purchase and it takes under consideration not processed orders. For more about these two inventory types, see [this section]](#products-life-cycle).

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 will mark the product as Out-Of-Stock and restrict anyone from purchasing additional units. You should do a best-effort attempt at re-stocking your products regularly since Out-Of-Stock products negatively affect the user experience and your brand perception.

If a buyer stumbles on an Out-Of-Stock product, we will 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

When a product is discontinued, you will be tempted to just delete it from your Product Catalog. Please don't do this!

Deleting products from your catalog may cause undesirable effects, such as product tags and images disappearing. 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 will ensure that the Commerce Platform can link your product back to a known entity and manage different situations gracefully.

Products life cycle

Everytime you update inventory, we will update the provided inventory. This number does not correspond to the number of items available for customer purchase. Facebook will keep track of incoming orders (which may be in different states) and subtract unacknowledged orders to calculate a final available inventory. This number may not be exposed outside of our platform.

Available Inventory = Provided Inventory - Not Acknowledged Orders.

After orders are acknowledged, there is a 30 minute buffer to allow you to process orders and update inventory numbers (via the catalog) before we remove those acknowledged orders from our counter.

Over-selling

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

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

If you are frequently faced with overselling, you can process orders at a more frequent basis, and adjust the inventory level of your products accordingly.

Inventory Integration Strategy

You can update inventory in a different way depending on the type of integration you are doing:

  • Via Catalog manager UI (small product set, testing, etc.)
  • A feed with scheduled or manual upload
  • Using catalog API

We recommend to use feed updates for slow selling products or the pre-allocated inventory. We recommend for fast-selling products and combined products sets that are shared between different channels to use the Batch API or combination of both.

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. We recommend a Replace Feed to run over night, to avoid delays in item processing and review.
  • 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.

Here's an example of 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. Read the Batch API documentation for more information.

If you are 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, a good rule of thumb is that you should use the Real-Time Batch API if you are updating more than a dozen of products at a time.

Here's an example of 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, a.k.a. the retailer_id.

Hybrid Catalog (slow & fast selling products)

It is important to recognize that 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/promote them. Regardless, it's worth noting that you can treat products with different sales velocity differently.

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. Note that 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 cautious 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 will typically need a higher threshold value, while slow selling products can probably use a lower threshold value for being marked Out-Of-Stock.