Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Pricing
description: Prices, Price Lists, Price Rules, and the Pricing Context — Spree's flexible pricing engine for regional, wholesale, volume, and market-based pricing.
---
## Overview
Spree's pricing system supports both simple single-currency pricing and advanced multi-currency, rule-based pricing through Price Lists. Every [Variant](/developer/core-concepts/products#variants) can have multiple prices — a base price per currency, plus additional prices from Price Lists that apply conditionally based on rules like geography, customer segment, or quantity.
## Prices
Each variant has one or more `Price` records — one per currency. The API automatically returns the correct price based on the current currency and [Market](/developer/core-concepts/markets) context. See [monetary amounts](/api-reference/store-api/monetary-amounts) for how money fields (decimal, cents, and display string) are formatted across the API.
| Attribute | Description | Example |
|-----------|-------------|---------|
| `amount` | Current selling price | `"99.90"` |
| `compare_at_amount` | Original/compare price for strikethrough display | `"129.90"` |
| `currency` | ISO 4217 currency code | `USD` |
<Warning>
If a product doesn't have a price in the selected currency, it won't appear in Store API responses by default.
</Warning>
### Fetching Prices via API
The Store API returns the resolved price (including Price List rules) for the current currency and market context:
<CodeGroup>
```typescript Store SDK
// Product price is included by default
const product = await client.products.get('spree-tote')
console.log(product.price.amount) // "15.99" — resolved for current currency
console.log(product.price.compare_at_amount) // "19.99" — compare-at/strikethrough price (if set)
// Each variant has its own price
const detailed = await client.products.get('spree-tote', {
expand: ['variants'],
})
detailed.variants?.forEach(variant => {
console.log(variant.price.amount) // "15.99"
console.log(variant.price.compare_at_amount) // "19.99"
})
```
```typescript Admin SDK
const product = await adminClient.products.get('prod_86Rf07xd4z', {
expand: ['variants'],
})
```
```bash cURL
# Product price is always in the response
curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
-H 'X-Spree-API-Key: pk_xxx'
# With variants
curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants' \
-H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
### Setting Prices via the Admin API
Base prices are set per variant per currency. Use the [Admin API](/api-reference/admin-api/introduction) — via the [Admin SDK](/developer/sdk/admin/quickstart) — to set them individually or in bulk (`bulk_upsert` matches on variant + currency):
<CodeGroup>
```typescript Admin SDK
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://store.example.com',
secretKey: 'sk_xxx',
})
// Set / change one variant's price in a currency
await client.prices.create({ variant_id: 'variant_xxx', currency: 'USD', amount: '15.99' })
// Upsert many at once
await client.prices.bulkUpsert({
prices: [
{ variant_id: 'variant_xxx', currency: 'USD', amount: '15.99' },
{ variant_id: 'variant_xxx', currency: 'EUR', amount: '14.99' },
],
})
```
```bash CLI
spree api post /prices/bulk_upsert -d '{
"prices": [
{ "variant_id": "variant_xxx", "currency": "USD", "amount": "15.99" },
{ "variant_id": "variant_xxx", "currency": "EUR", "amount": "14.99" }
]
}'
```
</CodeGroup>
`?expand=variants.prices` returns every price a variant has, Price List amounts
and quantity breaks included; each row carries its `price_list_id`, which is
`null` for a base price. Writing `prices` back on a variant sets **base prices
only** — a currency left out is removed — so filter the rows you read before
sending them back. To write what a Price List charges, use `/prices`.
## Price Lists
Price Lists allow you to create different pricing strategies based on various conditions. This enables advanced pricing scenarios like:
- **Market-based pricing** — different prices for different [Markets](/developer/core-concepts/markets) (e.g., North America vs Europe)
- **Regional pricing** — different prices for different geographic zones
- **Wholesale/B2B pricing** — special prices for business customers
- **Volume discounts** — tiered pricing based on quantity purchased
- **Promotional pricing** — time-limited special offers
- **VIP customer pricing** — exclusive prices for specific customers
### How Price Lists Work
When a customer views a product, Spree's pricing resolver determines which price to use:
1. **Price List priority** — Price Lists are ordered by position; higher priority lists are checked first
2. **Status** — only `active` or `scheduled` Price Lists are considered
3. **Date range** — the current time must fall within `starts_at` and `ends_at` (if set)
4. **Price Rules** — all configured rules must match (or any, depending on `match_policy`)
If no applicable Price List is found, the base price is used.
### Price List Attributes
| Attribute | Description |
|-----------|-------------|
| `name` | Human-readable name for the Price List |
| `status` | `draft`, `active`, `scheduled`, or `inactive` |
| `starts_at` | Optional start date when the Price List becomes applicable |
| `ends_at` | Optional end date when the Price List stops being applicable |
| `match_policy` | How rules are evaluated: `all` (every rule must match) or `any` (at least one) |
| `position` | Priority order (lower numbers = higher priority) |
### Creating a Price List via the Admin API
Rules and per-variant price overrides ride on the create/update payload. Each rule is a `{ type, preferences }` draft (see [Price Rules](#price-rules) below):
<CodeGroup>
```typescript Admin SDK
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://store.example.com',
secretKey: 'sk_xxx',
})
const priceList = await client.priceLists.create({
name: 'EU wholesale',
match_policy: 'all',
rules: [
{ type: 'market_rule', preferences: { market_ids: ['mkt_xxx'] } },
],
prices: [
{ variant_id: 'variant_xxx', currency: 'EUR', amount: '19.99' },
],
})
// Price Lists are draft until activated
await client.priceLists.activate(priceList.id)
```
```bash CLI
spree api post /price_lists -d '{
"name": "EU wholesale",
"match_policy": "all",
"prices": [{ "variant_id": "variant_xxx", "currency": "EUR", "amount": "19.99" }]
}'
spree api patch /price_lists/pl_xxx/activate
```
</CodeGroup>
## Price Rules
Price Rules define conditions that must be met for a Price List to apply. Rules describe the *context* of a purchase — where, through what, how much:
| Rule | Description | Use Case |
|------|-------------|----------|
| **Market Rule** | Matches based on the current [Market](/developer/core-concepts/markets) | Regional pricing across markets |
| **Channel Rule** | Matches based on the [Channel](/developer/core-concepts/channels) the customer is buying through | App-only or in-store pricing |
| **Volume Rule** | Matches based on quantity purchased | Bulk discounts, tiered pricing |
*Who* gets a price list is not a rule — it's a [Catalog](/developer/core-concepts/catalogs): attach the list to a catalog assigned to the customer groups or companies it's for.
<Note>
The **User Rule** and **Customer Group Rule** kinds still work and are not going away, but they're no longer offered when adding a rule — targeting an audience through a catalog is the one way to do it now. Nothing needs migrating; rules you already have keep matching exactly as before.
</Note>
### Market Rule
Regional pricing. Applies the Price List when the customer is in one of the specified markets.
**Example:** Price a product at $29.99 in North America and €24.99 in Europe, rather than relying on exchange rate conversion.
### Channel Rule
Applies when the customer is buying through a particular sales channel — a discount that exists only in the mobile app, or a price that only applies at a retail till. For new setups, prefer giving the channel a default [Catalog](/developer/core-concepts/catalogs) that owns the price list — that is where channel-wide commercial terms live going forward.
### Volume Rule
Applies based on quantity purchased. Supports `min_quantity` and `max_quantity` to create tiered pricing:
| Tier | Quantity | Price |
|------|----------|-------|
| Base | 1–9 | $10.00 |
| Bulk Tier 1 | 10–49 | $8.50 |
| Bulk Tier 2 | 50+ | $7.00 |
<Info>
Custom Price Rules can be created for specialized pricing logic. See the [Customization Quickstart](/developer/customization/quickstart) for details.
</Info>
## Pricing Context
When resolving prices, Spree considers the full context of the request:
| Context | Source | Description |
|---------|--------|-------------|
| Currency | Market or request header | The currency to price in |
| Market | Customer's country | The [Market](/developer/core-concepts/markets) for market-based rules |
| Channel | The API credential in use | The [Channel](/developer/core-concepts/channels) for channel-based rules |
| Customer | Authentication | The signed-in customer, for resolving their [Catalogs](/developer/core-concepts/catalogs) |
| Quantity | Cart line item | The quantity for volume-based rules |
| Date | Current time | For time-based Price List scheduling |
The Store API automatically builds this context from the [request headers](/api-reference/store-api/localization) (`X-Spree-Currency`, `X-Spree-Country`) and authentication state. You don't need to construct it manually — just make API requests and the correct price is resolved.
<Info>
Price resolution runs per request — there is no in-process caching of resolved prices. The Store API instead relies on HTTP/CDN caching, with `Vary` headers keyed on every request header that changes the price — `X-Spree-Country` (market), `X-Spree-Currency`, `X-Spree-Locale`, `X-Spree-Channel`, the publishable key and `Authorization` — so each combination is cached separately at the edge. See [HTTP caching](/developer/deployment/caching#http-caching-of-store-api-responses).
</Info>
## Time-Based Pricing
Price Lists support scheduling through `starts_at` and `ends_at` attributes. Scheduled Price Lists automatically become applicable when the current time falls within their date range — no manual activation needed.
**Example:** A Black Friday sale Price List with `starts_at: 2025-11-28 00:00` and `ends_at: 2025-11-28 23:59` will automatically activate and deactivate.
## Managing Price Lists
Price Lists are managed in the Admin Panel under **Products → Price Lists**, or via the Admin API.
Each Price List contains prices for specific variants and currencies. Products can be added to a Price List, and individual variant prices set within it.
## Price History (EU Omnibus Directive)
Spree automatically records price changes for EU Omnibus Directive compliance. When a product goes on sale, EU regulations require displaying the lowest price in the preceding 30 days alongside the discounted price.
### How It Works
Every time a base price amount changes, a `PriceHistory` record is created automatically. Price list prices are not tracked — only the base price visible to all customers.
### Fetching Prior Price via API
The prior price is available as an expandable field on product and variant endpoints:
<CodeGroup>
```typescript Store SDK
const product = await client.products.get('spree-tote', {
expand: ['prior_price'],
})
if (product.prior_price) {
console.log(product.prior_price.amount) // "9.99"
console.log(product.prior_price.display_amount) // "$9.99"
console.log(product.prior_price.currency) // "USD"
console.log(product.prior_price.recorded_at) // "2026-03-10T..."
}
```
```typescript Admin SDK
const product = await adminClient.products.get('prod_86Rf07xd4z', {
expand: ['prior_price'],
})
```
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=prior_price' \
-H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
The response includes a `prior_price` object when expanded:
```json Response
{
"id": "prod_xxx",
"name": "Spree Tote",
"price": { "amount": "15.99", "currency": "USD", "display_amount": "$15.99" },
"prior_price": {
"amount": "9.99",
"currency": "USD",
"display_amount": "$9.99",
"recorded_at": "2026-03-10T14:30:00Z"
}
}
```
### Configuration
Price history tracking is enabled by default. To disable it (e.g., for non-EU stores):
<CodeGroup>
```typescript Admin SDK
await client.store.update({ track_price_history: false })
```
```bash cURL
curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
-H 'X-Spree-API-Key: sk_xxx' \
-H 'Content-Type: application/json' \
-d '{ "track_price_history": false }'
```
</CodeGroup>
Retention defaults to 30 days, set per store with the `price_history_retention_days` preference. A Rake task prunes anything older:
<CodeGroup>
```bash Spree CLI (Docker)
spree task price_history:prune
```
```bash Without Spree CLI
bundle exec rake spree:price_history:prune
```
</CodeGroup>
### Seeding Existing Prices
After enabling price history on an existing store, seed the current prices as a baseline:
<CodeGroup>
```bash Spree CLI (Docker)
spree task price_history:seed
```
```bash Without Spree CLI
bundle exec rake spree:price_history:seed
```
</CodeGroup>
## Related Documentation
- [Products](/developer/core-concepts/products) — Products, Variants, and base prices
- [Store SDK: Products](/developer/sdk/store/products) — Fetching product and variant prices with the Store SDK
- [Markets](/developer/core-concepts/markets) — Geographic regions with currency and locale
- [Taxes](/developer/core-concepts/taxes) — Tax categories, tax rates, and zones
- [Promotions](/developer/core-concepts/promotions) — Discount-based pricing via promotion rules