Backorders

Beta

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