Merchant configuration

To build a Buy Online, Pick up in Store solution, you must first create a location for pickup. You can then manage inventory for a location, configure inventory settings such as stock warning levels. Last, you must create a method for pickup. You can define collection instructions and assign the method to a location.

Create locations

Create one or more locations using the Create locations endpoint. Include a pickup location from which customers can pick up their orders.

Example request: Create locations

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/inventory/locations
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "code": "DTOWN_PARK_ST",
    "label": "Downtown Location - Park Lane",
    "description": "Customer-facing additional details about this location",
    "managed_by_external_source": false,
    "type_id": "PHYSICAL",
    "enabled": true,
    "operating_hours": {
      "sunday": {
        "open": false,
        "opening": "00:00",
        "closing": "00:00"
      },
      "monday": {
        "open": true,
        "opening": "09:00",
        "closing": "17:00"
      },
      "tuesday": {
        "open": true,
        "opening": "09:00",
        "closing": "17:00"
      },
      "wednesday": {
        "open": true,
        "opening": "09:00",
        "closing": "17:00"
      },
      "thursday": {
        "open": true,
        "opening": "09:00",
        "closing": "17:00"
      },
      "friday": {
        "open": true,
        "opening": "09:00",
        "closing": "17:00"
      },
      "saturday": {
        "open": false,
        "opening": "00:00",
        "closing": "00:00"
      }
    },
    "time_zone": "Etc/UTC",
    "address": { 
      "email": "jane.doe@bigcommerce.com",
      "address1": "100 Park Lane",
      "address2": "",
      "city": "Austin",
      "state": "TX",
      "zip": "78726",
      "country_code": "US",
      "phone": "+15128654500",
      "geo_coordinates": {
        "longitude": -97.849560,
        "latitude": 30.404500
      } 
    },
    "storefront_visibility": true,
    "special_hours": [
      {
        "label": "Christmas Eve",
        "date": "2022-12-25",
        "open": true,
        "opening": "00:00",
        "closing": "09:00",
        "all_day": false,
        "annual": false
      }
    ]  
  }
]

Update location details

After you create a location, you can update its details using the Update locations endpoint.

Example request: Update locations

PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/inventory/locations
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "id": 2,
    "code": "DTOWN_PARKST",
    "label": "Downtown Location - Park Lane",
    "description": "Customer-facing additional details about this location.",
    "managed_by_external_source": false,
    "type_id": "PHYSICAL",
    "enabled": true,
    "operating_hours": {
      "sunday": {
        "open": false,
        "opening": "00:00",
        "closing": "00:00"
      },
      "monday": {
        "open": true,
        "opening": "09:00",
        "closing": "17:00"
      },
      "tuesday": {
        "open": true,
        "opening": "09:00",
        "closing": "17:00"
      },
      "wednesday": {
        "open": true,
        "opening": "09:00",
        "closing": "17:00"
      }
    },
    "time_zone": "Etc/UTC",
    "address": {
      "email": "jane.doe@bigcommerce.com",
      "address1": "100 Park Lane",
      "address2": "",
      "city": "Austin",
      "state": "TX",
      "zip": "78726",
      "country_code": "US",
      "phone": "+15128654500",
      "geo_coordinates": {
        "longitude": -97.849560,
        "latitude": 30.404500
      }
    },
    "storefront_visibility": true,
    "special_hours": [
      {
        "label": "Christmas Eve",
        "date": "2022-12-25",
        "open": true,
        "opening": "00:00",
        "closing": "09:00",
        "all_day": false,
        "annual": false
      }
    ]
  }
]

Get all locations

After you create one or more locations, use the Get locations endpoint to retrieve location details.

Example request: Get locations

GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/inventory/locations
X-Auth-Token: {{access_token}}
Accept: application/json

Manage inventory for a location

Buy Online, Pick up in Store uses the Inventory API to manage inventory quantities in two ways:

Absolute quantity sets or overwrites the inventory quantity of a product or variant.
Relative quantity adjusts a product or variant's inventory quantity by adding to or subtracting from the existing quantity.

Before setting inventory quantity to a location, check the inventory tracking configurations that have been enabled. There are three inventory tracking configurations:

Inventory is tracked by product - This setting is used if your product has no variations. For example, champagne glasses or .
Inventory is tracked by variant - This setting is used if your product has different attributes (variations), e.g. a shirt has various sizes and colors.
Inventory is not tracked - This setting is used if you do not have a need to track inventory quantity, e.g. you may sell a digital asset like a PDF or digital music title. When inventory is not tracked, the product will always be considered available to sell on your storefront, even if it may not be in your physical storage location.

It’s important to know the type of tracking when making absolute or relative adjustments, as this will ultimately determine how you author your API request to set inventory quantity.

Absolute adjustments to inventory quantity

You can make absolute adjustments for inventory tracked by product. To make absolute adjustments, send a request to the Absolute adjustment endpoint.

