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

Response

Body

object | application/json

Get All PriceLists.

  • data
    array[object]

  • meta
    object

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

example

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

    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

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

      Filter by id. Accepts multiple comma-separated values.

    • name in query - string

      Filter items by name.

    example

    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

      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

      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

        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

        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

        Response

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

        Did you find what you were looking for?