Pricing

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.

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"
})

# Product price is always in the response
curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
  -H 'Authorization: Bearer pk_xxx'

# With variants
curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants' \
  -H 'Authorization: Bearer pk_xxx'

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:

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

Price Rules

Price Rules define conditions that must be met for a Price List to apply. Spree includes five built-in rule types:

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:

Pricing Context

When resolving prices, Spree considers the full context of the request:

The Store API automatically builds this context from the request headers (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.

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:

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

curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=prior_price' \
  -H 'X-Spree-API-Key: pk_xxx'

The response includes a prior_price object when expanded:

{
  "id": "prod_xxx",
  "name": "Spree Tote",
  "price": { "amount": "15.99", "currency": "USD", "display_amount": "$15.99" },
  "prior_price": {
    "amount": "9.99",
    "amount_in_cents": 999,
    "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):

# config/initializers/spree.rb
Spree.config do |config|
  config.track_price_history = false
  config.price_history_retention_days = 30 # default
end

Price history retention defaults to 30 days and can be configured globally. A Rake task is provided for cleanup:

bundle exec rake spree:price_history:prune

Seeding Existing Prices

After enabling price history on an existing store, seed the current prices as a baseline:

bundle exec rake spree:price_history:seed

Related Documentation

• 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