> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Query Inventory with the GraphQL Storefront API

The GraphQL Storefront API allows you to fetch inventory for products and variants in your store location(s).
The queries can show online availability for products or availability at location(s). You can filter by product or variant when fetching inventory.

**Default behavior:** By default, Stencil's native storefront and GraphQL's Get Stock by Locations queries support stock levels from only the *default* location. Aggregated stock includes stock from only the default location; queries for stock at each location return stock from only the default location.

**Alternate behavior:** Upon request, your store can have the following features:

* Stock *per location*
* Stock aggregated, or summed, from *all locations*

[Contact the Support team](https://support.bigcommerce.com/s/contact?language=en_US) if you want the alternate behavior on your storefront. Stencil storefront pages will then reflect these features, including home, Category, and Product details pages. You will need to customize default themes to have these features on Elastic Search, Cart, Checkout, and Orders pages. For example, you can [build a custom checkout](/developer/docs/admin/checkout-and-cart/open-checkout) on a headless storefront.

> **Note**
>
> In the alternate behavior, aggregated stock calculations include only stock from *active* locations. To check if a location is active, use the [Get locations](/developer/api-reference/rest/admin/management/inventory/locations/get-locations) endpoint.

Below are examples of queries that allow you to fetch inventory for storefront location(s).

For a general overview of the GraphQL Storefront API usage and capabilities, see [GraphQL Storefront API Overview](/developer/docs/storefront/guides/graphql-storefront-api).

## Fetch aggregate inventory for products

This query returns the aggregate inventory level for each product.

#### Request

**`Example request: Get aggregate inventory for a base product`**

```graphql title="Example request: Get aggregate inventory for a base product"
query {
  site {
    products {
      edges {
        node {
          entityId
          name
          inventory {
            aggregated {         // By default, includes inventory from only the default location
              availableToSell
              warningLevel
            }
          }
        }
      }
    }
  }
}
```

#### Response

**`Example response: Get aggregate inventory for a base product`**

```json title="Example response: Get aggregate inventory for a base product"
{
  "data": {
    "site": {
      "products": {
        "edges": [
          {
            "node": {
              "entityId": 113,
              "name": "Example Product 1",
              "inventory": {
                "aggregated": {
                  "availableToSell": 20,
                  "warningLevel": 5
                }
              }
            }
          },
          {
            "node": {
              "entityId": 115,
              "name": "Example Product 2",
              "inventory": {
                "aggregated": {
                  "availableToSell": 0,
                  "warningLevel": 0
                }
              }
            }
          }
        ]
      }
    }
  }
}
```

In the example response, Example Product 1 has an aggregate inventory of 11.

> **Note**
>
> You can filter by product so that only the inventory for certain products will be returned. To do so, use the entity IDs of the products you wish to return.
> For example, in the example response, Example Product 1 has an entityId of 113. You can make a new request that filters for this product by using entityId 113. See GraphQL Playground for documentation.

### How inventory settings affect product inventories returned

The products returned depend on a store's inventory settings for out-of-stock products. If a merchant decides to hide out-of-stock products completely, out-of-stock products will not be returned. In the following example, Example Product 2s are out-of-stock and therefore, only (in-stock) Example Product 1 is returned:

**`Example JSON Response`**

```json title="Example JSON Response" showLineNumbers={false}
{
  "data": {
    "site": {
      "products": {
        "edges": [
          {
            "node": {
              "entityId": 113,
              "name": "Example Product 1",
              "inventory": {
                "aggregated": {
                  "availableToSell": 20,
                  "warningLevel": 5
                }
              }
            }
          }
        ]
      }
    }
  }
}
```

The inventory levels for products depend on a store's inventory settings for displaying stock levels. If a merchant decides to not show stock levels, inventory levels will return `null` as shown here:

**`Example JSON Response`**

```json title="Example JSON Response" showLineNumbers={false}
{
  "data": {
    "site": {
      "products": {
        "edges": [
          {
            "node": {
              "entityId": 113,
              "name": "Example Product 1",
              "inventory": {
                "aggregated": null
              }
            }
          },
          {
            "node": {
              "entityId": 115,
              "name": "Example Product 2",
              "inventory": {
                "aggregated": null
              }
            }
          }
        ]
      }
    }
  }
}
```

Similarly, if a merchant decides to only show stock levels for a product when stock is low, inventory levels for products that aren't low or aren't out of stock will return `null`. In the following example, Example Product 1 returns `null` because it is not low or out of stock:

**`Example JSON Response`**

```json title="Example JSON Response" showLineNumbers={false}
{
  "data": {
    "site": {
      "products": {
        "edges": [
          {
            "node": {
              "entityId": 113,
              "name": "Example Product 1",
              "inventory": {
                "aggregated": null
              }
            }
          },
          {
            "node": {
              "entityId": 115,
              "name": "Example Product 2",
              "inventory": {
                "aggregated": {
                  "availableToSell": 0,
                  "warningLevel": 0
                }
              }
            }
          }
        ]
      }
    }
  }
}
```

## Fetch aggregate inventory for variants

This query returns the aggregate inventory level for each variant. In this example, the query returns data for only one product by specifying the product's entityId.

#### Request

**`Example request: Get aggregate inventory for a variant`**

```graphql title="Example request: Get aggregate inventory for a variant"
query {
  site {
    products (entityIds:[113]) {
      edges {
        node {
          entityId
          name
          variants {
            edges {
              node {
                entityId
                sku
                inventory {
                  aggregated {        // By default, includes inventory from only the default location
                    availableToSell
                    warningLevel
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### Response

**`Example response: Get aggregate inventory for a variant`**

```json title="Example response: Get aggregate inventory for a variant"
{
    "data": {
      "site": {
        "products": {
          "edges": [
            {
              "node": {
                "entityId": 113,
                "name": "Example Product 1",
                "variants": {
                  "edges": [
                    {
                      "node": {
                        "entityId": 95,
                        "sku": "ABC-1111-PI",
                        "inventory": {
                          "aggregated": {
                            "availableToSell": 11,
                            "warningLevel": 20
                          }
                        }
                      }
                    },
                    {
                      "node": {
                        "entityId": 96,
                        "sku": "ABC-1111-PU",
                        "inventory": {
                          "aggregated": {
                            "availableToSell": 0,
                            "warningLevel": 0
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
  }
```

## Fetch inventory for variants at each location

This query returns the inventory level for a specified variant. In this example, the query returns data for only one product and only one variant by specifying the product's entityId and the variant's entityId.

> **Note**
>
> * The `isInStock` field is calculated based on `is_in_stock` and `availableToSell` values. The `is_in_stock` value is set by the [Inventory API](/developer/api-reference/rest/admin/management/inventory/items/get-inventory-items) or in the product section of the control panel.
> * `isInStock` is TRUE if `is_in_stock` is TRUE and `available_to_sell` is more than zero.

#### Request

**`Example request: Get a location's inventory for a variant`**

```graphql title="Example request: Get a location's inventory for a variant"
query {
  site {
    products (entityIds:[113]) {
      edges {
        node {
          entityId
          name
          variants (entityIds:[95]) {
            edges {
              node {
                entityId
                sku
                inventory {
                  byLocation {     // By default, returns only the default location
                    edges {
                      node {
                        locationEntityId
                        locationEntityCode
                        locationEntityTypeId
                        locationDistance {
                          value
                          lengthUnit
                        }
                        availableToSell
                        warningLevel
                        isInStock
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### Response

**`Example response: Get a location's inventory for a variant`**

```json title="Example response: Get a location's inventory for a variant"
{
    "data": {
      "site": {
        "products": {
          "edges": [
            {
              "node": {
                "entityId": 113,
                "name": "Example Product 1",
                "variants": {
                  "edges": [
                    {
                      "node": {
                        "entityId": 95,
                        "sku": "ABC-1111-PI",
                        "inventory": {
                          "byLocation": {
                            "edges": [
                              {
                                "node": {
                                  "locationEntityId": 1,
                                  "locationEntityCode": "BC-LOCATION-1",
                                  "locationEntityTypeId": "PHYSICAL",
                                  "locationDistance": null,
                                  "availableToSell": 6,
                                  "warningLevel": 20,
                                  "isInStock": false
                                }
                              },

                              // By default, responses don't include non-default locations
                              {
                                "node": {
                                  "locationEntityId": 2,
                                  "locationEntityCode": "BC-LOCATION-2",
                                  "locationEntityTypeId": "PHYSICAL",
                                  "locationDistance": null,
                                  "availableToSell": 5,
                                  "warningLevel": 20,
                                  "isInStock": false
                                }
                              }
                            ]
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
  }
```

> **Note**
>
> As shown in the example response, locations are identified by a unique ID (`locationEntityId`) and code (`locationEntityCode`).
> The location type ID (`locationEntityTypeId`) is the location type, either `PHYSICAL` or `VIRTUAL`.
> The location's code and type can be customized using Locations API.

### How inventory settings affect variant inventories returned

The following examples show how variant inventories are affected when a merchant decides to hide out-of-stock options.

The query returns variant inventories if a variant has stock in at least one location.

#### Request

**`Example request: Get inventory for a variant`**

```graphql title="Example request: Get inventory for a variant"
query {
  site {
    products (entityIds:[113]) {
      edges {
        node {
          entityId
          name
          variants (entityIds: [95]) {
            edges {
              node {
                entityId
                sku
                inventory {
                  aggregated {
                    availableToSell
                    warningLevel
                  }
                  byLocation {         // By default, returns only the default location
                    edges {
                      node {
                        locationEntityId
                        locationEntityCode
                        locationEntityTypeId
                        locationDistance {
                          value
                          lengthUnit
                        }
                        availableToSell
                        warningLevel
                        isInStock
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### Response

**`Example response: Get inventory for a variant`**

```json title="Example response: Get inventory for a variant"
{
    "data": {
      "site": {
        "products": {
          "edges": [
            {
              "node": {
                "entityId": 113,
                "name": "Example Product 1",
                "variants": {
                  "edges": [
                    {
                      "node": {
                        "entityId": 95,
                        "sku": "ABC-1111-PI",
                        "inventory": {
                          "aggregated": {
                            "availableToSell": 10,
                            "warningLevel": 10
                          },
                          "byLocation": {
                            "edges": [
                              {
                                "node": {
                                  "locationEntityId": 1,
                                  "locationEntityCode": "BC-LOCATION-1",
                                  "locationEntityTypeId": "PHYSICAL",
                                  "locationDistance": null,
                                  "availableToSell": 10,
                                  "warningLevel": 5,
                                  "isInStock": true
                                }
                              },

                              // By default, responses don't include non-default locations
                              {
                                "node": {
                                  "locationEntityId": 2,
                                  "locationEntityCode": "BC-LOCATION-2",
                                  "locationEntityTypeId": "PHYSICAL",
                                  "locationDistance": null,
                                  "availableToSell": 0,
                                  "warningLevel": 5,
                                  "isInStock": false
                                }
                              }
                            ]
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
  }
```

If a variant is out of stock at all locations, the variant is not returned. In the following example, variant `entityId: 95` is out of stock at all locations, but variant `entityId: 96` has stock in at least one location.

#### Request

**`Example request: Get inventory for a variant`**

```graphql title="Example request: Get inventory for a variant"
query {
  site {
    products (entityIds:[113]) {
      edges {
        node {
          entityId
          name
          variants (entityIds:[95,96]) {
            edges {
              node {
                entityId
                sku
                inventory {
                  aggregated {
                    availableToSell
                    warningLevel
                  }
                  byLocation {          // By default, returns only the default location
                    edges {
                      node {
                        locationEntityId
                        locationEntityCode
                        locationEntityTypeId
                        locationDistance {
                          value
                          lengthUnit
                        }
                        availableToSell
                        warningLevel
                        isInStock
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### Response

**`Example response: Get inventory for a variant`**

```json title="Example response: Get inventory for a variant"
{
  "data": {
    "site": {
      "products": {
        "edges": [
          {
            "node": {
              "entityId": 113,
              "name": "Example Product 1",
              "variants": {
                "edges": [
                  {
                    "node": {
                      "entityId": 96,
                      "sku": "ABC-1111-PU",
                      "inventory": {
                        "aggregated": {
                          "availableToSell": 10,
                          "warningLevel": 5
                        },
                        "byLocation": {
                          "edges": [
                            {
                              "node": {
                                "locationEntityId": 1,
                                "locationEntityCode": "BC-LOCATION-1",
                                "locationEntityTypeId": "PHYSICAL",
                                "locationDistance": null,
                                "availableToSell": 10,
                                "warningLevel": 5,
                                "isInStock": true
                              }
                            },

                            // By default, responses don't include non-default locations
                            {
                              "node": {
                                "locationEntityId": 2,
                                "locationEntityCode": "BC-LOCATION-2",
                                "locationEntityTypeId": "PHYSICAL",
                                "locationDistance": null,
                                "availableToSell": 0,
                                "warningLevel": 0,
                                "isInStock": false
                              }
                            }
                          ]
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
  }
}
```

The following example shows the returned response if you query for variants whose inventories are zero at all locations:

#### Request

**`Example request: Get inventory for a variant`**

```graphql title="Example request: Get inventory for a variant"
query {
  site {
    products (entityIds:[113]) {
      edges {
        node {
          entityId
          name
          variants (entityIds:[95,96]) {
            edges {
              node {
                entityId
                sku
                inventory {
                  aggregated {
                    availableToSell
                    warningLevel
                  }
                  byLocation {
                    edges {
                      node {
                        locationEntityId
                        locationEntityCode
                        locationEntityTypeId
                        locationDistance {
                          value
                          lengthUnit
                        }
                        availableToSell
                        warningLevel
                        isInStock
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### Response

**`Example response: Get inventory for a variant`**

```json title="Example response: Get inventory for a variant"
{
    "data": {
      "site": {
        "products": {
          "edges": [
            {
              "node": {
                "entityId": 113,
                "name": "Example Product 1",
                "variants": {
                  "edges": []
                }
              }
            }
          ]
        }
      }
    }
  }
```