> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# 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.

**`Create a price list with fallback layers`**

```http title="Create a price list with fallback layers"
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:

| `layers` value   | Effect                       |
| ---------------- | ---------------------------- |
| Omitted          | No change to existing layers |
| `[]`             | Removes all layers           |
| Array with items | Replaces existing layers     |

**`Add a fallback layer to an existing price list`**

```http title="Add a fallback layer to an existing price list"
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 }
  ]
}
```

**`Remove all layers from a price list`**

```http title="Remove all layers from a price list"
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](/developer/api-reference/rest/admin/management/price-lists/create-price-list).

## 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.