Docs
Management API
Locations

Locations

Locations

By default, all BigCommerce stores have at least one location (id = 1). You can create additional locations to track inventory against using the /locations endpoints. Initially, we will only support the creation of physical inventory locations, which must have an address.

Metafields

Metafields allow you to add additional fields about your storeʼs locations.

Create Locations

POST /inventory/locations

Request

Create new locations.

Limits

  • Limit of 50 concurrent requests.
  • Limit of 100 active locations.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

array | application/json

  • code    string

    Location user-defined unique identifier.
    Example: BIGC-1

  • label    string

    Location label.
    Example: Central store

  • description    string

    Description of location. This field can be returned by the GraphQL Storefront API so that additional details can be exposed to customers on the storefront (customer-facing).
    Example: Central shop of the world

  • managed_by_external_source    boolean

    Indicates if the third-party system is the source of truth for inventory values. If set to true, manually editing inventory in BCʼs control panel will be disabled.

    Default: false

  • type_id    string

    Describe type of given location.

    Allowed: PHYSICAL | VIRTUAL

    Default: PHYSICAL

  • enabled    boolean

    Default: true

  • operating_hours    object

    Schedule with opening and closing hours for each day of the week.

  • time_zone    string

    Time zone of location. For a list of valid time zones, please view: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
    Example: Etc/UTC

  • address    object

    Address is required if the locationʼs type_id is PHYSICAL.

  • storefront_visibility    boolean

    Default: true

  • special_hours    array[object]

Create Locations

Response

Locations have been successfully created.

Body

object | application/json

  • transaction_id    string

    Unique identifier of performed action.

example

Get Locations

GET /inventory/locations

Request

List locations. You can use optional filter parameters.

Limits

  • Limit of 50 concurrent requests.
  • Limit of 1000 items for payload length.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • location_id:in in query - integer
    Comma separated list of location_id.
  • location_code:in in query - string
    Comma separated list of location_code.
  • is_default in query - boolean
    Filter whether the location is the default.
  • type_id:in in query - string
    Comma separated list of locations type codes.
  • managed_by_external_source in query - boolean
    Filter whether an external source manages location inventory levels.
  • is_active in query - boolean
    Filter by active locations flag; return both if not specified.
  • storefront_visibility in query - boolean
    Filter by storefront_visibility flag; return both if not specified.
  • page in query - integer

    Specifies the page number in a limited (paginated) list of products.

  • limit in query - integer

    Controls the number of items per page in a limited (paginated) list of products.

example

Response

The request has been successfully processed.

Body

object | application/json

  • data    array[object]

  • meta    object

example

Update Locations

PUT /inventory/locations

Request

Update existing locations.

Limits

  • Limit of 50 concurrent requests.
  • Limit of 100 active locations.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.

Body

array | application/json

  • id    integer
    required

    Location immutable unique identifier.
    Example: 2

  • code    string

    Location user-defined unique identifier.
    Example: BIGC-2

  • label    string

    Location label.
    Example: Central store

  • description    string

    Description of location.
    Example: Central shop of the world

  • managed_by_external_source    boolean

    Indicates if the third-party system is the source of truth for inventory values. If set to true, manually editing inventory in BCʼs control panel will be disabled.

    Default: false

  • type_id    string

    Describe type of given location.

    Allowed: PHYSICAL | VIRTUAL

    Default: PHYSICAL

  • enabled    boolean

    Indicator of accessibility of the location.

    Default: true

  • operating_hours    object

    Schedule with opening and closing hours for each day of the week.

  • time_zone    string

    Time zone of location.
    Example: Etc/UTC

  • address    object

  • storefront_visibility    boolean

    Indicator of accessibility of location on the storefront.

    Default: true

  • special_hours    array[object]

Update Locations

Response

The request has been successfully processed.

Body

object | application/json

  • transaction_id    string

    Unique identifier of performed action.

example

Delete Locations

DELETE /inventory/locations

Request

Delete existing locations.

You cannot delete locations that are shipping origins or have open order transactions. The location with a location_id of 1 is the storeʼs default shipping origin, and you cannot change the shipping origin.

You can delete locations assigned to pickup methods.

Warning:

Deleting locations that have inventory also deletes its stock.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • location_id:in in query - integer
    required
    Comma separated list of location_id.

example

Response

Request has been successfully processed.

Body

object | application/json

  • transaction_id    string

    Unique identifier of performed action.

example

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
Update Inventory Settings for a LocationCreate Locations