Overview
Spree’s pricing system supports both simple single-currency pricing and advanced multi-currency, rule-based pricing through Price Lists. Every Variant 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 context.
| 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 |
If a product doesn’t have a price in the selected currency, it won’t appear in Store API responses by default.
Fetching Prices via API
The Store API returns the resolved price (including Price List rules) for the current currency and market context:
// Product price is included by default
const product = await client.products.get('spree-tote')
console.log(product.price) // "15.99" — resolved for current currency
console.log(product.original_price) // "19.99" — compare-at 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) // "15.99"
console.log(variant.original_price) // "19.99"
})
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 (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:
- Price List priority — Price Lists are ordered by position; higher priority lists are checked first
- Status — only
active or scheduled Price Lists are considered
- Date range — the current time must fall within
starts_at and ends_at (if set)
- 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) |
Price Rules
Price Rules define conditions that must be met for a Price List to apply. Spree includes five built-in rule types:
| Rule | Description | Use Case |
|---|
| Market Rule | Matches based on the current Market | Regional pricing across markets |
| Zone Rule | Matches based on the customer’s geographic zone | Country or state-level pricing |
| User Rule | Matches specific customer accounts | VIP customers, wholesale accounts |
| Customer Group Rule | Matches members of customer groups | Loyalty tiers, membership pricing |
| Volume Rule | Matches based on quantity purchased | Bulk discounts, tiered pricing |
Market Rule
The recommended approach for regional pricing when using Markets. 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.
Zone Rule
Applies based on the customer’s geographic zone. Useful for regional or country-specific pricing when not using Markets.
User Rule
Limits the Price List to specific customer accounts. Useful for VIP customers, employee pricing, or wholesale accounts.
Customer Group Rule
Applies to members of specific customer groups. Useful for wholesale tiers, loyalty programs, or membership-based pricing.
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 |
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 for market-based rules |
| Zone | Customer’s address | The geographic zone for zone-based rules |
| Customer | JWT authentication | The logged-in customer for user-based rules |
| Quantity | Cart line item | The quantity for volume-based rules |
| Date | Current time | For time-based Price List scheduling |
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.
Price resolution results are cached for 15 minutes. Different context combinations are cached separately.
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.
- Products — Products, Variants, and base prices
- Markets — Geographic regions with currency and locale
- Taxes — Tax categories, tax rates, and zones
- Promotions — Discount-based pricing via promotion rules
