Inventory and Location Webhooks

Buy Online, Pick up in Store allows merchants to distribute inventory among locations. Developers might need notification when inventories or locations change. This notification helps them perform downstream actions required to manage inventory at multiple locations. To this end, developers can subscribe to webhook events for changes to inventory or location.

This page is a reference for inventory and location webhooks for Buy Online, Pick up in Store. This article assumes that you're familiar with webhooks. For a general introduction to webhooks, see Webhooks Overview.

Storefront channels share the inventory for a product or variant. A product or variant's inventory settings apply to all storefront channels. The * in the scope indicates that you subscribe to inventory events across all storefront channels. An inventory change fires a single webhook event.

You can track inventory changes at any location. A product or variant's inventory levels and settings apply to a specific location. When you update inventory, the callback returns the location for the inventory.

Creating a webhook

To create a webhook, send a request to the Create a webhook endpoint. Follow the process described in the Webhooks Overview.

The following example creates a webhook that subscribes to changes in inventory settings.

Example request: Create a webhook

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/hooks
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "scope": "store/channel/*/inventory/product/settings_changed", // The `*` indicates that you subscribe to events across all storefront channels 
  "destination": "https://placeholder.ngrok.io/webhooks", // replace placeholder.ngrok.io with your HTTPS tunnel URL
  "is_active": true
}

The destination URL must be served on port 443; custom ports are not currently supported.
It can take up to one minute for a newly created webhook to work.

For information on creating a webhook, consult the creating a webhook section of the Webhooks Overview.

Callback structure

For webhook callback structure reference, see Webhook Events.

Inventory

The following inventory webhook events fire in response to changes in inventory for a product or variant.

You can track inventory changes for products or variants. The * in the scope indicates that you subscribe to inventory events across all storefront channels. An inventory change fires a single webhook event.

Storefront channels share the inventory for a product or variant. For order-related events, the webhook fires a single event in response to a change from any storefront channel. For example, placing an order from any channel can trigger one webhook event.

A store's inventory settings affect when stock levels change through an order. For example, stock levels can change when you either place or complete/ship an order. Stock levels can also change when you refund or cancel an order. Global settings apply when inventory changes through a manual order (opens in a new tab). Settings for a channel apply when inventory changes through an order in a channel.

Name / Scope	Description	Corresponding Endpoint
`store/channel/*/inventory/product/stock_changed`	Fires when a product or variant stock level changes at a location. For example, stock levels can change by manual merchant adjustments in the control panel or API.	Absolute adjustment
`store/channel/*/inventory/product/low_stock_reached`	Fires when a product or variant stock level is lower or equal to the low-stock value at a location. Stock levels must change through an order.	not applicable
`store/channel/*/inventory/product/out_of_stock_reached`	Fires when a product or variant stock level is zero at a location. Stock levels must change through an order.	not applicable
`store/channel/*/inventory/product/settings_changed`	Fires when a product's safety stock, `is_in_stock` flag, or warning level changes at a location. A product or variant's inventory settings apply to all storefront channels. Changing a product or variant's inventory settings triggers one webhook event.	Update inventory settings for a location

Inventory payload objects take the form that follows:

Example stock changed payload object

{
  "producer": "stores/{store_hash}",
  "hash": "996ea203c939d05ca667a515ef2f029976d6df80",
  "created_at": 1682624640,
  "store_id": "1234567890",
  "scope": "store/channel/*/inventory/product/stock_changed",
  "data": {
    "variant_id": 127,
    "product_id": 113,
    "location_id": 2
  }
}

The channel does not have to be active or visible for you to track changes.

Locations

The following location webhook events fire in response to actions that affect a location. You can track changes for any location.

Name / Scope	Description	Corresponding Endpoint
`store/inventory/location/created`	Fires when a location is created.	Create locations
`store/inventory/location/updated`	Fires when a location is updated, including enabling or disabling a location.	Update locations

Location payload objects take the form that follows:

Example location created payload object

{
  "producer": "stores/{store_hash}",
  "hash": "f23133c2b4caa5a8763b678fed2e3b643348599d",
  "created_at": 1682627509,
  "store_id": "1234567890",
  "scope": "store/inventory/location/created",
  "data": {
    "location_id": 2
  }
}

Resources

Did you find what you were looking for?

Channel events Metafields