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.

4.2 KB
Raw Blame
---
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