Locations

Locations allow merchants to track product inventory across multiple physical or virtual locations. Locations also allow merchants to manage their store and warehouse physical addresses in a single source of truth, which can be used by tools such as store locator widgets or app integrations concerned with locations where a store’s business is conducted.

Default behavior: By default, Stencil’s native storefront and locations queries support stock levels from only the default location. If the default location runs out of stock, the product will be considered out of stock on the storefront, even if there is inventory in other locations.

Alternate behavior: By request, your store can instead use Aggregated stock, where stock from all locations is summed up for Stencil’s storefront and location queries. This means that if the default location has a stock of 0, but another location has a stock greater than 0, the product will still be considered in stock. If you would like to enable Aggregated stock, please contact our support team.

Managing locations

You can create up to the following number of locations:

Standard plan: up to 4
Plus plan: up to 5
Pro plan: up to 8
Enterprise plan: 100; can be customized by request

You can disable, remove visibility, and delete locations.

The enabled and storefront_visibility flags for a location determine whether a location is available for Storefront and Management APIs.

Both flags determine if a location will return through any of the Storefront APIs, including getting available pickup methods. The flags control location visibility through the Storefront APIs.
However, the enabled flag also controls:
- Whether a location can be used to create orders and pickup methods.
- Whether you can edit stock levels through the management APIs
- If any stock for products at a location contribute to the “available to sell” total returned by the Storefront APIs.
For example, a location can be “enabled”, allowing orders to be fulfilled at that location through the Order V2 or Checkout APIs. If its storefront_visibility is set to false, the details of that location are omitted from the Storefront APIs.

The Locations API allows you to manage locations. For examples, see Merchant Configuration under the End-to-end guides.

You can query locations using the GraphQL Storefront API. For examples, see Query Locations with the GraphQL Storefront API.

Due to the asynchronous nature of the Locations API, there may be a short delay before data is updated after the endpoints are called. Endpoints that manage these locations and inventory at these locations return a transaction_id for any write requests.

Location metafields

Manage location metafields using the Locations API.

To create a location metafield, send a request to the Create a location metafield endpoint. Each metafield must have a unique combination of key and value for a namespace.

Request

Response

Example request: Create a location metafield

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/inventory/locations/{{LOCATION_ID}}/metafields
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 {
7   "key": "location status",
8   "value": "upcoming",
9   "namespace": "headquarters",
10   "permission_set": "write_and_sf_access",
11   "description": "new location"
12 }

Location metafields that have storefront access permissions (i.e. permission set as read_and_sf_access or write_and_sf_access) can be returned in the GraphQL Storefront API. For example queries of this, see Query Locations with the GraphQL Storefront API.

Resources