Cascading price lists

Cascading price lists let you layer up to five fallback price lists onto a primary price list. When a price record is not found in the primary price list, the system checks each fallback layer in order before resolving to the catalog price.

This reduces the need to duplicate entire price lists for minor pricing variations. You can maintain shared base price lists and assign them as fallback layers across multiple primary lists.

How price resolution works

When priority order is enabled, the price resolution sequence is:

1. The primary price list assigned to the shopper’s context (channel and customer group)
2. Each fallback layer, in the order listed in layers, skipping any that are inactive
3. The catalog price

If the primary price list has a price record for the requested variant, that price is used. If not, the system checks each layer in order and uses the first price record it finds. If no layer contains a price, it resolves to the catalog price.

Each price list supports a maximum of five layers.

Configure layers via the API

The layers field on a price list defines an ordered list of up to five fallback price lists. Each item in the array is an object with a price_list_id, and layers are evaluated in array order.

Create a price list with layers

Include layers in the POST request body.

POST https://api.bigcommerce.com/stores/{store_hash}/v3/pricelists
X-Auth-Token: <YOUR_ACCESS_TOKEN>
Content-Type: application/json
{
  "name": "VIP Pricing",
  "active": true,
  "layers": [
    { "price_list_id": 5 },
    { "price_list_id": 8 }
  ]
}

Update layers on an existing price list

Send a PUT request with layers in the request body. The behavior depends on the value provided:

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/pricelists/{price_list_id}
X-Auth-Token: <YOUR_ACCESS_TOKEN>
Content-Type: application/json
{
  "layers": [
    { "price_list_id": 5 }
  ]
}

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/pricelists/{price_list_id}
X-Auth-Token: <YOUR_ACCESS_TOKEN>
Content-Type: application/json
{
  "layers": []
}

For full API details, see the Price Lists API reference.

Constraints

• Maximum five layers: each price list supports up to five fallback layers, evaluated in the order listed.
• Type compatibility: Inclusive and exclusive price lists can only layer with like types. Attempting to layer mismatched types returns a 422 error.
• Tax type changes: You cannot change prices_entered_with_tax on a price list that is part of a layer relationship, as either the primary or the layer. Remove all layer relationships first, then make the change.
• Inactive layers: An inactive price list can be assigned as a layer but is skipped during price resolution. The primary price list must be active for any of its layers to be evaluated.