Cascading price lists

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

This reduces the need to duplicate entire price lists for minor pricing variations. You can maintain a shared base price list and assign it as a fallback layer 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. The fallback layer, if one is assigned and active
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 the layer. If neither contains a price, it resolves to the catalog price.

Each price list supports a maximum of one layer.

Configure layers via the API

The layers field on a price list defines a fallback price list. Each item in the array is an object with a price_list_id.

Create a price list with a layer

Include layers in the POST request body.

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

Update layers on an existing price list

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

1
PUT https://api.bigcommerce.com/stores/{store_hash}/v3/pricelists/{price_list_id}
2
X-Auth-Token: <YOUR_ACCESS_TOKEN>
3
Content-Type: application/json
4
5
{
6
  "layers": [
7
    { "price_list_id": 5 }
8
  ]
9
}

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

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

Constraints

• Maximum one layer — each price list supports a single fallback layer.
• 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.