What is a Price List?

A Price List allows you to populate different versions of catalog pricing and assign them to different Customer Groups. The prices are specified exclusively at the variant level.

If an active Price List does not contain prices for a variant then the Catalog pricing will be used. The association of a Price List to a Customer Group can be done either via the Control Panel or using the Customer Groups API.

Price Lists will provide overridden price values to the Stencil storefront. Final price display can be further customized within the Stencil template. See the Price Object in Stencil for further documentation.


  • Price List : A collection of price records. Price Records make up a price list.

  • Price Record: A price override for a particular variant - minimally, this is a variant ID, price, and currency.

		"variant_id": 3121,
		"price": 10.0,
		"sale_price": 8.0,
		"retail_price": 12.0,
		"map_price": 6.0,
		"currency": "EUR"
  • PriceRecordBatch: A way to update several Price Records in a Price List at once. Using this bulk upsert endpoint, you can upsert up to 1000 Price Records in a single API call.

  • Currency: A Price List can contain records for multiple currencies. At this time, only price records that match the store’s default currency will be used to determine storefront and in-cart prices. Although BigCommerce supports a storefront currency selection, this is not currently integrated with Price Lists and will merely convert prices from the store’s default currency for display convenience.

Example Price List
    "variant_id": 3121,
    "price": 10,
    "sale_price": 8,
    "retail_price": 12,
    "map_price": 6,
    "currency": "USD"
    "variant_id": 3255,
    "price": 11,
    "sale_price": 9,
    "retail_price": 13,
    "map_price": 7,
    "currency": "USD"
    "variant_id": 3256,
    "price": 12,
    "sale_price": 10,
    "retail_price": 14,
    "map_price": 8,
    "currency": "USD"
    "variant_id": 3257,
    "price": 13,
    "sale_price": 11,
    "retail_price": 15,
    "map_price": 9,
    "currency": "USD"
    "variant_id": 3258,
    "price": 14,
    "sale_price": 12,
    "retail_price": 16,
    "map_price": 10,
    "currency": "USD"
Example Price List assigned to a customer group
    "id": 1,
    "name": "Price List Test",
    "is_default": false,
    "category_access": {
      "type": "all"
    "discount_rules": [
        "type": "price_list",
        "price_list_id": 1

Under discount_rules the type is set to price_list and the price_list_id is 1. Which is the id of the price list the group has been assigned to.


  • Bulk Pricing Tiers may additionally be associated with a Price Record to indicate different pricing as the quantity in 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.

OAuth Scopes

Webhooks Available

There are no direct webhooks available for Price Lists. Since Price Lists directly relate to products, webhooks related to products will fire for corresponding changes such as pricing.

Related Endpoints

Object Properties


Common Price List properties.


The unique name of the Price List. Required in /POST.

example: Wholesale

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

example: true