Docs
Management API
Price lists

Price Lists

Populate different versions of catalog pricing and assign them to different customer groups at the variant level.

Price Lists

You can associate a Price List with a customer group either through the control panel or by using the Customer Groups API.

You can create Price List Assignments to assign Price Lists to a specific channel. Price Lists assigned to a channel apply to all shoppers on that channel, unless there are more specific assignments or customer group discounts set up for the shopper's customer group.

If an active Price List does not contain prices for a variant, the catalog pricing will be used. Price Lists provide overridden price values to the Stencil storefront. You can further customize the final price display using Stencil's handlebars objects.

To learn more about Price Lists, see Price Lists API.

Price Lists Assignments

Order of operations

IF Price List assigned to current customer group AND Price List assigned to current channel:

  • Use this Price List -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices)

ELSE IF Price List assigned to current customer group:

  • Use this Price List -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices)

ELSE IF Customer group discounts:

  • Use them -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices)

ELSE IF Channel has a default Price List:

  • Use this Price List -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices)

ELSE:

  • Fall back to the catalog price (or in the case of multi-currency, auto-converted prices)

Usage notes

  • You cannot assign Price Lists to a customer group with customer group discounts -- You must delete the customer group discounts first.
  • Bulk pricing Tiers can additionally be associated with a price record to indicate different pricing as the quantity in the cart increases.
  • If a variant has a Price Record, any existing product-level bulk pricing will not apply to the cart. For variants without Price Records, any existing product bulk pricing will apply.
  • Price Lists Records accepts bulk upsert. You can only do one bulk upsert at a time. Running more than one bulk upsert in parallel on the same store will cause a 429 error and the request will fail.
  • There are webhooks available for Price Lists assignments. The price list assignment webhook fires when a price list assignment is assigned, reassigned, or unassigned. Note that since Price Lists directly relate to products, neither product nor SKU webhooks are going to fire for corresponding changes, such as pricing.

Additional information

Webhooks

Related endpoints

Get All Price Lists

GET /pricelists

Request

Returns a list of Price Lists. Optional parameters can be passed in.

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.
  • name in query - string

    Filter items by name.

  • date_created in query - string

    Filter items by date_created.

  • date_modified in query - string
    Filter items by date_modified. For example v3/catalog/products?date_last_imported:min=2018-06-15
  • 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.
  • id:in in query - array
    Type: array[integer]
  • name:like in query - string
  • date_created:max in query - string
  • date_created:min in query - string
  • date_modified:max in query - string
  • date_modified:min in query - string

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json
Get All PriceLists.

  • data    array[object]

  • meta    object

    Data related to the response, including pagination and collection totals.

example

{
"data": [
{
"id": 1,
"name": "Warehouse",
"date_created": "2022-02-26T17:33:11Z",
"date_modified": "2022-05-08T14:05:27Z",
"active": true
},
{
"id": 2,
"name": "B2B",
"date_created": "2022-02-26T17:37:01Z",
"date_modified": "2022-02-26T17:37:01Z",
"active": true
},
{
"id": 3,
"name": "Wholesale",
"date_created": "2022-04-05T16:05:12Z",
"date_modified": "2022-04-05T16:05:12Z",
"active": true
}
],
"meta": {
"pagination": {
"total": 3,
"count": 3,
"per_page": 50,

Create a Price List

POST /pricelists

Request

Creates a Price List.

Required Fields

  • name

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

object | application/json
Creates a Price List.

  • name    string
    required

    The unique name of the Price List. Required in a POST request.
    Example: Wholesale

  • active    boolean

    Boolean value that specifies whether this Price List and its prices are active or not. Defaults to true.

    Example: true

example

{
"name": "Wholesale",
"active": true
}

Response

Body

object | application/json

PriceList Response returns for:

  • Create a PriceList
  • Get a PriceList
  • Update a PriceList

  • data    object

    Specifies the Common Price List properties.

  • meta    object

    Response metadata.

example

{
"data": {
"id": 4,
"name": "Wholesale Group - Trade Show",
"date_created": "2022-09-17T18:41:59Z",
"date_modified": "2022-09-17T18:41:59Z",
"active": false
},
"meta": {}
}

Delete All Price Lists

DELETE /pricelists

Request

Deletes a Price List. All associated price records are also removed. Optional parameters can be passed in.

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.
  • id:in in query - array

    Filter by ID. Accepts multiple comma-separated values.

    Type: array[integer]
  • name in query - string

    Filter items by name.

example

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

204 No Content. The action has been performed and no further information will be supplied. null is returned.

Body

object | application/json

    example

    {}

    Get a Price List

    GET /pricelists/{price_list_id}

    Request

    Returns a single Price List.

    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.
    • price_list_id in path - integer
      required

      The ID of the Price List requested.

    example

    curl --request GET \
    --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'X-Auth-Token: {{token}}'

    Response

    Body

    object | application/json

    PriceList Response returns for:

    • Create a PriceList
    • Get a PriceList
    • Update a PriceList

    • data      object

      Specifies the Common Price List properties.

    • meta      object

      Response metadata.

    example

    {
    "data": {
    "id": 2,
    "name": "B2B",
    "date_created": "2022-02-26T17:37:01Z",
    "date_modified": "2022-09-17T18:34:36Z",
    "active": true
    },
    "meta": {}
    }

    Update a Price List

    PUT /pricelists/{price_list_id}

    Request

    Updates a Price List.

    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.
    • price_list_id in path - integer
      required

      The ID of the Price List requested.

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

    Body

    object | application/json
    Update a PriceList

    • name      string
      required

      The unique name of the Price List. Required in a POST request.
      Example: Wholesale

    • active      boolean

      Whether or not this Price List and its prices are active. Defaults to true.

      Example: true

    example

    {
    "name": "Wholesale",
    "active": true
    }

    Response

    Body

    object | application/json

    PriceList Response returns for:

    • Create a PriceList
    • Get a PriceList
    • Update a PriceList

    • data      object

      Common Price List properties.

    • meta      object

      Response metadata.

    example

    {
    "data": {
    "id": 2,
    "name": "BigCommerce",
    "date_created": "2022-02-26T17:37:01Z",
    "date_modified": "2022-09-17T18:45:17Z",
    "active": false
    },
    "meta": {}
    }

    Delete a Price List

    DELETE /pricelists/{price_list_id}

    Request

    Deletes a Price List. All associated price records are also removed. Limits

    • Limit of 1 concurrent request.

    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.
    • price_list_id in path - integer
      required

      The ID of the Price List requested.

    example

    curl --request DELETE \
    --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/pricelists/[price_list_id]' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'X-Auth-Token: {{token}}'

    Response

    Action has been enacted and no further information is to be supplied. null is returned.

    See something you can improve? Edit this file on GitHub

    Did you find what you were looking for?
    Get Prices (Batch)Get All Price Lists