DocsAdminCatalog and InventoryInventory

Backorders

Beta

Backorders let customers purchase products that are currently out of stock, up to a configurable limit per location. When backorders are enabled, BigCommerce tracks backordered quantities separately from on-hand inventory, giving you visibility into fulfillment obligations and the ability to set limits on how many units can be backordered.

This guide covers the API endpoints and events involved in creating, adjusting, querying, and monitoring backorders.

Tracking backorders in orders

Use the V2 Orders API to include backordered quantities when creating or updating an order. The quantity_backordered field tracks how many units of a line item are backordered.

PUT /stores/{store_hash}/v2/orders/{order_id}

1{
2  "products": [
3    {
4      "id": 8,
5      "quantity": 50,
6      "quantity_backordered": 100
7    }
8  ]
9}

You can also supply quantity_backordered when sending a POST request to create an order. The field is returned in the response when the order has backordered items.

Error response for unavailable quantities

If a customer attempts to order more than the available stock plus the backorder limit, the API returns a 409 error with details about the constraint:

1[
2  {
3    "status": 409,
4    "message": "Quantities of one or more products are out of stock or did not meet quantity requirements.",
5    "details": {
6      "errors": [
7        {
8          "type": "OutOfStock",
9          "message": "Insufficient stock of variant(id: 74), available stock: 10, available quantity for backorder: 45. order(id: ), channel(id: 1), location(id: 1).",
10          "variant_id": 74,
11          "location_id": 1,
12          "available_quantity": 10,
13          "available_quantity_for_backorder": 45
14        }
15      ]
16    }
17  }
18]

Adjusting backorder inventory

Use the V3 Inventory Adjustments endpoints to set or modify the qty_backordered value for items at specific locations.

Absolute adjustments

Set backorder quantities to exact values.

PUT /stores/{store_hash}/v3/inventory/adjustments/absolute

1{
2  "reason": "Absolute adjustment reason",
3  "items": [
4    {
5      "location_id": 1,
6      "variant_id": 1,
7      "quantity": 1,
8      "qty_backordered": 0
9    },
10    {
11      "location_id": 2,
12      "variant_id": 3,
13      "quantity": 1
14    },
15    {
16      "location_id": 3,
17      "sku": "sku-4",
18      "qty_backordered": 0
19    },
20    {
21      "location_id": 1,
22      "sku": "sku-5",
23      "quantity": 1,
24      "qty_backordered": 0
25    },
26    {
27      "location_id": 1,
28      "product_id": 111,
29      "quantity": 7,
30      "qty_backordered": 0
31    }
32  ]
33}

Relative adjustments

Increment or decrement backorder quantities relative to their current values.

POST /stores/{store_hash}/v3/inventory/adjustments/relative

1{
2  "reason": "Relative adjustment reason",
3  "items": [
4    {
5      "location_id": 1,
6      "variant_id": 1,
7      "quantity": 1,
8      "qty_backordered": -1
9    },
10    {
11      "location_id": 2,
12      "variant_id": 3,
13      "quantity": 1
14    },
15    {
16      "location_id": 3,
17      "sku": "sku-4",
18      "qty_backordered": -3
19    },
20    {
21      "location_id": 1,
22      "sku": "sku-5",
23      "quantity": -1
24    }
25  ]
26}

Configuring backorder limits

Use the V3 Inventory endpoints to read current backorder levels and set the backorder_limit for items at a location.

Get inventory at a location

GET /stores/{store_hash}/v3/inventory/locations/{location_id}/items

1{
2  "data": [
3    {
4      "identity": {
5        "sku": "RE-130",
6        "variant_id": 78,
7        "product_id": 130
8      },
9      "available_to_sell": 10,
10      "total_inventory_onhand": 12,
11      "qty_backordered": 0,
12      "settings": {
13        "safety_stock": 2,
14        "is_in_stock": true,
15        "warning_level": 2,
16        "bin_picking_number": "1",
17        "backorder_limit": 33
18      }
19    }
20  ],
21  "meta": {}
22}

Get inventory across all locations

GET /stores/{store_hash}/v3/inventory/items

1{
2  "data": [
3    {
4      "identity": {
5        "sku": "RE-130",
6        "variant_id": 79,
7        "product_id": 120,
8        "sku_id": 0
9      },
10      "locations": [
11        {
12          "location_id": 1,
13          "location_code": "BC-LOCATION-1",
14          "location_name": "Default location",
15          "available_to_sell": 10,
16          "total_inventory_onhand": 11,
17          "location_enabled": true,
18          "qty_backordered": 0,
19          "settings": {
20            "safety_stock": 1,
21            "is_in_stock": true,
22            "warning_level": 1,
23            "bin_picking_number": "1",
24            "backorder_limit": 33
25          }
26        }
27      ]
28    }
29  ],
30  "meta": {}
31}

Update backorder limit

PUT /stores/{store_hash}/v3/inventory/locations/{location_id}/items

1{
2  "settings": [
3    {
4      "identity": {
5        "sku": "SLCTBS-A9615491",
6        "variant_id": 1,
7        "product_id": 77
8      },
9      "backorder_limit": 100
10    }
11  ]
12}

Querying backorder data with GraphQL

Use the Admin GraphQL API to query inventory data including backorder fields at the product and variant level.

1{
2  store {
3    products {
4      edges {
5        node {
6          id
7          inventory {
8            aggregated {
9              availableToSell
10              warningLevel
11              backorderLimit
12              availability
13              onHand
14              qtyBackordered
15            }
16          }
17          variants {
18            edges {
19              cursor
20              node {
21                id
22                inventory {
23                  aggregated {
24                    availableToSell
25                    warningLevel
26                    backorderLimit
27                    availability
28                    onHand
29                    qtyBackordered
30                  }
31                }
32              }
33            }
34          }
35        }
36      }
37    }
38  }
39}

Webhooks

Subscribe to these webhook events to monitor backorder activity.

Backorder limit reached

Fires when the backorder limit for a product has been reached:

store/channel/{channel_id}/inventory/product/backorder_limit_reached

Backorder quantity changed

Fires when the backordered quantity changes for a product:

store/channel/{channel_id}/inventory/product/stock_changed