Countries & States

Craft Commerce takes advantage of Craft’s built-in addresses support for managing store and order addresses, and includes tools for working with them.

As you’re building your store, you’ll most likely need to fetch two different kinds of address data:

  1. Store-specific addresses configured in Commerce, like the store location and markets.
    (Set these via Commerce → Store Settings → Store.)
  2. Global lists of countries and states, provided by Craft’s address repository.

# Fetching Countries

You can fetch countries within the configured Commerce markets, shipping zones, and tax zones, or more broadly from the Craft CMS address repository.

# Store Market Countries

The store model (opens new window)’s getCountriesList() method returns a key-value array of countries in the store’s configured market. The key will be the country’s two-character ISO code and the value will be its name:

{% set storeCountries = craft.commerce
  .getStore()
  .getStore()
  .getCountriesList() %}

<select>
{% for code, name in storeCountries %}
  <option value="{{ code }}">
    {{- name -}}
  </option>
{% endfor %}
</select>

# Country by ID

If you need to get information for a single country, you can pass its two-character code (and optional locale string) to Craft’s address repository:

{# @var country CommerceGuys\Addressing\Country\Country #}
{% set country = craft.app.getAddresses().countryRepository.get('US') %}

The resulting Country (opens new window) object includes additional code, labeling, and locale information.

# All Countries

You can fetch a list of all countries from Craft’s address repository:

{% set countries = craft.app.getAddresses().countryRepository.getList() %}
<select name="myCountry">
  {% for code, name in countries %}
    <option value="{{ code }}">{{ name }}</option>
  {% endfor %}
</select>

Use getAll() rather than getList() to get back an array of Country (opens new window) objects.

# Fetching States

States are represented by the more general concept of administrative areas in Craft CMS and Craft Commerce. You can fetch states within the configured Commerce markets, or generic lists directly from the Craft CMS address repository.

# Store Market Administrative Areas

You can fetch the states that are part of Commerce’s configured store market via the store model (opens new window). Results will be keyed by country code:

{% set storeStates = craft.commerce
  .getStore()
  .getStore()
  .getAdministrativeAreasListByCountryCode() %}

{% for countryCode, states in storeStates %}
  <h2>{{ countryCode }}</h2>
  <select name="myState">
    {% for code, name in states %}
      <option value="{{ code }}">{{ name }}</option>
    {% endfor %}
  </select>
{% endfor %}

# Administrative Area by ID

You can fetch a single state’s data, represented by a subdivision, by providing its two-character ISO code and parent(s) to the subdivision repository:

{# @var state CommerceGuys\Addressing\Subdivision\Subdivision #}
{% set state = craft.app.getAddresses().subdivisionRepository.get('OR', ['US']) %}

The resulting Subdivision (opens new window) object includes additional code, labeling, and postal code information as well as the ability to access relevant parents and children.

# All Administrative Areas

You can fetch all states for one or more countries using Craft’s address repository:

{% set states = craft.app.getAddresses().subdivisionRepository.getList(['US']) %}
<select name="myState">
  {% for code, name in states %}
    <option value="{{ code }}">{{ name }}</option>
  {% endfor %}
</select>