Thanks for being patient while we implement your feedback to improve the developer experience.

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

  • Price Lists cannot be assigned to a customer group that has customer group discounts -- the customer group discounts must be deleted first.
  • Bulk pricing Tiers may 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 in 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 no webhooks available for Price Lists. Since Price Lists directly relate to products, product webhooks will trigger 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 - required

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 query - integer

    Filter items by ID.

  • 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
  • name:like in query - array
  • 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: xxxxxxxxxxxxxxxxx'

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,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

Create a Price List

POST /pricelists

Request

Creates a Price List.

Required Fields

  • name

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

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

    • 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 - required

    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 query - integer

      Filter items by ID.

    • 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: xxxxxxxxxxxxxxxxx'

    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 - required

      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.

      • id in query - integer

        Filter items by ID.

      • 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=2022-06-15

      • page in query - integer

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

      • limit in query - integer

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

      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: xxxxxxxxxxxxxxxxx'

      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 - required

      Parameters

      • store_hash in path - string
      • 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

      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

        • 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 - required

        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: xxxxxxxxxxxxxxxxx'

        Response

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