Example request: Absolute adjustment to inventory

PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/inventory/adjustments/absolute
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
{
  "items": [
    {
      "location_id": 1,
      "product_id": 111,
      "quantity": 10
    }
  ]
}

You can make absolute adjustments for inventory tracked by variant.

Example request: Absolute adjustment to inventory

PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/inventory/adjustments/absolute
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
{
  "items": [
    {
      "location_id": 2,
      "variant_id": 78,
      "quantity": 5
    },
    {
      "location_id": 2,
      "variant_id": 79,
      "quantity": 5
    }
  ]
}

Relative adjustments to inventory quantity

You can make relative adjustments to inventory tracked by product. To make relative adjustments, send a request to the Relative inventory adjustments endpoint.

Example request: Relative adjustment to inventory

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/inventory/adjustments/relative
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
{
  "items": [
    {
      "location_id": 2,
      "product_id": 111,
      "quantity": -2
    },
    {
      "location_id": 2,
      "product_id": 112,
      "quantity": 2
    }
  ]
}

You can also make relative adjustments to inventory tracked by variant.

Example request: Relative adjustment to inventory

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/inventory/adjustments/relative
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
{
  "items": [
    {
      "location_id": 2,
      "variant_id": 78,
      "quantity": -2
    },
    {
      "location_id": 2,
      "variant_id": 79,
      "quantity": 2
    }
  ]
}

Configure inventory settings

In addition to making absolute or relative adjustments to inventory quantities, other inventory settings can also be set, including:

Warning Level - This is the same as the inventory_warning_level attribute in the Catalog API
Safety Stock - The quantity of product that is stored to prevent an out-of-stock situation. It serves as insurance against sudden or rapid fluctuations in demand. Safety stock quantity is not included in the "available to sell" quantity that may be displayed to customers on the storefront.

To do so, send a request to the Update inventory settings for a location endpoint.

You can configure inventory settings for inventory tracked by product.

Example request: Update inventory settings for a location

PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/inventory/locations/{location_id}/items
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
{
  "settings": [
    {
      "identity": {
        "product_id": 111
      },
      "safety_stock": 2,
      "warning_level": 5
    }
  ]
}

You can configure inventory settings for inventory tracked by variant.

Example request: Update inventory settings for a location

PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/inventory/locations/{location_id}/items
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
{
  "settings": [
    {
      "identity": {
        "variant_id": 78
      },
      "safety_stock": 2,
      "warning_level": 5
    },
    {
      "identity": {
        "variant_id": 79
      },
      "safety_stock": 2,
      "warning_level": 5
    }
  ]
}

Get inventory by location

At this point you may want to view inventory by location. To do so, send a request to the Get inventory at a location endpoint.

Example request: Get inventory at a location

GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/inventory/locations/{location_id}/items
X-Auth-Token: {{access_token}}
Accept: application/json

[Optional step] Get a product's inventory across all locations

Alternatively, you can view aggregate inventory information for a product, across all locations that stock it. Send a request to the Get inventory at locations endpoint and filter by product_id, variant_id, or sku.

Example request: Get inventory at locations

GET https://api.bigcommerce.com/stores/{store_hash}/v3/inventory/items?variant_id=123
X-Auth-Token: {{access_token}}
Accept: application/json

Create a pickup method and assign it to a location

Once locations have been created, you can create pickup methods and assign them to a location. To do so, send a request to the Create pickup methods endpoint.

Example request: Create pickup methods

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/pickup/methods
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "location_id": 1,
    "display_name": "In-store pickup",
    "collection_instructions": "Visit the service desk on arrival with your order number",
    "collection_time_description": "9 AM to 5 PM"
  }
]

Add a second pickup method and assign it to a location

Some merchants offer multiple pickup options at a single location. For example, a merchant might offer both in-store pickup and curbside pickup. To achieve this, send a request to the Create pickup methods endpoint to create another pickup method and assign it to the same location.

Example request: Create pickup methods

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/pickup/methods
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "location_id": 1,
    "display_name": "Curbside pickup",
    "collection_instructions": "See our staff member outside the store",
    "collection_time_description": "Wait for a pickup confirmation and visit during business hours."
  }
]

Update a specific detail for a pickup method

If you need to update the original pickup method details, you can use the Pickup Methods API. Update any of the following details using the Update pickup methods endpoint:

location_id
display_name
collection_instructions
collection_time_description

Example request: Update pickup methods

PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/pickup/methods
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
[
  {
    "id": 2,
    "collection_instructions": "See our friendly staff member outside the store."
  }
]

[Optional step] Verify pickup method assignment

Once you have assigned the pickup methods to the location(s), you can check what you've configured. To do so, send a request to the Get pickup methods endpoint.

Example request: Get pickup methods

GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/pickup/methods
X-Auth-Token: {{access_token}}
Accept: application/json

Did you find what you were looking for?

Overview Browse and discover as a shopper