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

# Price List API

Price lists allow you to populate different versions of catalog pricing and assign them to different [Customer Groups](/developer/api-reference/rest/admin/management/customers/v2). The prices are specified exclusively at the variant level. If an active price list doesn't contain prices for a variant, then the catalog pricing will be used.

You can assign a price list to a specific sales channel, customer group, or customer group on a specific sales channel, using price list assignments in the [Price List Assignment API](/developer/api-reference/rest/admin/management/price-lists/price-lists-assignments/create-price-list-assignments). You can also associate a price list to a customer group in the Control Panel or the [Customer Groups API](/developer/api-reference/rest/admin/management/customers/v2). Price list assignments combined with a customer group assignment allows you to better target the signed-in customers shopping on that channel.

Price lists will provide overridden price values to the Stencil storefront. You can further customize the final price displayed within the Stencil template. For more information, see [Theme Objects](/developer/docs/storefront/stencil/themes/context/object-reference/schemas).

### OAuth scopes

The following OAuth Scopes are required:

* [Products](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes)

## Price list definitions

* A **price list** is a collection of price records. Price records make up a price list.
* A **price record** is a price override for a particular variant. At a minimum, it contains a variant ID, a price, and a currency.

**`Price Record`**

```js title="Price Record" showLineNumbers={false}
{
  "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. If you use a [transactional currency](/developer/docs/admin/store-configuration/currencies#display-vs-transactional), the customer group or channel will use price records in that currency. If a multi-currency price list is unavailable, BigCommerce auto converts the catalog price. The customer group or channel uses price records in the default currency and performs a currency conversion for [display-only currencies](/developer/docs/admin/store-configuration/currencies#display-vs-transactional).

**`Example request: Get all price lists`**

```http title="Example request: Get all price lists" showLineNumbers={false}
GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/pricelists
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json

{}
```

## Price list assignments

The price list assignment assigns a price list to a specific sales channel. This association lets you define custom pricing for shoppers on storefront channels, but doesn't affect pricing in different omnichannel environments, such as Facebook, Amazon, Instagram, etc.

See [Channels, Sites, and Routes](/developer/api-reference/rest/admin/management/channels) for further documentation.

**`Example request: Create a price list assignment`**

```http title="Example request: Create a price list assignment" showLineNumbers={false}
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/pricelists/assignments
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json

[
  {
    "customer_group_id": 3,
    "price_list_id": 2,
    "channel_id": 1
  }
]
```

## Price lists assigned to customer groups

**`Example request: Assign a price list to a customer group`**

```http title="Example request: Assign a price list to a customer group" showLineNumbers={false}
PUT https://api.bigcommerce.com/stores/{{store_hash}}/v2/customer_groups/{{customer_group_id}}
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json

[
  {
    "id": 1,
    "name": "VIP Price List",
    "is_default": false,
    "category_access": {
      "type": "all"
    },
    "discount_rules": [
      {
        "type": "price_list",
        "price_list_id": 2
      }
    ]
  }
]
```

Under `discount_rules` the `type` is set to `price_list`. The `price_list_id` is 1, which is the id of the price list assigned to the group.

## Price list notes

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

* Deleting a `Price Record` defaults the bulk price back to product bulk pricing.

* `Price Lists Records` accepts bulk upsert. You can only do one [Bulk upsert](/developer/api-reference/rest/admin/management/price-lists/price-lists-records/upsert-price-list-records) at a time. Running more than one in parallel on the **same store** will cause a `429` error, and the request will fail.

## Related resources

### Endpoints

* [Get Price List Collection](/developer/api-reference/rest/admin/management/price-lists/get-price-lists)

### Webhooks

There are webhooks available for Price Lists assignments. The price list assignment webhook fires when a price list assignment is assigned, reassigned, or unassigned. Note that since Price Lists directly relate to products, neither product nor SKU webhooks will fire for corresponding changes, such as pricing.

* [Price list assignments](/developer/docs/integrations/webhooks/event-reference/channel-events#price-list-assignments)
* [Products](/developer/docs/integrations/webhooks/event-reference#webhook-events_products)
* [SKU](/developer/docs/integrations/webhooks/event-reference#webhook-events_sku)