Markets

List Markets

Returns all markets for the current store with their countries, currency, locales, and tax configuration.

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

markets.forEach(market => {
  market.id               // "mkt_UkLWZg9DAJ"
  market.name             // "North America"
  market.currency         // "USD"
  market.default_locale   // "en"
  market.tax_inclusive    // false
  market.default          // true
  market.supported_locales // ["en", "es"]
  market.countries        // [{ iso: "US", name: "United States of America", ... }]
})

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

Response:

{
  "data": [
    {
      "id": "mkt_UkLWZg9DAJ",
      "name": "North America",
      "currency": "USD",
      "default_locale": "en",
      "tax_inclusive": false,
      "default": true,
      "supported_locales": ["en", "es"],
      "countries": [
        { "iso": "US", "iso3": "USA", "name": "United States of America", "states_required": true, "zipcode_required": true }
      ]
    },
    {
      "id": "mkt_gbHJdmfrXB",
      "name": "Europe",
      "currency": "EUR",
      "default_locale": "de",
      "tax_inclusive": true,
      "default": false,
      "supported_locales": ["de", "en", "fr"],
      "countries": [
        { "iso": "DE", "iso3": "DEU", "name": "Germany", "states_required": false, "zipcode_required": true },
        { "iso": "FR", "iso3": "FRA", "name": "France", "states_required": false, "zipcode_required": true }
      ]
    }
  ]
}

Get a Market

const market = await client.markets.get('mkt_gbHJdmfrXB')

market.name      // "Europe"
market.currency  // "EUR"
market.countries // [{ iso: "DE", ... }, { iso: "FR", ... }]

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

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.

const market = await client.markets.resolve('DE')

market.id       // "mkt_gbHJdmfrXB"
market.name     // "Europe"
market.currency // "EUR"

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

If no market matches the given country, a 404 error is returned.

List Countries in a Market

Returns countries belonging to a specific market. Use this for address form country dropdowns during checkout.

const { data: countries } = await client.markets.countries.list('mkt_gbHJdmfrXB')

countries.forEach(country => {
  country.iso              // "DE"
  country.name             // "Germany"
  country.states_required  // false
  country.zipcode_required // true
})

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

Get a Country in a Market

Returns a single country by ISO code within a market. Use expand: ['states'] for address forms that need state/province dropdowns.

const country = await client.markets.countries.get('mkt_gbHJdmfrXB', 'US', {
  expand: ['states'],
})

country.iso    // "US"
country.name   // "United States of America"
country.states // [{ id: "st_xxx", name: "New York", abbr: "NY" }, ...]

curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB/countries/US?expand=states' \
  -H 'X-Spree-API-Key: pk_xxx'

Markets — Market concepts, zones, and configuration
Localization — Locale and currency headers
Geography — Global country endpoints

Getting Started

Store API

List Markets

Get a Market

Resolve Market by Country

List Countries in a Market

Get a Country in a Market

​List Markets

​Get a Market

​Resolve Market by Country

​List Countries in a Market

​Get a Country in a Market

​Related Documentation

List Markets

Get a Market

Resolve Market by Country

List Countries in a Market

Get a Country in a Market

Related Documentation