Countries & States
Because billing and shipping addresses are important for orders, Commerce provides convenient, flexible support for working with whatever countries and states your store needs to support.
When you first install Commerce, a complete set of countries and their related states will be prepopulated. You can see these navigating in the control panel to Store Settings → Countries & States. From there, you can remove any countries you don’t want to be available for checkout, reorder those countries, and add/edit any states within and optionally designate the state as a required field on a per-country basis.
Starting your own country? No problem! Choose New Country from the Countries & States list to enter your own country name, ISO, and individual states.
# Fetching Countries
The following methods are available for getting country data.
- allEnabledCountries
- allEnabledCountriesAsList
- allCountries
- allCountriesAsList
- countriesByShippingZoneId
- countriesByTaxZoneId
- countryById
- countryByIso
# allEnabledCountries
Returns an array of craft\commerce\models\Country (opens new window) objects representing all countries that have been enabled.
{% set countries = craft.commerce.countries.allEnabledCountries %}
<select>
{% for country in countries %}
<option value="{{ country.id }}">
{{- country.name -}}
</option>
{% endfor %}
</select>
# craft.commerce.countries.allEnabledCountriesAsList
Returns a key-value array representing all countries that have been enabled. Each key is the country ID and the value is the full name of that country.
Data returned as [32:'Australia', 72:'United States']
.
{% set countries = craft.commerce.countries.allEnabledCountriesAsList %}
<select>
{% for id, countryName in countries %}
<option value="{{ id }}">
{{- countryName -}}
</option>
{% endfor %}
</select>
# craft.commerce.countries.allCountries
Returns an array of craft\commerce\models\Country (opens new window) objects representing all countries defined in the system regardless of whether they’re enabled.
{% set countries = craft.commerce.countries.allCountries %}
<select name="country">
{% for country in countries %}
<option value="{{ country.id }}">
{{- country.name -}}
</option>
{% endfor %}
</select>
# craft.commerce.countries.allCountriesAsList
Returns a key-value array representing all countries defined in the system regardless of whether they’re enabled. Each key is the country ID and the value is the full name of that country.
Data returned as [32:'Australia', 72:'United States']
.
{% set countries = craft.commerce.countries.allCountriesAsList %}
<select>
{% for id, countryName in countries %}
<option value="{{ id }}">
{{- countryName -}}
</option>
{% endfor %}
</select>
# craft.commerce.countries.countriesByShippingZoneId
Returns an array of craft\commerce\models\Country (opens new window) objects representing all countries within the specified shipping zone, per the shipping zone’s ID.
{% set countries = craft.commerce.countries
.countriesByShippingZoneId(shippingZoneId) %}
<select name="country">
{% for country in countries %}
<option value="{{ country.id }}">
{{- country.name -}}
</option>
{% endfor %}
</select>
# craft.commerce.countries.countriesByTaxZoneId
Returns an array of craft\commerce\models\Country (opens new window) objects representing all countries within the specified tax zone, per the tax zone’s ID.
{% set countries = craft.commerce.countries.countriesByTaxZoneId(taxZoneId) %}
<select name="country">
{% for country in countries %}
<option value="{{ country.id }}">
{{- country.name -}}
</option>
{% endfor %}
</select>
# craft.commerce.countries.countryById
Returns a craft\commerce\models\Country (opens new window) object for the provided country ID.
{% set country = craft.commerce.countries.countryById(countryId) %}
{# country.id #}
{# country.name #}
# craft.commerce.countries.countryByIso
Returns a craft\commerce\models\Country (opens new window) object for the provided two-character country ISO code.
{% set country = craft.commerce.countries.countryByIso('AU') %}
{# country.id #}
{# country.name #}
# Fetching States
The following methods are available for getting country data.
- allEnabledStates
- allEnabledStatesAsList
- allEnabledStatesAsListGroupedByCountryId
- allStates
- allStatesAsList
- allStatesAsListGroupedByCountryId
- statesByCountryId
- statesByShippingZoneId
- statesByTaxZoneId
- stateByAbbreviation
- stateById
# craft.commerce.states.allEnabledStates
Returns an array of craft\commerce\models\State (opens new window) objects representing all states that have been enabled.
<select>
{% for state in craft.commerce.states.allEnabledStates %}
<option value="{{ state.id }}">
{{- state.name -}}
</option>
{% endfor %}
</select>
# craft.commerce.states.allEnabledStatesAsList
Returns a key-value array representing all states that have been enabled. Each key is the state ID and the value is the full name of that state.
Data returned as [1:'Australian Capital Territory', 2:'New South Wales']
.
{% set states = craft.commerce.states.allEnabledStatesAsList %}
<select>
{% for id, stateName in states %}
<option value="{{ id }}">
{{- stateName -}}
</option>
{% endfor %}
</select>
# craft.commerce.states.allEnabledStatesAsListGroupedByCountryId
Returns an array of craft\commerce\models\State (opens new window) object arrays, indexed by country IDs.
Data returned as [72:[3:'California', 4:'Washington'],32:[7:'New South Wales']]
.
{% set statesByCountryId = craft.commerce.states
.allEnabledStatesAsListGroupedByCountryId %}
<select>
{% for countryId, states in statesByCountryId %}
{% set country = craft.commerce.countries.getCountryById(countryId) %}
<optgroup label="{{ country.name }}">
{% for stateId, stateName in states %}
<option value="{{ stateId }}">{{ stateName }}</option>
{% endfor %}
</optgroup>
{% endfor %}
</select>
# craft.commerce.states.allStates
Returns an array of craft\commerce\models\State (opens new window) objects representing all states defined in the system regardless of whether they’re enabled.
<select>
{% for state in craft.commerce.states.allStates %}
<option value="{{ state.id }}">
{{- state.name -}}
</option>
{% endfor %}
</select>
# craft.commerce.states.allStatesAsList
Returns a key-value array representing all states defined in the system regardless of whether they’re enabled. Each key is the state ID and the value is the full name of that state.
Data returned as [1:'Australian Capital Territory', 2:'New South Wales']
.
{% set states = craft.commerce.states.allStatesAsList %}
<select>
{% for id, stateName in states %}
<option value="{{ id }}">
{{- stateName -}}
</option>
{% endfor %}
</select>
# craft.commerce.states.statesByCountryId
Returns an array of craft\commerce\models\State (opens new window) objects representing all states belonging to the provided country ID, ignoring whether the country or any state is enabled.
<select>
{% for state in craft.commerce.states.statesByCountryId(countryId) %}
<option value="{{ state.id }}">
{{- state.name -}}
</option>
{% endfor %}
</select>
# craft.commerce.states.statesByShippingZoneId
Returns an array of craft\commerce\models\State (opens new window) objects representing all states belonging to the provided shipping zone by the provided zone ID.
<select>
{% for state in craft.commerce.states.statesByShippingZoneId(shippingZoneId) %}
<option value="{{ state.id }}">
{{- state.name -}}
</option>
{% endfor %}
</select>
# craft.commerce.states.statesByTaxZoneId
Returns an array of craft\commerce\models\State (opens new window) objects representing all states belonging to the provided tax zone by the provided zone ID.
<select>
{% for state in craft.commerce.states.statesByTaxZoneId(taxZoneId) %}
<option value="{{ state.id }}">
{{- state.name -}}
</option>
{% endfor %}
</select>
# craft.commerce.states.stateByAbbreviation
Returns a craft\commerce\models\State (opens new window) object for the provided country ID and state abbreviation.
{% set state = craft.commerce.states.stateByAbbreviation(countryId, 'ACT') %}
{# state.id #}
{# state.name #}
# craft.commerce.states.stateById
Returns a craft\commerce\models\State (opens new window) object for the provided state ID.