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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Markets
description: Use the Spree Storefront SDK to list markets, resolve a market by country, and fetch the countries available within each market for checkout.
---
## List Markets
Returns all markets for the current store with their countries, currency, locales, and tax configuration.
<CodeGroup>
```typescript SDK
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", iso3: "USA", ... }]
})
```
```bash cURL
curl 'https://api.mystore.com/api/v3/store/markets' \
-H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
**Response:**
```json
{
"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", "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", "states_required": false, "zipcode_required": true },
{ "iso": "FR", "iso3": "FRA", "states_required": false, "zipcode_required": true }
]
}
]
}
```
## Get a Market
<CodeGroup>
```typescript SDK
const market = await client.markets.get('mkt_gbHJdmfrXB')
market.name // "Europe"
market.currency // "EUR"
market.countries // [{ iso: "DE", ... }, { iso: "FR", ... }]
```
```bash cURL
curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB' \
-H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
## 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.
<CodeGroup>
```typescript SDK
const market = await client.markets.resolve('DE')
market.id // "mkt_gbHJdmfrXB"
market.name // "Europe"
market.currency // "EUR"
```
```bash cURL
curl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \
-H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
<Info>
If no market matches the given country, a `404` error is returned.
</Info>
## List Countries in a Market
Returns countries belonging to a specific market. Use this for address form country dropdowns during checkout.
<CodeGroup>
```typescript SDK
const { data: countries } = await client.markets.countries.list('mkt_gbHJdmfrXB')
// Name each country in the customer's language from its ISO code
const countryName = new Intl.DisplayNames([locale], { type: 'region' })
countries.forEach(country => {
country.iso // "DE"
countryName.of(country.iso) // "Germany" in English, "Deutschland" in German
country.states_required // false
country.zipcode_required // true
})
```
```bash cURL
curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB/countries' \
-H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
## 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.
<CodeGroup>
```typescript SDK
const country = await client.markets.countries.get('mkt_gbHJdmfrXB', 'US', {
expand: ['states'],
})
country.iso // "US"
country.states // [{ id: "st_xxx", name: "New York", abbr: "NY" }, ...]
```
```bash cURL
curl 'https://api.mystore.com/api/v3/store/markets/mkt_gbHJdmfrXB/countries/US?expand=states' \
-H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
## Related Documentation
- [Markets](/developer/core-concepts/markets) — Market concepts, zones, and configuration
- [Localization](/api-reference/store-api/localization) — Locale and currency headers
- [Geography](/developer/sdk/store/products#geography) — Global country endpoints