Markets - Spree Commerce documentation

Overview

Markets let you segment a single Store 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 Attributes

Attribute	Description	Example
`name`	Human-readable name, unique per store	`North America`
`currency`	ISO 4217 currency code	`USD`
`default_locale`	Default language for this market	`en`
`supported_locales`	All locales available in this market	`["en", "es"]`
`tax_inclusive`	Whether the prices entered for this market include tax	`false`
`default`	Whether this is the fallback market when no country match is found	`true`
`country_codes`	Countries in this market, as ISO codes	`["US", "CA"]`

How Markets Work

When a customer visits your store, their country determines which market applies. The market then sets the currency, locale, and tax behavior for that session.

Customer's Country → Market → Currency + Locale + Tax treatment

The resolution chain:

Customer’s country is detected (from URL, geolocation, X-Spree-Country header, or manual selection)
Spree finds the market containing that country
The market’s currency and locale become the defaults for the session
The market’s tax setting determines whether prices are shown with or without tax

If no market matches the customer’s country, the store’s default market is used.

Listing Markets

Fetch all markets for the current store, including their countries:

const { data: markets } = await client.markets.list()
// [
//   {
//     id: "mkt_k5nR8xLq",
//     name: "North America",
//     currency: "USD",
//     default_locale: "en",
//     supported_locales: ["en", "es"],
//     tax_inclusive: false,
//     default: true,
//     countries: [
//       { iso: "US", name: "United States", states_required: true, zipcode_required: true },
//       { iso: "CA", name: "Canada", states_required: true, zipcode_required: true }
//     ]
//   },
//   ...
// ]

const { data: markets } = await adminClient.markets.list()

curl 'https://api.mystore.com/api/v3/store/markets' \
  -H 'X-Spree-API-Key: pk_xxx'

Resolving a Market by Country

When you know a customer’s country (e.g., from geolocation or a country picker), resolve which market applies:

const market = await client.markets.resolve('DE')
// { id: "mkt_gbHJdmfr", name: "Europe", currency: "EUR", tax_inclusive: true, ... }

curl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \
  -H 'X-Spree-API-Key: pk_xxx'

Returns the market object on success, or 404 if no market contains that country. This is useful for building a country switcher — resolve the market to show the customer what currency and language they’ll get.

Countries in a Market

List countries belonging to a specific market. Useful for populating address form dropdowns during checkout:

const { data: countries } = await client.markets.countries.list('mkt_k5nR8xLq')
// [
//   { iso: "CA", name: "Canada", states_required: true, zipcode_required: true },
//   { iso: "US", name: "United States", states_required: true, zipcode_required: true }
// ]

// Get a country with its states (for address form dropdowns)
const usa = await client.markets.countries.get('mkt_k5nR8xLq', 'US', {
  expand: ['states'],
})

# List countries in a market
curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries' \
  -H 'X-Spree-API-Key: pk_xxx'

# Get a country with its states
curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries/US?expand=states' \
  -H 'X-Spree-API-Key: pk_xxx'

You can also fetch countries flat (across all markets) or include the market on a country:

// All countries across all markets
const { data: countries } = await client.countries.list()

// Get a country with its market details
const germany = await client.countries.get('DE', { expand: ['market'] })
// { iso: "DE", name: "Germany", market: { currency: "EUR", default_locale: "de", tax_inclusive: true } }

const { data: countries } = await adminClient.countries.list()

const germany = await adminClient.countries.get('DE')

# All countries across all markets
curl 'https://api.mystore.com/api/v3/store/countries' \
  -H 'X-Spree-API-Key: pk_xxx'

# Get a country with its market
curl 'https://api.mystore.com/api/v3/store/countries/DE?expand=market' \
  -H 'X-Spree-API-Key: pk_xxx'

Currency and Locale

Each market defines a currency and set of supported locales. When a market is resolved, its currency and locale become the defaults for the session. You can discover all available currencies and locales (aggregated from all markets) via dedicated endpoints:

const { data: currencies } = await client.currencies.list()
// [{ iso_code: "USD", decimal_places: 2 }, { iso_code: "EUR", decimal_places: 2 }]

