Brands
Brand Images
Brand Metafields
Category Metafields
Category Images
Products
Product Bulk Pricing Rules
Product Complex Rules
Product Custom Fields
Product Images
Product Metafields
Product Modifiers
Product Modifier Values
Product Modifier Images
Product Options
Product Option Values
Product Reviews
Product Variants
Product Variants Metafields
Product Videos
Summary
Variants
Category
Webhooks
Catalog
Price Lists
Price Lists Assignments
Price Lists Records

Price Lists

  • Version: 3.0
  • Host: api.bigcommerce.com/stores/{$$.env.store_hash}/v3
  • Protocols: https
  • Accepts: application/json
  • Responds With: application/json

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.

The association of a Price List to a Customer Group can be done either via the Control Panel or using the Customer Groups API.

Additionally, Price List Assignments can be created to assign Price Lists to a specific Channel. Price lists assigned to a channel apply to all shoppers on that channel, unless there is a more specific assignment.

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.

To learn more about Price Lists, see here.

OAuth Scopes

UI Name Permission Parameter
Products modify store_v2_products
Products read-only store_v2_products_read_only

For more information on OAuth Scopes, see: Authentication.

Authentication

Requests can be authenticated by sending a client_id and access_token via X-Auth-Client and X-Auth-Token HTTP headers:

GET /stores/{$$.env.store_hash}/v3/catalog/summary
host: api.bigcommerce.com
Accept: application/json
X-Auth-Client: {client_id}
X-Auth-Token: {access_token}
Header Parameter Description
X-Auth-Client client_id Obtained by creating an API account or installing an app in a BigCommerce control panel.
X-Auth-Token access_token Obtained by creating an API account or installing an app in a BigCommerce control panel.

For more information on Authenticating BigCommerce APIs, see: Authentication.

Available Endpoints

Resource / Endpoint Description
Price List Records Create and manage price list records
Price Lists Create and manage catalog pricing variations
Price List Assignments Assign price lists to Channels

Price List Assignment Order of Operations

The Price List Assignment Pricing Order of Operations is as follows:

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

Note: Price Lists cannot be assigned to a customer group that has custom group discounts – the customer group discounts must be deleted first.

Usage Notes

  • Price Lists cannot be assigned to a customer group that has custom 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 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. Only one Bulk upsert can done at a time. Running more than one in parallel on the same store will cause a 429 error and the request will fail.

Related Endpoints

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.