Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Added coumentation about Markets + more documentation around Pricing

Damian Legawiec032abc621ac9
diff --git a/docs/developer/core-concepts/architecture.mdx b/docs/developer/core-concepts/architecture.mdx
index b54b79a99d..20871ffbc4 100644
--- a/docs/developer/core-concepts/architecture.mdx
+++ b/docs/developer/core-concepts/architecture.mdx
@@ -117,7 +117,7 @@ erDiagram
## Multi-Store Architecture
-Spree supports multiple [Stores](/developer/core-concepts/stores) from a single installation. Each Store can have:
+Spree can work in [Multi-Store model](/developer/multi-store/quickstart) from a single installation. Each Store can have:
- Its own domain and branding
- Different currencies and locales
@@ -162,22 +162,17 @@ Spree is distributed as a set of Ruby gems (packages). Most users run Spree in *
| Package | Purpose |
|---------|---------|
-| `spree_core` | Models, services, and business logic |
-| `spree_api` | [Storefront API](/api-reference/storefront), [Platform API](/api-reference/platform), and [Webhooks](/developer/core-concepts/webhooks) |
+| `spree` | Models, services, business logic, API and Webhooks |
**Optional packages:**
| Package | Purpose |
|---------|---------|
| `spree_admin` | Admin dashboard for managing your store |
-| `spree_storefront` | Pre-built Rails storefront (not needed for headless setups) |
| `spree_emails` | Transactional email templates (order confirmation, shipping, etc.) |
-| `spree_page_builder` | Visual page builder for the Rails storefront |
-| `spree_sample` | Sample data (products, categories, etc.) for development and testing |
-| `spree_dev_tools` | Development and testing utilities for Spree applications and extensions |
<Info>
-For headless commerce, you only need `spree_core` and `spree_api`. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Storefront API.
+For headless commerce, you only need `spree` package. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Store API and SDK.
</Info>
## Related Documentation
@@ -186,4 +181,4 @@ For headless commerce, you only need `spree_core` and `spree_api`. Build your cu
- [Orders](/developer/core-concepts/orders) - Order lifecycle and state machine
- [Payments](/developer/core-concepts/payments) - Payment processing
- [Shipments](/developer/core-concepts/shipments) - Shipping and fulfillment
-- [Customization Quickstart](/developer/customization/quickstart) - How to extend Spree
\ No newline at end of file
+- [Customization Quickstart](/developer/customization/quickstart) - How to extend Spree
diff --git a/docs/developer/core-concepts/markets.mdx b/docs/developer/core-concepts/markets.mdx
new file mode 100644
index 0000000000..9b58f29fb9
--- /dev/null
+++ b/docs/developer/core-concepts/markets.mdx
@@ -0,0 +1,281 @@
+---
+title: Markets
+description: Multi-region commerce with Markets — bundle geography, currency, and locale into distinct selling regions within a single store.
+---
+
+<Info>
+Markets are coming with Spree 5.4 early March
+</Info>
+
+
+## Overview
+
+Markets let you segment a single [Store](/developer/core-concepts/stores) into distinct geographic regions, each with its own currency, locale, and set of countries. For example, an international store might define:
+
+- **North America** — USD, English, ships to US and Canada
+- **Europe** — EUR, German, ships to DE, FR, AT, NL
+- **United Kingdom** — GBP, English, ships to GB
+
+### Market Model Diagram
+
+```mermaid
+erDiagram
+ Store {
+ string name
+ string code
+ string url
+ boolean default
+ }
+
+ Market {
+ string name
+ string currency
+ string default_locale
+ string supported_locales
+ boolean tax_inclusive
+ boolean default
+ integer position
+ }
+
+ MarketCountry {
+ integer market_id
+ integer country_id
+ }
+
+ Country {
+ string iso
+ string name
+ }
+
+ Store ||--o{ Market : "has many"
+ Market ||--o{ MarketCountry : "has many"
+ MarketCountry }o--|| Country : "belongs to"
+```
+
+**Key relationships:**
+- A **Store** has many Markets — each market defines a selling region
+- A **Market** has many Countries through `MarketCountry` join records
+- A **Country** can belong to multiple Markets (across different stores)
+- Markets connect to the [Pricing](/developer/core-concepts/pricing) system via `Spree::Pricing::Context`
+
+## Market Attributes
+
+| Attribute | Description | Example Value |
+|---------------------|---------------------------------------------------------------------------------------------------|------------------------|
+| `name` | Human-readable name for the market. Must be unique per store. | `North America` |
+| `currency` | ISO 4217 currency code used for this market. | `USD` |
+| `default_locale` | Default locale/language for this market. | `en` |
+| `supported_locales` | Comma-separated list of additional locales supported by this market. | `en,fr` |
+| `tax_inclusive` | Whether prices in this market include tax. | `false` |
+| `default` | Whether this is the default market for the store. Only one market per store can be default. | `true` |
+| `position` | Sort order for market resolution priority. Lower numbers = higher priority. | `0` |
+| `deleted_at` | Soft-delete timestamp. Markets are never fully removed from the database. | `nil` |
+
+## Default Market
+
+`Spree::Current.market` provides per-request access to the current market. The fallback chain is:
+
+1. Explicitly set market (e.g., resolved from the customer's country)
+2. The store's default market (`store.default_market`)
+
+```ruby
+# Spree::Current.market is available in controllers, models, and services
+Spree::Current.market
+# => #<Spree::Market name: "North America", currency: "USD", ...>
+
+# Set it explicitly per-request
+Spree::Current.market = eu_market
+```
+
+The default market for a store is determined by the `default` flag, falling back to the first market by position:
+
+```ruby
+store.default_market
+# => #<Spree::Market name: "North America", default: true, ...>
+```
+
+## Currency and Locale
+
+When markets are configured, `Spree::Current.currency` derives from the current market rather than the store:
+
+```ruby
+# Fallback chain for currency:
+# 1. Explicitly set currency
+# 2. Current market's currency
+# 3. Store's default_currency
+Spree::Current.currency
+# => "USD" (from Spree::Current.market.currency)
+```
+
+Each market tracks its supported locales. Use `supported_locales_list` to get all available locales (always includes the `default_locale`):
+
+```ruby
+market = Spree::Market.find_by(name: 'Europe')
+market.supported_locales_list
+# => ["de", "en", "fr"]
+```
+
+The store aggregates currencies and locales from all its markets:
+
+```ruby
+store.supported_currencies_list
+# => [#<Money::Currency USD>, #<Money::Currency EUR>, #<Money::Currency GBP>]
+
+store.supported_locales_list
+# => ["de", "en", "fr"]
+```
+
+## Finding a Market by Country
+
+Resolve which market a country belongs to using the class method:
+
+```ruby
+country = Spree::Country.find_by(iso: 'DE')
+market = Spree::Market.for_country(country, store: current_store)
+# => #<Spree::Market name: "Europe", currency: "EUR", ...>
+```
+
+Or via the store convenience method:
+
+```ruby
+current_store.market_for_country(country)
+# => #<Spree::Market name: "Europe", currency: "EUR", ...>
+```
+
+When multiple markets contain the same country, the one with the lowest `position` is returned.
+
+## Countries Available for Checkout
+
+Markets determine which countries are available during checkout. The `countries_available_for_checkout` method on Store aggregates countries from all markets:
+
+```ruby
+current_store.countries_available_for_checkout
+# => [#<Spree::Country iso: "AT">, #<Spree::Country iso: "CA">, ...]
+```
+
+## Creating Markets
+
+```ruby
+# Create a market with countries
+na_market = current_store.markets.create!(
+ name: 'North America',
+ currency: 'USD',
+ default_locale: 'en',
+ countries: [usa, canada],
+ default: true
+)
+
+eu_market = current_store.markets.create!(
+ name: 'Europe',
+ currency: 'EUR',
+ default_locale: 'de',
+ supported_locales: 'de,en,fr',
+ tax_inclusive: true,
+ countries: [germany, france, austria, netherlands]
+)
+```
+
+<Info>
+When you run `rails db:seed`, Spree automatically creates a default market for each store
+</Info>
+
+## Store API
+
+The Store API provides endpoints for fetching markets and resolving which market applies to a given country. All endpoints require a publishable API key.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/v3/store/markets` | List all markets for the current store |
+| `GET` | `/api/v3/store/markets/:id` | Get a single market by prefixed ID |
+| `GET` | `/api/v3/store/markets/resolve?country=:iso` | Resolve which market a country belongs to |
+| `GET` | `/api/v3/store/markets/:market_id/countries` | List countries in a market |
+| `GET` | `/api/v3/store/markets/:market_id/countries/:iso` | Get a country with its states |
+
+<AccordionGroup>
+ <Accordion title="List Markets">
+
+ Returns all markets for the current store with their countries.
+
+ ```bash
+ curl -H "Authorization: Bearer spree_pk_xxx" \
+ https://example.com/api/v3/store/markets
+ ```
+
+ ```json
+ {
+ "data": [
+ {
+ "id": "mkt_k5nR8xLq",
+ "name": "North America",
+ "currency": "USD",
+ "default_locale": "en",
+ "supported_locales": ["en"],
+ "tax_inclusive": false,
+ "default": true,
+ "countries": [
+ { "iso": "US", "name": "United States" },
+ { "iso": "CA", "name": "Canada" }
+ ]
+ }
+ ]
+ }
+ ```
+
+ </Accordion>
+ <Accordion title="Resolve Market by Country">
+
+ Determine which market applies for a given country ISO code. Useful for auto-selecting the correct currency and locale when a customer's location is known.
+
+ ```bash
+ curl -H "Authorization: Bearer spree_pk_xxx" \
+ https://example.com/api/v3/store/markets/resolve?country=DE
+ ```
+
+ Returns the market object on success, or `404` if no market contains that country.
+
+ </Accordion>
+ <Accordion title="List Countries in a Market">
+
+ Returns countries belonging to a specific market. Useful for populating address dropdowns during checkout.
+
+ ```bash
+ curl -H "Authorization: Bearer spree_pk_xxx" \
+ https://example.com/api/v3/store/markets/mkt_k5nR8xLq/countries
+ ```
+
+ ```json
+ {
+ "data": [
+ { "iso": "CA", "iso3": "CAN", "name": "Canada", "states_required": true, "zipcode_required": true },
+ { "iso": "US", "iso3": "USA", "name": "United States", "states_required": true, "zipcode_required": true }
+ ]
+ }
+ ```
+
+ </Accordion>
+</AccordionGroup>
+
+## Pricing Integration
+
+Markets integrate with the [Pricing](/developer/core-concepts/pricing) system through the `Spree::Pricing::Context`. The current market is automatically included in pricing resolution, enabling market-specific Price Lists via the **Market Rule**.
+
+```ruby
+# Market is automatically part of the pricing context
+context = Spree::Pricing::Context.new(
+ variant: variant,
+ currency: 'EUR',
+ market: eu_market
+)
+
+# Price Lists with a Market Rule targeting eu_market will apply
+price = variant.price_for(context)
+```
+
+See [Pricing — Market Rule](/developer/core-concepts/pricing#price-rules) for details on configuring market-specific price lists.
+
+## Related Documentation
+
+- [Stores](/developer/core-concepts/stores) — Multi-store setup and configuration
+- [Pricing](/developer/core-concepts/pricing) — Price Lists, Price Rules, and the Pricing Context
+- [Addresses](/developer/core-concepts/addresses) — Countries, States, and Zones
+- [Internationalization](/developer/core-concepts/i18n) — Locales, currencies, and translations
diff --git a/docs/developer/core-concepts/pricing.mdx b/docs/developer/core-concepts/pricing.mdx
new file mode 100644
index 0000000000..f0ccdde4d0
--- /dev/null
+++ b/docs/developer/core-concepts/pricing.mdx
@@ -0,0 +1,527 @@
+---
+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
+
+`Price` objects track a price for a particular currency and variant combination. For instance, a [Variant](/developer/core-concepts/products#variants) may be available for $15 (`15 USD`) and €7 (`7 Euro`).
+
+`Price` object contains 3 important attributes:
+
+| Attribute | Description | Example Value |
+|-------------------|-----------------------------------------------------------------------------------------------|-----------------------|
+| `amount` | The current selling price of the variant in the specified currency. | `99.90` |
+| `compare_at_amount` | The recommended retail price of the variant in the specified currency. This can be used to display crossed out prices in the storefront. | `129.90` |
+| `currency` | The ISO code for the currency in which the `amount` and `compare_at_amount` are denominated. | `USD` |
+
+<Warning>
+If a product doesn't have a price in the selected currency it won't show up in the Storefront and Storefront API by default.
+</Warning>
+
+To fetch a list of currencies that given product is available in, call `prices` to get a list of related `Price` objects:
+
+```ruby
+product.prices
+=> [#<Spree::Price id: 2 ...]
+```
+
+To find a list of currencies that Variant is available in, call `prices` to get a list of related `Price` objects:
+
+```ruby
+product.default_variant.prices
+=> [#<Spree::Price id: 2 ...]
+```
+
+To find Product price in a selected currency via [ISO symbol](https://www.iban.com/currency-codes):
+
+```ruby
+product.price_in('EUR')
+=> #<Spree::Price id: 232, variant_id: 232, amount: 0.8499e2, currency: "EUR", deleted_at: nil, created_at: "2021-08-16 19:41:55.888522000 +0000", updated_at: "2021-08-16 19:41:55.888522000 +0000", compare_at_amount: nil, preferences: nil>
+```
+
+<Note>
+If there's no price set for requested currency this will return a new Price object with the currency set to the requested currency. It will not be a persisted object.
+</Note>
+
+To find Variant's price in a selected currency:
+
+```ruby
+product.default_variant.price_in('EUR')
+=> #<Spree::Price id: 232, variant_id: 232, amount: 0.8499e2, currency: "EUR", deleted_at: nil, created_at: "2021-08-16 19:41:55.888522000 +0000", updated_at: "2021-08-16 19:41:55.888522000 +0000", compare_at_amount: nil, preferences: nil>
+```
+
+There are also other helpful methods available such as:
+
+<AccordionGroup>
+ <Accordion title="Getting amount (number)">
+
+ ```ruby
+ product.default_variant.amount_in('EUR')
+ => 0.8499e2
+ ```
+
+ </Accordion>
+ <Accordion title="Getting amount (string)">
+
+ ```ruby
+ product.default_variant.amount_in('EUR').to_s
+ => "84.99"
+ ```
+
+ </Accordion>
+ <Accordion title="Displaying price with currency symbol">
+
+ ```ruby
+ product.price_in('EUR').display_amount.to_s
+ => "€84.99"
+ ```
+
+ </Accordion>
+</AccordionGroup>
+
+<Info>
+Spree behind the scenes uses [Ruby Money gem](https://github.com/RubyMoney/money) with some [additional](https://github.com/spree/spree/blob/main/core/app/models/concerns/spree/display_money.rb) [tweaks](https://github.com/spree/spree/blob/main/core/lib/spree/money.rb).
+</Info>
+
+## Price Lists
+
+<Info>
+Price Lists are available as of Spree 5.2.
+</Info>
+
+Price Lists allow you to create different pricing strategies for your products based on various conditions such as [markets](/developer/core-concepts/markets), customer zones, specific users, or order quantities. 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 users
+
+### How Price Lists Work
+
+Each Price List contains a collection of prices for specific variants and currencies. When a customer views a product or adds it to their cart, Spree's pricing resolver determines which price to use based on:
+
+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 (price without a Price List) is used.
+
+### Price List Attributes
+
+| Attribute | Description |
+|-----------------|-------------------------------------------------------------------------------------------------|
+| `name` | Human-readable name for the Price List |
+| `status` | Current status: `draft`, `active`, `scheduled`, or `inactive` |
+| `starts_at` | Optional start date/time when the Price List becomes applicable |
+| `ends_at` | Optional end date/time when the Price List stops being applicable |
+| `match_policy` | How rules are evaluated: `all` (every rule must match) or `any` (at least one rule must match) |
+| `position` | Priority order for evaluation (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:
+
+<AccordionGroup>
+ <Accordion title="Market Rule">
+
+ Applies the Price List based on the current [Market](/developer/core-concepts/markets). This is the recommended approach for regional pricing when using Markets.
+
+ ```ruby
+ # Example: Create a Price List for the European market
+ price_list = Spree::PriceList.create!(
+ name: 'EU Market Pricing',
+ store: current_store,
+ status: 'active',
+ match_policy: 'all'
+ )
+
+ eu_market = Spree::Market.find_by!(name: 'Europe')
+ price_list.price_rules.create!(
+ type: 'Spree::PriceRules::MarketRule',
+ preferences: { market_ids: [eu_market.id] }
+ )
+ ```
+
+ If `market_ids` is empty, the rule matches any market. If the pricing context has no market, the rule does not match.
+
+ </Accordion>
+ <Accordion title="Zone Rule">
+
+ Applies the Price List based on the customer's tax/shipping zone. Useful for regional or country-specific pricing when not using Markets.
+
+ ```ruby
+ # Example: Create a Price List for EU customers
+ price_list = Spree::PriceList.create!(
+ name: 'EU Pricing',
+ store: current_store,
+ status: 'active',
+ match_policy: 'all'
+ )
+
+ eu_zone = Spree::Zone.find_by!(name: 'EU')
+ price_list.price_rules.create!(
+ type: 'Spree::PriceRules::ZoneRule',
+ preferences: { zone_ids: [eu_zone.id] }
+ )
+ ```
+
+ </Accordion>
+ <Accordion title="User Rule">
+
+ Applies the Price List to specific users. Useful for VIP customers, wholesale accounts, or B2B pricing.
+
+ ```ruby
+ # Example: Create a VIP Price List
+ price_list = Spree::PriceList.create!(
+ name: 'VIP Customers',
+ store: current_store,
+ status: 'active',
+ match_policy: 'all'
+ )
+
+ # Find users tagged with 'VIP'
+ vip_user_ids = Spree.user_class.tagged_with('VIP').pluck(:id)
+
+ price_list.price_rules.create!(
+ type: 'Spree::PriceRules::UserRule',
+ preferences: { user_ids: vip_user_ids }
+ )
+ ```
+
+ </Accordion>
+ <Accordion title="Customer Group Rule">
+
+ Applies the Price List to members of specific customer groups. Useful for wholesale tiers, loyalty programs, or membership-based pricing.
+
+ ```ruby
+ # Example: Create a wholesale Price List
+ price_list = Spree::PriceList.create!(
+ name: 'Wholesale Pricing',
+ store: current_store,
+ status: 'active',
+ match_policy: 'all'
+ )
+
+ wholesale_group = Spree::CustomerGroup.find_by!(name: 'Wholesale')
+ price_list.price_rules.create!(
+ type: 'Spree::PriceRules::CustomerGroupRule',
+ preferences: { customer_group_ids: [wholesale_group.id] }
+ )
+ ```
+
+ </Accordion>
+ <Accordion title="Volume Rule">
+
+ Applies the Price List based on quantity purchased. Useful for bulk discounts or tiered pricing.
+
+ ```ruby
+ # Example: Create volume-based pricing tiers
+ # Tier 1: 10-49 units
+ tier1 = Spree::PriceList.create!(
+ name: 'Bulk Tier 1 (10-49)',
+ store: current_store,
+ status: 'active',
+ position: 2
+ )
+ tier1.price_rules.create!(
+ type: 'Spree::PriceRules::VolumeRule',
+ preferences: { min_quantity: 10, max_quantity: 49 }
+ )
+
+ # Tier 2: 50+ units (higher priority)
+ tier2 = Spree::PriceList.create!(
+ name: 'Bulk Tier 2 (50+)',
+ store: current_store,
+ status: 'active',
+ position: 1
+ )
+ tier2.price_rules.create!(
+ type: 'Spree::PriceRules::VolumeRule',
+ preferences: { min_quantity: 50, max_quantity: nil }
+ )
+ ```
+
+ </Accordion>
+</AccordionGroup>
+
+### Creating Custom Price Rules
+
+You can create custom Price Rules by subclassing `Spree::PriceRule`:
+
+```ruby
+# app/models/spree/price_rules/membership_rule.rb
+module Spree
+ module PriceRules
+ class MembershipRule < Spree::PriceRule
+ preference :membership_levels, :array, default: []
+
+ def applicable?(context)
+ return false unless context.user
+ return true if preferred_membership_levels.empty?
+
+ preferred_membership_levels.include?(context.user.membership_level)
+ end
+
+ def self.description
+ 'Apply pricing based on membership level'
+ end
+ end
+ end
+end
+```
+
+Then register it in your initializer:
+
+```ruby
+# config/initializers/spree.rb
+Rails.application.config.after_initialize do
+ Rails.application.config.spree.pricing.rules << Spree::PriceRules::MembershipRule
+end
+```
+
+## Pricing Context
+
+The `Spree::Pricing::Context` object carries all the information needed to resolve the correct price. It encapsulates the current pricing scenario and is used by the `Spree::Pricing::Resolver` to find the best applicable price.
+
+### Context Attributes
+
+| Attribute | Type | Required | Default | Description |
+|------------|---------------------|----------|---------------------|-------------------------------------------------------------------------------------------------|
+| `variant` | `Spree::Variant` | Yes | - | The variant for which to resolve the price |
+| `currency` | `String` | Yes | - | ISO 4217 currency code (e.g., `'USD'`, `'EUR'`) |
+| `store` | `Spree::Store` | No | `Spree::Current.store` | The store context; Price Lists are scoped to stores |
+| `zone` | `Spree::Zone` | No | `Spree::Current.zone` | The tax/shipping zone for zone-based pricing rules. Falls back to `Spree::Zone.default_tax` if not set. |
+| `market` | `Spree::Market` | No | `Spree::Current.market` | The current [Market](/developer/core-concepts/markets) for market-based pricing rules. Falls back to the store's default market. |
+| `user` | User class | No | `nil` | The current user; used by User Rules for customer-specific pricing |
+| `quantity` | `Integer` | No | `nil` | The quantity being purchased; used by Volume Rules for tiered pricing |
+| `date` | `Time` | No | `Time.current` | The date/time for price resolution; used to check Price List date ranges |
+| `order` | `Spree::Order` | No | `nil` | The current order; provides additional context for price resolution |
+
+### Understanding the Market and Zone Attributes
+
+The `market` attribute is the primary way to scope pricing geographically. [Markets](/developer/core-concepts/markets) bundle a set of countries with a currency and locale, making them the natural unit for regional pricing.
+
+**How market is resolved:**
+- `Spree::Current.market` is set per-request, typically based on the customer's country
+- Falls back to the store's default market if not explicitly set
+- The Market Rule on Price Lists uses this attribute to match market-specific prices
+
+```ruby
+# Market is automatically available in the pricing context
+Spree::Current.market # => #<Spree::Market name: "Europe", currency: "EUR">
+
+context = Spree::Pricing::Context.new(variant: variant, currency: 'EUR')
+context.market # => Spree::Current.market
+```
+
+<Note>
+The `zone` attribute is still available for zone-based pricing via the Zone Rule. Zones are primarily used for tax and shipping calculations, while Markets are the recommended approach for regional pricing. Both can be used together — for example, a Market Rule for currency-based pricing and a Zone Rule for state-level tax-inclusive pricing.
+</Note>
+
+### Creating a Context
+
+There are several ways to create a pricing context:
+
+<AccordionGroup>
+ <Accordion title="From an Order (recommended)">
+
+ The most common approach during checkout. Automatically extracts all relevant information from the order:
+
+ ```ruby
+ context = Spree::Pricing::Context.from_order(variant, order)
+
+ # This is equivalent to:
+ context = Spree::Pricing::Context.new(
+ variant: variant,
+ currency: order.currency,
+ store: order.store,
+ zone: order.tax_zone || order.store.checkout_zone,
+ user: order.user,
+ quantity: order.line_items.find_by(variant: variant)&.quantity,
+ order: order
+ )
+ ```
+
+ </Accordion>
+ <Accordion title="From Currency (simple)">
+
+ For basic price lookups when you only need currency-based pricing:
+
+ ```ruby
+ context = Spree::Pricing::Context.from_currency(variant, 'USD')
+
+ # This is equivalent to:
+ context = Spree::Pricing::Context.new(
+ variant: variant,
+ currency: 'USD'
+ )
+ ```
+
+ </Accordion>
+ <Accordion title="Manual Construction">
+
+ For full control over all pricing parameters:
+
+ ```ruby
+ context = Spree::Pricing::Context.new(
+ variant: variant,
+ currency: 'EUR',
+ store: Spree::Store.find_by!(code: 'eu-store'),
+ zone: Spree::Zone.find_by!(name: 'EU'),
+ market: Spree::Market.find_by!(name: 'Europe'),
+ user: current_user,
+ quantity: 10,
+ date: 1.week.from_now # Preview future pricing
+ )
+ ```
+
+ </Accordion>
+</AccordionGroup>
+
+### Resolving the Price
+
+Once you have a context, use the `Spree::Pricing::Resolver` to find the best price:
+
+```ruby
+resolver = Spree::Pricing::Resolver.new(context)
+price = resolver.resolve # Returns a Spree::Price object
+
+# The resolver:
+# 1. Finds all applicable Price Lists (active/scheduled, within date range)
+# 2. Filters by Price Rules (market, zone, user, quantity, etc.)
+# 3. Returns the first matching price (by Price List position)
+# 4. Falls back to the base price if no Price List applies
+```
+
+<Note>
+Price resolution results are cached for 15 minutes using the context's cache key. The cache key includes all context attributes (including market), so different scenarios are cached separately.
+</Note>
+
+## Getting Prices: `price_for` vs `price_in`
+
+Spree provides two methods for fetching variant prices. Understanding when to use each is important for correct pricing behavior.
+
+### `price_for` (Recommended)
+
+The `price_for` method resolves prices using the full Price List system. It considers all applicable Price Lists, rules, and returns the best matching price. **This is the recommended method for most use cases.**
+
+```ruby
+# Using a Pricing Context object
+context = Spree::Pricing::Context.from_order(variant, order)
+price = variant.price_for(context)
+
+# Using an options hash (context is built automatically)
+price = variant.price_for(
+ currency: 'USD',
+ store: Spree::Current.store,
+ zone: order.tax_zone,
+ user: current_user,
+ quantity: 5
+)
+
+# Display the resolved price
+price.display_amount.to_s # => "$89.99"
+```
+
+**Use `price_for` when:**
+- Displaying prices to customers in the storefront
+- Calculating line item prices during checkout
+- You need market-based, zone-based, user-based, or volume-based pricing
+- You want prices from active Price Lists to apply
+
+### `price_in` (Base Prices Only)
+
+The `price_in` method returns only the **base price** (prices without a Price List) for a given currency. It bypasses the Price List system entirely.
+
+```ruby
+# Get the base price in USD
+base_price = variant.price_in('USD')
+base_price.amount # => 99.99
+```
+
+**Use `price_in` when:**
+- You specifically need the base price, ignoring all Price Lists
+- Managing prices in the admin interface
+- Importing/exporting base pricing data
+- Backward compatibility with pre-5.2 code
+
+<Warning>
+`price_in` is maintained for backward compatibility. For customer-facing pricing, always use `price_for` to ensure Price Lists are applied correctly.
+</Warning>
+
+### Comparison
+
+| Method | Price Lists | Rules Applied | Use Case |
+|------------|-------------|---------------|-----------------------------------|
+| `price_for`| Yes | Yes | Storefront, checkout, customer-facing |
+| `price_in` | No | No | Admin, base price management |
+
+```ruby
+# Example: Same variant, different results
+variant = Spree::Variant.find(1)
+
+# Base price (no Price Lists)
+variant.price_in('USD').amount # => 100.00
+
+# Resolved price (with VIP Price List applied)
+context = Spree::Pricing::Context.new(
+ variant: variant,
+ currency: 'USD',
+ user: vip_customer
+)
+variant.price_for(context).amount # => 80.00 (20% VIP discount)
+```
+
+## Managing Price List Products
+
+Products can be added to a Price List, which creates placeholder prices for all variants:
+
+```ruby
+price_list = Spree::PriceList.find(1)
+
+# Add products to the Price List
+price_list.add_products([product1.id, product2.id])
+
+# Update prices for the Price List
+price_list.prices.each do |price|
+ price.update(amount: calculate_special_price(price.variant))
+end
+
+# Remove products from the Price List
+price_list.remove_products([product1.id])
+```
+
+## Time-Based Pricing
+
+Price Lists support scheduling through `starts_at` and `ends_at` attributes:
+
+```ruby
+# Create a Black Friday sale
+black_friday = Spree::PriceList.create!(
+ name: 'Black Friday 2025',
+ store: current_store,
+ status: 'scheduled',
+ starts_at: Time.zone.parse('2025-11-28 00:00'),
+ ends_at: Time.zone.parse('2025-11-28 23:59'),
+ position: 1 # Highest priority
+)
+```
+
+<Note>
+Scheduled Price Lists automatically become applicable when the current time falls within their date range. They don't need to be manually activated.
+</Note>
+
+## Related Documentation
+
+- [Products](/developer/core-concepts/products) — Products, Variants, and base prices
+- [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
diff --git a/docs/developer/core-concepts/products.mdx b/docs/developer/core-concepts/products.mdx
index 7bcf8ae3ba..4b229f4cca 100644
--- a/docs/developer/core-concepts/products.mdx
+++ b/docs/developer/core-concepts/products.mdx
@@ -253,456 +253,9 @@ As of version 4.6, product property `value` fields are translatable.
`Price` objects track a price for a particular currency and variant combination. For instance, a [Variant](#variants) may be available for $15 (`15 USD`) and €7 (`7 Euro`).
-`Price` object contains 3 important attributes:
+Each variant can have multiple prices — a base price per currency, plus additional prices from Price Lists that apply conditionally based on rules like [market](/developer/core-concepts/markets), geography, customer segment, or quantity.
-| Attribute | Description | Example Value |
-|-------------------|-----------------------------------------------------------------------------------------------|-----------------------|
-| `amount` | The current selling price of the variant in the specified currency. | `99.90` |
-| `compare_at_amount` | The recommended retail price of the variant in the specified currency. This can be used to display crossed out prices in the storefront. | `129.90` |
-| `currency` | The ISO code for the currency in which the `amount` and `compare_at_amount` are denominated. | `USD` |
-
-<Warning>
-If a product doesn't have a price in the selected currency it won't show up in the Storefront and Storefront API by default.
-</Warning>
-
-To fetch a list of currencies that given product is available in, call `prices` to get a list of related `Price` objects:
-
-```ruby
-product.prices
-=> [#<Spree::Price id: 2 ...]
-```
-
-To find a list of currencies that Variant is available in, call `prices` to get a list of related `Price` objects:
-
-```ruby
-product.default_variant.prices
-=> [#<Spree::Price id: 2 ...]
-```
-
-To find Product price in a selected currency via [ISO symbol](https://www.iban.com/currency-codes):
-
-```ruby
-product.price_in('EUR')
-=> #<Spree::Price id: 232, variant_id: 232, amount: 0.8499e2, currency: "EUR", deleted_at: nil, created_at: "2021-08-16 19:41:55.888522000 +0000", updated_at: "2021-08-16 19:41:55.888522000 +0000", compare_at_amount: nil, preferences: nil>
-```
-
-<Note>
-If there's no price set for requested currency this will return a new Price object with the currency set to the requested currency. It will not be a persisted object.
-</Note>
-
-To find Variant's price in a selected currency:
-
-```ruby
-product.default_variant.price_in('EUR')
-=> #<Spree::Price id: 232, variant_id: 232, amount: 0.8499e2, currency: "EUR", deleted_at: nil, created_at: "2021-08-16 19:41:55.888522000 +0000", updated_at: "2021-08-16 19:41:55.888522000 +0000", compare_at_amount: nil, preferences: nil>
-```
-
-There are also other helpful methods available such as:
-
-<AccordionGroup>
- <Accordion title="Getting amount (number)">
-
- ```ruby
- product.default_variant.amount_in('EUR')
- => 0.8499e2
- ```
-
- </Accordion>
- <Accordion title="Getting amount (string)">
-
- ```ruby
- product.default_variant.amount_in('EUR').to_s
- => "84.99"
- ```
-
- </Accordion>
- <Accordion title="Displaying price with currency symbol">
-
- ```ruby
- product.price_in('EUR').display_amount.to_s
- => "€84.99"
- ```
-
- </Accordion>
-</AccordionGroup>
-
-<Info>
-Spree behind the scenes uses [Ruby Money gem](https://github.com/RubyMoney/money) with some [additional](https://github.com/spree/spree/blob/main/core/app/models/concerns/spree/display_money.rb) [tweaks](https://github.com/spree/spree/blob/main/core/lib/spree/money.rb).
-</Info>
-
-### Price Lists
-
-<Info>
-Price Lists are available as of Spree 5.2.
-</Info>
-
-Price Lists allow you to create different pricing strategies for your products based on various conditions such as customer zones, specific users, or order quantities. This enables advanced pricing scenarios like:
-
-- **Regional pricing** - Different prices for different geographic regions
-- **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 users
-
-#### How Price Lists Work
-
-Each Price List contains a collection of prices for specific variants and currencies. When a customer views a product or adds it to their cart, Spree's pricing resolver determines which price to use based on:
-
-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 (price without a Price List) is used.
-
-#### Price List Attributes
-
-| Attribute | Description |
-|-----------------|-------------------------------------------------------------------------------------------------|
-| `name` | Human-readable name for the Price List |
-| `status` | Current status: `draft`, `active`, `scheduled`, or `inactive` |
-| `starts_at` | Optional start date/time when the Price List becomes applicable |
-| `ends_at` | Optional end date/time when the Price List stops being applicable |
-| `match_policy` | How rules are evaluated: `all` (every rule must match) or `any` (at least one rule must match) |
-| `position` | Priority order for evaluation (lower numbers = higher priority) |
-
-#### Price Rules
-
-Price Rules define conditions that must be met for a Price List to apply. Spree includes three built-in rule types:
-
-<AccordionGroup>
- <Accordion title="Zone Rule">
-
- Applies the Price List based on the customer's tax/shipping zone. Useful for regional or country-specific pricing.
-
- ```ruby
- # Example: Create a Price List for EU customers
- price_list = Spree::PriceList.create!(
- name: 'EU Pricing',
- store: current_store,
- status: 'active',
- match_policy: 'all'
- )
-
- eu_zone = Spree::Zone.find_by!(name: 'EU')
- price_list.price_rules.create!(
- type: 'Spree::PriceRules::ZoneRule',
- preferences: { zone_ids: [eu_zone.id] }
- )
- ```
-
- </Accordion>
- <Accordion title="User Rule">
-
- Applies the Price List to specific users. Useful for VIP customers, wholesale accounts, or B2B pricing.
-
- ```ruby
- # Example: Create a VIP Price List
- price_list = Spree::PriceList.create!(
- name: 'VIP Customers',
- store: current_store,
- status: 'active',
- match_policy: 'all'
- )
-
- # Find users tagged with 'VIP'
- vip_user_ids = Spree.user_class.tagged_with('VIP').pluck(:id)
-
- price_list.price_rules.create!(
- type: 'Spree::PriceRules::UserRule',
- preferences: { user_ids: vip_user_ids }
- )
- ```
-
- </Accordion>
- <Accordion title="Volume Rule">
-
- Applies the Price List based on quantity purchased. Useful for bulk discounts or tiered pricing.
-
- ```ruby
- # Example: Create volume-based pricing tiers
- # Tier 1: 10-49 units
- tier1 = Spree::PriceList.create!(
- name: 'Bulk Tier 1 (10-49)',
- store: current_store,
- status: 'active',
- position: 2
- )
- tier1.price_rules.create!(
- type: 'Spree::PriceRules::VolumeRule',
- preferences: { min_quantity: 10, max_quantity: 49 }
- )
-
- # Tier 2: 50+ units (higher priority)
- tier2 = Spree::PriceList.create!(
- name: 'Bulk Tier 2 (50+)',
- store: current_store,
- status: 'active',
- position: 1
- )
- tier2.price_rules.create!(
- type: 'Spree::PriceRules::VolumeRule',
- preferences: { min_quantity: 50, max_quantity: nil }
- )
- ```
-
- </Accordion>
-</AccordionGroup>
-
-#### Creating Custom Price Rules
-
-You can create custom Price Rules by subclassing `Spree::PriceRule`:
-
-```ruby
-# app/models/spree/price_rules/membership_rule.rb
-module Spree
- module PriceRules
- class MembershipRule < Spree::PriceRule
- preference :membership_levels, :array, default: []
-
- def applicable?(context)
- return false unless context.user
- return true if preferred_membership_levels.empty?
-
- preferred_membership_levels.include?(context.user.membership_level)
- end
-
- def self.description
- 'Apply pricing based on membership level'
- end
- end
- end
-end
-```
-
-#### Pricing Context
-
-The `Spree::Pricing::Context` object carries all the information needed to resolve the correct price. It encapsulates the current pricing scenario and is used by the `Spree::Pricing::Resolver` to find the best applicable price.
-
-##### Context Attributes
-
-| Attribute | Type | Required | Default | Description |
-|------------|---------------------|----------|---------------------|-------------------------------------------------------------------------------------------------|
-| `variant` | `Spree::Variant` | Yes | - | The variant for which to resolve the price |
-| `currency` | `String` | Yes | - | ISO 4217 currency code (e.g., `'USD'`, `'EUR'`) |
-| `store` | `Spree::Store` | No | `Spree::Current.store` | The store context; Price Lists are scoped to stores |
-| `zone` | `Spree::Zone` | No | `Spree::Current.zone` | The tax/shipping zone for zone-based pricing rules (see below). Falls back to `Spree::Zone.default_tax` if not set. |
-| `user` | User class | No | `nil` | The current user; used by User Rules for customer-specific pricing |
-| `quantity` | `Integer` | No | `nil` | The quantity being purchased; used by Volume Rules for tiered pricing |
-| `date` | `Time` | No | `Time.current` | The date/time for price resolution; used to check Price List date ranges |
-| `order` | `Spree::Order` | No | `nil` | The current order; provides additional context for price resolution |
-
-##### Understanding the Zone Attribute
-
-The `zone` attribute represents the geographic zone used for zone-based pricing. Zones in Spree can be based on countries or states and are typically used for tax and shipping calculations.
-
-**Where zones come from:**
-- During checkout, the zone is determined by the customer's shipping or billing address
-- The `order.tax_zone` method returns the applicable tax zone based on the order's addresses
-- `Spree::Current.zone` holds the current request's zone (set automatically by controllers)
-- Falls back to `Spree::Zone.default_tax` if no zone is explicitly set
-
-**How zone is resolved:**
-```ruby
-# Spree::Current.zone is automatically set in controllers from the current order:
-Spree::Current.zone # => order.tax_zone || Spree::Zone.default_tax
-
-# When creating a context, zone defaults to Spree::Current.zone
-context = Spree::Pricing::Context.new(variant: variant, currency: 'USD')
-context.zone # => Spree::Current.zone
-```
-
-##### Creating a Context
-
-There are several ways to create a pricing context:
-
-<AccordionGroup>
- <Accordion title="From an Order (recommended)">
-
- The most common approach during checkout. Automatically extracts all relevant information from the order:
-
- ```ruby
- context = Spree::Pricing::Context.from_order(variant, order)
-
- # This is equivalent to:
- context = Spree::Pricing::Context.new(
- variant: variant,
- currency: order.currency,
- store: order.store,
- zone: order.tax_zone || order.store.checkout_zone,
- user: order.user,
- quantity: order.line_items.find_by(variant: variant)&.quantity,
- order: order
- )
- ```
-
- </Accordion>
- <Accordion title="From Currency (simple)">
-
- For basic price lookups when you only need currency-based pricing:
-
- ```ruby
- context = Spree::Pricing::Context.from_currency(variant, 'USD')
-
- # This is equivalent to:
- context = Spree::Pricing::Context.new(
- variant: variant,
- currency: 'USD'
- )
- ```
-
- </Accordion>
- <Accordion title="Manual Construction">
-
- For full control over all pricing parameters:
-
- ```ruby
- context = Spree::Pricing::Context.new(
- variant: variant,
- currency: 'EUR',
- store: Spree::Store.find_by!(code: 'eu-store'),
- zone: Spree::Zone.find_by!(name: 'EU'),
- user: current_user,
- quantity: 10,
- date: 1.week.from_now # Preview future pricing
- )
- ```
-
- </Accordion>
-</AccordionGroup>
-
-##### Resolving the Price
-
-Once you have a context, use the `Spree::Pricing::Resolver` to find the best price:
-
-```ruby
-resolver = Spree::Pricing::Resolver.new(context)
-price = resolver.resolve # Returns a Spree::Price object
-
-# The resolver:
-# 1. Finds all applicable Price Lists (active/scheduled, within date range)
-# 2. Filters by Price Rules (zone, user, quantity, etc.)
-# 3. Returns the first matching price (by Price List position)
-# 4. Falls back to the base price if no Price List applies
-```
-
-<Note>
-Price resolution results are cached for 15 minutes using the context's cache key. The cache key includes all context attributes, so different scenarios are cached separately.
-</Note>
-
-#### Getting Prices: `price_for` vs `price_in`
-
-Spree provides two methods for fetching variant prices. Understanding when to use each is important for correct pricing behavior.
-
-##### `price_for` (Recommended)
-
-The `price_for` method resolves prices using the full Price List system. It considers all applicable Price Lists, rules, and returns the best matching price. **This is the recommended method for most use cases.**
-
-```ruby
-# Using a Pricing Context object
-context = Spree::Pricing::Context.from_order(variant, order)
-price = variant.price_for(context)
-
-# Using an options hash (context is built automatically)
-price = variant.price_for(
- currency: 'USD',
- store: Spree::Current.store,
- zone: order.tax_zone,
- user: current_user,
- quantity: 5
-)
-
-# Display the resolved price
-price.display_amount.to_s # => "$89.99"
-```
-
-**Use `price_for` when:**
-- Displaying prices to customers in the storefront
-- Calculating line item prices during checkout
-- You need zone-based, user-based, or volume-based pricing
-- You want prices from active Price Lists to apply
-
-##### `price_in` (Base Prices Only)
-
-The `price_in` method returns only the **base price** (prices without a Price List) for a given currency. It bypasses the Price List system entirely.
-
-```ruby
-# Get the base price in USD
-base_price = variant.price_in('USD')
-base_price.amount # => 99.99
-```
-
-**Use `price_in` when:**
-- You specifically need the base price, ignoring all Price Lists
-- Managing prices in the admin interface
-- Importing/exporting base pricing data
-- Backward compatibility with pre-5.2 code
-
-<Warning>
-`price_in` is maintained for backward compatibility. For customer-facing pricing, always use `price_for` to ensure Price Lists are applied correctly.
-</Warning>
-
-##### Comparison
-
-| Method | Price Lists | Rules Applied | Use Case |
-|------------|-------------|---------------|-----------------------------------|
-| `price_for`| Yes | Yes | Storefront, checkout, customer-facing |
-| `price_in` | No | No | Admin, base price management |
-
-```ruby
-# Example: Same variant, different results
-variant = Spree::Variant.find(1)
-
-# Base price (no Price Lists)
-variant.price_in('USD').amount # => 100.00
-
-# Resolved price (with VIP Price List applied)
-context = Spree::Pricing::Context.new(
- variant: variant,
- currency: 'USD',
- user: vip_customer
-)
-variant.price_for(context).amount # => 80.00 (20% VIP discount)
-```
-
-#### Managing Price List Products
-
-Products can be added to a Price List, which creates placeholder prices for all variants:
-
-```ruby
-price_list = Spree::PriceList.find(1)
-
-# Add products to the Price List
-price_list.add_products([product1.id, product2.id])
-
-# Update prices for the Price List
-price_list.prices.each do |price|
- price.update(amount: calculate_special_price(price.variant))
-end
-
-# Remove products from the Price List
-price_list.remove_products([product1.id])
-```
-
-#### Time-Based Pricing
-
-Price Lists support scheduling through `starts_at` and `ends_at` attributes:
-
-```ruby
-# Create a Black Friday sale
-black_friday = Spree::PriceList.create!(
- name: 'Black Friday 2025',
- store: current_store,
- status: 'scheduled',
- starts_at: Time.zone.parse('2025-11-28 00:00'),
- ends_at: Time.zone.parse('2025-11-28 23:59'),
- position: 1 # Highest priority
-)
-```
-
-<Note>
-Scheduled Price Lists automatically become applicable when the current time falls within their date range. They don't need to be manually activated.
-</Note>
+For full details on Prices, Price Lists, Price Rules, and the Pricing Context, see the dedicated [Pricing](/developer/core-concepts/pricing) guide.
## Prototypes
diff --git a/docs/developer/core-concepts/stores.mdx b/docs/developer/core-concepts/stores.mdx
index 08383b0c27..d7cc66fdba 100644
--- a/docs/developer/core-concepts/stores.mdx
+++ b/docs/developer/core-concepts/stores.mdx
@@ -4,15 +4,7 @@ title: Stores
## Overview
-The `Spree::Store` model is the center of the Spree ecosystem. Each Spree installation can have multiple Stores. Each Store operates on a different domain or subdomain, eg.
-
-* Store A, `us.example.com`
-* Store B, `eu.example.com`
-* Store C, `another-brand.com`
-
-<Frame type="glass" caption="Spree multi-store setup">
-![](/images/mulit_store_978x2.png)
-</Frame>
+The `Spree::Store` model is the center of the Spree ecosystem.
### Store Model Diagram
@@ -22,10 +14,6 @@ erDiagram
string name
string code
string url
- string default_currency
- string supported_currencies
- string default_locale
- string supported_locales
boolean default
string mail_from_address
string customer_support_email
@@ -61,6 +49,14 @@ erDiagram
integer position
}
+ Market {
+ string name
+ string currency
+ string default_locale
+ boolean default
+ }
+
+ Store ||--o{ Market : "has many"
Store ||--o{ Order : "has many"
Store }o--o{ Product : "has many"
Store }o--o{ PaymentMethod : "has many"
@@ -74,6 +70,7 @@ erDiagram
**Key relationships:**
- **Store** is the central model - all commerce data is scoped to a store
+- Each store has one or more [Markets](/developer/core-concepts/markets) that define geographic selling regions with their own currency and locale
- Each store has its own [Orders](/developer/core-concepts/orders), [Products](/developer/core-concepts/products), [Payment Methods](/developer/core-concepts/payments), and [Shipping Methods](/developer/core-concepts/shipments)
- Stores can have different currencies, locales, and configurations
- Content (Menus, CMS Pages) and [Webhooks](/developer/core-concepts/webhooks) are also store-specific
@@ -88,93 +85,29 @@ erDiagram
| `meta_keywords` | Relevant keywords associated with the store for SEO. | fashion, electronics, books |
| `seo_title` | A custom SEO title for the store. | Shop the Best Deals Online - Spree Store |
| `mail_from_address` | The email address used for sending emails from the store. | [email protected] |
-| `default_currency` | The default currency for prices within the store. | `USD` |
| `default` | Indicates if the store is the default store. | `true` |
-| `supported_currencies` | A list of currencies supported by the store, separated by commas. | `USD, EUR, GBP` |
-| `supported_locales` | A list of locales supported by the store, separated by commas. | `en, fr, de` |
| `customer_support_email` | The email address for customer support inquiries. | [email protected] |
| `facebook` | The store's Facebook page URL. | spree |
| `twitter` | The store's Twitter handle. | @spreecommerce |
| `instagram` | The store's Instagram profile URL. | https://www.instagram.com/spree |
-| `default_locale` | The default locale/language for the store. | `en` |
| `description` | A detailed description of the store. | Your one-stop shop for everything you need. |
| `address` | The physical address of the store. | 123 Example St, San Francisco, CA |
| `contact_phone` | The contact phone number for the store. | `+1 234-567-8900` |
| `new_order_notifications_email` | The email address to send notifications of new orders. | [email protected] |
-## Current Store
-
-Spree will try to determine the current store based on the current URL. If the URL does not match any of the stores in the database, Spree will fall back to the default store.
-
-All Spree controllers or any other controllers that include [Spree::Core::ControllerHelpers::Store](https://github.com/spree/spree/blob/main/core/lib/spree/core/controller_helpers/store.rb) have access to the `current_store` method which returns the `Store` matching the current URL.
-
-All parts of Spree (API v1, API v2, Storefront, Admin Panel) have this implemented. This method is also available in views and JSON serializers.
-
-<Info>
-Under the hood `current_store` calls [Spree::Stores::FindCurrent.new(url: url).execute](https://github.com/spree/spree/blob/main/core/app/finders/spree/stores/find_current.rb).
-
-This logic can be easily overwritten by setting
-
-```ruby
-Spree::Dependencies.current_store_finder = 'MyStoreFinderClass'
-```
-
-in `config/initializers/spree.rb` file
-</Info>
-
-## Default Store
-
-If the system cannot find any Store that matches the current URL it will fall back to the Default Store.
-
-You can set the default Store in `Admin Panel -> Configurations -> Store` or via Rails console:
-
-```ruby
-Spree::Store.find(2).update(default: true)
-```
-
-To get the default store in your code or rails console type:
-
-```ruby
-Spree::Store.default
-```
-
-## Localization and Currency
-
-Each Store can have multiple locales and currencies. This configuration is stored in Store model attributes:
-
-| Attribute | Description | Example(s) |
-|-----------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------|
-| `default_currency` | This is the default currency that will be pre-selected when visiting the store the first time. | `USD` |
-| `supported_currencies`| If there is more than one supported currency, visitors will be able to choose which currency they browse in. | `USD`, `CAD`, `EUR` |
-| `default_locale` | This is the default locale/language which will be pre-selected when visiting the store the first time. | `en` |
-| `supported_locales` | If there is more than one supported locale, visitors can choose which locale they browse in. Locales are available upon installing [Spree I18n](https://github.com/spree-contrib/spree_i18n). | `en`, `fr`, `de` |
+### Accessing Store in code
-### Translations
+To access the current store you can use `current_store` in controllers or `Spree::Store.current` in models/services/jobs.
-As of version 4.6, the `Store` resource allows for translating many of its fields. Translations are enabled when selecting more than one locale in `supported_locales`. The following fields are translatable:
+## Markets
-* `name`
-* `meta_description`
-* `meta_keywords`
-* `seo_title`
-* `facebook`
-* `twitter`
-* `instagram`
-* `customer_support_email`
-* `description`
-* `address`
-* `contact_phone`
-* `new_order_notifications_email`
+[Markets](/developer/core-concepts/markets) let you segment your store into geographic regions, each with its own currency, locale, and set of countries. For example, a single store can have:
-Read more about how resource translations work in [Internationalization](i18n#resource-translations).
+- **North America** — USD, English, ships to US and Canada
+- **Europe** — EUR, German, ships to DE, FR, AT, NL
+- **United Kingdom** — GBP, English, ships to GB
-## Checkout configuration
-
-Each Store can be configured to ship to only selected countries. This is achieved via the `checkout_zone_id` attribute which holds the ID of the selected [Zone record](shipments#zones).
-
-Available Shipping Methods on the Checkout are determined based on the [Zone and Shipping Methods configuration](shipments).
-
-This will also have an effect on what [Shipping / Billing Addresses](/developer/core-concepts/addresses) user can add/ select during Checkout. Only Addresses from Countries or States available in the selected Zone can be used and will be visible in the User's Address Book.
+For full details on creating and managing markets, see the [Markets](/developer/core-concepts/markets) guide.
## Store resources
@@ -182,6 +115,7 @@ Each Store can have its own resources. For example, a Store can have its own Pro
| Resource | Relationship |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| [**Market**](markets) | One Store has many Markets, each defining a geographic region with its own currency and locale |
| [**Order**](orders) | One Order belongs to one Store |
| [**Product**](products) | One Product can be associated with many Store(s), you can pick and choose in which Store(s) each Product will be available |
| [**Payment Method**](payments) | One Payment Method can be associated with many Store(s), you can select in which Stores given Payment Method will be available on Checkout |
@@ -189,8 +123,6 @@ Each Store can have its own resources. For example, a Store can have its own Pro
| [**Promotion**](promotions) | One Promotion can be associated with multiple Stores |
| **Store Credit** | One Store Credit belongs to and can be used in one Store |
-## Custom Domains
-
-Spree supports managing custom domains for Stores. This is useful for multi-store setups where each store has its own domain.
+## Multi-store setup
-In the Admin Panel, you can manage custom domains for each Store in the **Settings -> Domains** page.
\ No newline at end of file
+To enable multiple stores please follow our [Multi Store guide](/developer/multi-store/quickstart)
diff --git a/docs/developer/multi-store/quickstart.mdx b/docs/developer/multi-store/quickstart.mdx
index 2d57a9ae12..b6364a80f2 100644
--- a/docs/developer/multi-store/quickstart.mdx
+++ b/docs/developer/multi-store/quickstart.mdx
@@ -3,7 +3,17 @@ title: Multi-Store Spree Commerce
sidebarTitle: Quickstart
---
-Spree out of the box supports multiple stores on the same instance. This is useful for running multiple brands or multiple language versions of the same brand on the same instance.
+To enable multiple stores, you will need to add the `spree_multi_store` gem to your project via:
+
+```bash
+bundle add spree_multi_store
+```
+
+<Info>
+Spree Multi-Store is licensed under the [AGPL v3 License](https://opensource.org/licenses/AGPL-3.0).
+
+If you would like to use it in a commercial application, please [contact us](https://spreecommerce.org/get-started/) to obtain a commercial license.
+</Info>
<Frame type="glass" caption="Spree multi-store setup">
![](/images/mulit_store_978x2.png)
@@ -22,6 +32,46 @@ Each Store can have its own resources. For example, a Store can have its own Pro
| [**Promotion**](/core-concepts/promotions) | One Promotion can be associated with multiple Stores |
| **Store Credit** | One Store Credit belongs to and can be used in one Store
+## Current Store
+
+Spree will try to determine the current store based on the current URL. If the URL does not match any of the stores in the database, Spree will fall back to the default store.
+
+All Spree controllers or any other controllers that include [Spree::Core::ControllerHelpers::Store](https://github.com/spree/spree/blob/main/core/lib/spree/core/controller_helpers/store.rb) have access to the `current_store` method which returns the `Store` matching the current URL.
+
+All parts of Spree (API v1, API v2, Storefront, Admin Panel) have this implemented. This method is also available in views and JSON serializers.
+
+<Info>
+Under the hood `current_store` calls [Spree::Stores::FindCurrent.new(url: url).execute](https://github.com/spree/spree/blob/main/core/app/finders/spree/stores/find_current.rb).
+
+This logic can be easily overwritten by setting
+
+```ruby
+Spree::Dependencies.current_store_finder = 'MyStoreFinderClass'
+```
+
+in `config/initializers/spree.rb` file
+</Info>
+
+## Default Store
+
+If the system cannot find any Store that matches the current URL it will fall back to the Default Store.
+
+You can set the default Store via Rails console:
+
+```ruby
+Spree::Store.find(2).update(default: true)
+```
+
+To get the default store in your code or rails console type:
+
+```ruby
+Spree::Store.default
+```
+
+## Custom Domains
+
+Spree supports managing custom domains for Stores. In the Admin Panel, you can manage custom domains for each Store in the **Settings -> Domains** page.
+
## Setup multi-store application
-[Follow the setup guide](/developer/multi-store/setup) to get started.
\ No newline at end of file
+[Follow the setup guide](/developer/multi-store/setup) to get started.
diff --git a/docs/docs.json b/docs/docs.json
index 572b5a29a7..e7cc0f2c4b 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -103,9 +103,11 @@
"pages": [
"developer/core-concepts/architecture",
"developer/core-concepts/stores",
+ "developer/core-concepts/markets",
"developer/core-concepts/orders",
"developer/core-concepts/users",
"developer/core-concepts/products",
+ "developer/core-concepts/pricing",
"developer/core-concepts/inventory",
"developer/core-concepts/payments",
"developer/core-concepts/store-credits-gift-cards",
@@ -1203,6 +1205,7 @@
"pages": [
"developer/core-concepts/architecture",
"developer/core-concepts/stores",
+ "developer/core-concepts/markets",
"developer/core-concepts/orders",
"developer/core-concepts/users",
"developer/core-concepts/products",