const { data: locales } = await client.locales.list()
// [{ code: "en", default: true, rtl: false }, { code: "de", default: false, rtl: false }]

// Name them in the customer's language in the browser
new Intl.DisplayNames([locale], { type: 'currency' }).of('EUR') // "Euro"
new Intl.DisplayNames([locale], { type: 'language' }).of('de') // "German"

curl 'https://api.mystore.com/api/v3/store/currencies' \
  -H 'X-Spree-API-Key: pk_xxx'

curl 'https://api.mystore.com/api/v3/store/locales' \
  -H 'X-Spree-API-Key: pk_xxx'

See Localization for details on how to pass locale, currency, and country headers in API requests.

Tax Behavior

The tax_inclusive flag on a market decides whether the prices entered for it include tax:

tax_inclusive: true (common in Europe) — every customer pays the price as entered, with their country’s tax inside it
tax_inclusive: false (common in the US) — tax is added at checkout on top of the price

The same price is charged to every customer of the market, wherever they are. Take a €100.00 price in a market covering Germany (19%) and France (20%):

`tax_inclusive`	Customer in Germany pays	Customer in France pays
`true`	€100.00, of which €15.97 is VAT	€100.00, of which €16.67 is VAT
`false`	€119.00: €100.00 plus €19.00 VAT	€120.00: €100.00 plus €20.00 VAT

Tax rates only hold the percentage for each country; the market decides whether that tax is inside the price. Spree’s own tax tables and external tax providers both read the market’s setting, and each order’s tax lines record whether their tax was included, so editing a market later never changes an order already placed. A storefront can read tax_inclusive from the market to tell the shopper whether the price they see includes tax. Prices are never adjusted for customers in another country. To charge some countries a different price, put them in a market of their own and give it a price list with a Market Rule. Before a customer enters an address, the market’s first country by name supplies the tax rate; once a shipping address is entered at checkout, that address takes over and the real rate applies. A market also chooses which tax provider works out its numbers — Spree’s own rate tables in a simple market, an external tax service in a complicated one. See Taxes.

Pricing Integration

Markets integrate with the Pricing system, enabling market-specific pricing through Price Lists with a Market Rule. This lets you set different prices for the same product in different markets — beyond just currency conversion. For example, you could price a product at $29.99 in North America and €24.99 in Europe, rather than relying on exchange rate conversion. See Pricing — Price Rules for details on configuring market-specific price lists.

Setting Up Markets

Markets are managed in the admin dashboard under Settings → Markets. When you run rails db:seed, Spree automatically creates a default market for each store. To create markets programmatically, use the Admin API. See the Admin API endpoints for the full list of /markets routes and required scopes:

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://store.example.com',
  secretKey: 'sk_xxx',
})

// North America market (countries by ISO code)
const northAmerica = await client.markets.create({
  name: 'North America',
  currency: 'USD',
  default_locale: 'en',
  country_codes: ['US', 'CA'],
  default: true,
})

// Europe market with tax-inclusive pricing
const europe = await client.markets.create({
  name: 'Europe',
  currency: 'EUR',
  default_locale: 'de',
  supported_locales: ['de', 'en', 'fr'],
  tax_inclusive: true,
  country_codes: ['DE', 'FR', 'AT', 'NL'],
})

spree api post /markets -d '{
  "name": "North America",
  "currency": "USD",
  "default_locale": "en",
  "country_codes": ["US", "CA"],
  "default": true
}'

Update or remove a market the same way:

await client.markets.update('market_xxx', { tax_inclusive: true })
await client.markets.delete('market_xxx')

spree api patch /markets/market_xxx -d '{"tax_inclusive": true}'
spree api delete /markets/market_xxx

Markets (Store SDK) — Listing, resolving, and reading markets from the Store SDK
Pricing — Price Lists, Price Rules, and the Pricing Context
Addresses — Countries, states, and address forms
Localization — Locale, currency, and country headers in API requests
Translations — Resource and UI translations

​Overview

​Market Attributes

​How Markets Work

​Listing Markets

​Resolving a Market by Country

​Countries in a Market

​Currency and Locale

​Tax Behavior

​Pricing Integration

​Setting Up Markets

​Related Documentation