Skip to main content
The Store API supports multi-language, multi-currency, and market-aware responses. Use request headers to control the locale, currency, and country for each request.

​
Headers

HeaderExampleDescription
X-Spree-LocalefrLanguage for translated content (product names, descriptions, etc.)
X-Spree-CurrencyEURCurrency for prices and totals
X-Spree-CountryFRCountry ISO code for market resolution

​
Client-Level Defaults

Set locale, currency, and country once at initialization — all subsequent requests use these defaults:
SDK
import { createSpreeClient } from '@spree/sdk'

const client = createSpreeClient({
  baseUrl: 'https://api.mystore.com',
  publishableKey: 'spree_pk_xxx',
  locale: 'fr',
  currency: 'EUR',
  country: 'FR',
})

// All requests use fr/EUR/FR automatically
const products = await client.store.products.list()
Update defaults at any time: 
client.setLocale('de')
client.setCurrency('EUR')
client.setCountry('DE')

​
Per-Request Overrides

Override client defaults for individual requests: 
const products = await client.store.products.list({}, {
  locale: 'fr',
  currency: 'EUR',
  country: 'FR',
})

​
Country and Markets

The X-Spree-Country header resolves the customer’s market, which influences default locale and currency. Markets allow you to configure different pricing, languages, and product availability per region. 
// Setting country automatically resolves the market
const products = await client.store.products.list({}, {
  country: 'DE', // Resolves German market → EUR, de locale
})
When a market is resolved from the country:
  1. The market’s default locale is used (unless overridden by X-Spree-Locale)
  2. The market’s default currency is used (unless overridden by X-Spree-Currency)
You can also resolve the market explicitly using the Markets API: 
// Resolve which market applies for a country
const market = await client.store.markets.resolve('DE')
// => { id: "mkt_xxx", name: "Europe", currency: "EUR", default_locale: "de", ... }

// Then set the client defaults
client.setLocale(market.default_locale)
client.setCurrency(market.currency)
client.setCountry('DE')

​
Resolution Priority

Each value is resolved in the following order:

​
Locale

  1. X-Spree-Locale header
  2. locale query parameter
  3. Market default locale (if country is set)
  4. Store default locale

​
Currency

  1. X-Spree-Currency header
  2. currency query parameter
  3. Market default currency (if country is set)
  4. Store default currency

​
Market

  1. X-Spree-Country header
  2. country query parameter
The locale and currency must be supported by the current store. If an unsupported value is provided, the API falls back to the store’s default.

​
Translated Content

When a locale is set, all translatable fields are returned in the requested language. This includes product names, descriptions, taxon names, and other content managed through translations. 
// English (default)
const enProduct = await client.store.products.get('spree-tote')
console.log(enProduct.name) // "Spree Tote"

// French
const frProduct = await client.store.products.get('spree-tote', {}, {
  locale: 'fr',
})
console.log(frProduct.name) // "Sac Spree"
If a translation doesn’t exist for the requested locale, the API falls back to the store’s default locale automatically.

​
Currency-Aware Prices

All price fields in the response reflect the requested currency: 
// USD prices
const usdProduct = await client.store.products.get('spree-tote', {}, {
  currency: 'USD',
})
console.log(usdProduct.price) // { amount: "15.99", currency: "USD" }

// EUR prices
const eurProduct = await client.store.products.get('spree-tote', {}, {
  currency: 'EUR',
})
console.log(eurProduct.price) // { amount: "14.49", currency: "EUR" }

​
Discovering Available Options

Use the dedicated endpoints to discover which markets, countries, locales, and currencies are available. These are derived from your store’s markets configuration.

​
Markets

List all markets to get the full picture of regions, currencies, and supported locales: 
const { data: markets } = await client.store.markets.list()
// [
//   { id: "mkt_xxx", name: "North America", currency: "USD", default_locale: "en",
//     supported_locales: ["en", "es"], countries: [{ iso: "US", ... }, { iso: "CA", ... }] },
//   { id: "mkt_yyy", name: "Europe", currency: "EUR", default_locale: "de",
//     supported_locales: ["de", "en", "fr"], countries: [{ iso: "DE", ... }, { iso: "FR", ... }] },
// ]

​
Countries

List all countries or countries within a specific market. Each country includes its market’s currency and supported locales: 
// All countries across all markets
const { data: countries } = await client.store.countries.list()

// Countries in a specific market (useful for checkout address forms)
const { data: marketCountries } = await client.store.markets.countries.list('mkt_xxx')

// Get a single country with states
const usa = await client.store.countries.get('US', {
  expand: ['states'],
})
console.log(usa.states) // [{ abbr: "CA", name: "California" }, ...]

​
Locales

const { data: locales } = await client.store.locales.list()
// [{ code: "en", name: "English" }, { code: "fr", name: "French" }, ...]

​
Currencies

const { data: currencies } = await client.store.currencies.list()
// [{ iso_code: "USD", name: "US Dollar", symbol: "$" }, { iso_code: "EUR", name: "Euro", symbol: "€" }, ...]