Spree Commerce Countries API
The Countries API from Spree Commerce — 5 operation(s) for countries.
OpenAPI Specification
openapi: 3.0.3
info:
title: Admin Account / Address Countries API
contact:
name: Spree Commerce
url: https://spreecommerce.org
email: hello@spreecommerce.org
description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n"
version: v3
servers:
- url: http://{defaultHost}
variables:
defaultHost:
default: localhost:3000
tags:
- name: Countries
paths:
/api/v2/platform/countries:
get:
summary: Returns a list of Countries
tags:
- Countries
security:
- bearer_auth: []
operationId: countries-list
description: Returns a list of Countries
responses:
'200':
description: Records returned
content:
application/vnd.api+json:
examples:
Example:
value:
data:
- id: '72'
type: country
attributes:
iso_name: UNITED STATES
iso: US
iso3: USA
name: United States of America
numcode: 840
states_required: true
updated_at: '2022-11-08T19:34:06.932Z'
zipcode_required: true
created_at: '2022-11-08T19:34:06.932Z'
relationships:
states:
data: []
- id: '73'
type: country
attributes:
iso_name: ISO_NAME_2
iso: I2
iso3: IS2
name: NAME_2
numcode: 840
states_required: false
updated_at: '2022-11-08T19:34:06.937Z'
zipcode_required: true
created_at: '2022-11-08T19:34:06.937Z'
relationships:
states:
data: []
- id: '74'
type: country
attributes:
iso_name: ISO_NAME_3
iso: I3
iso3: IS3
name: NAME_3
numcode: 840
states_required: false
updated_at: '2022-11-08T19:34:06.939Z'
zipcode_required: true
created_at: '2022-11-08T19:34:06.939Z'
relationships:
states:
data: []
meta:
count: 3
total_count: 3
total_pages: 1
links:
self: http://www.example.com/api/v2/platform/countries
next: http://www.example.com/api/v2/platform/countries?page=1
prev: http://www.example.com/api/v2/platform/countries?page=1
last: http://www.example.com/api/v2/platform/countries?page=1
first: http://www.example.com/api/v2/platform/countries?page=1
schema:
$ref: '#/components/schemas/resources_list'
'401':
description: Authentication Failed
content:
application/vnd.api+json:
examples:
Example:
value:
error: The access token is invalid
schema:
$ref: '#/components/schemas/error'
/api/v2/platform/countries/{id}:
get:
summary: Returns a Country
tags:
- Countries
security:
- bearer_auth: []
operationId: show-country
description: Returns a Country
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Record found
content:
application/vnd.api+json:
examples:
Example:
value:
data:
id: '79'
type: country
attributes:
iso_name: ISO_NAME_6
iso: I6
iso3: IS6
name: NAME_6
numcode: 840
states_required: false
updated_at: '2022-11-08T19:34:07.232Z'
zipcode_required: true
created_at: '2022-11-08T19:34:07.232Z'
relationships:
states:
data: []
schema:
$ref: '#/components/schemas/resource'
'404':
description: Record not found
content:
application/vnd.api+json:
examples:
Example:
value:
error: The resource you were looking for could not be found.
schema:
$ref: '#/components/schemas/error'
'401':
description: Authentication Failed
content:
application/vnd.api+json:
examples:
Example:
value:
error: The access token is invalid
schema:
$ref: '#/components/schemas/error'
/api/v2/storefront/countries:
get:
description: Returns a list of all countries.
tags:
- Countries
operationId: countries-list
responses:
'200':
$ref: '#/components/responses/CountryList'
summary: List all Countries
/api/v2/storefront/countries/{iso}:
get:
description: Returns the details of a specific country.
tags:
- Countries
operationId: show-country
parameters:
- $ref: '#/components/parameters/IsoOrIso3'
- $ref: '#/components/parameters/CountryIncludeParam'
- $ref: '#/components/parameters/SparseFieldsCountry'
responses:
'200':
$ref: '#/components/responses/Country'
'404':
$ref: '#/components/responses/404NotFound'
summary: Retrieve a Country
/api/v2/storefront/countries/default:
get:
description: Returns the default country for the current store. By default this will be the US.
tags:
- Countries
operationId: default-country
parameters:
- $ref: '#/components/parameters/CountryIncludeParam'
- $ref: '#/components/parameters/SparseFieldsCountry'
responses:
'200':
$ref: '#/components/responses/Country'
summary: Get Default Country
components:
schemas:
ListLinks:
x-internal: false
type: object
title: Pagination Links
properties:
self:
type: string
description: URL to the current page of the listing
next:
type: string
description: URL to the next page of the listing
prev:
type: string
description: URL to the previous page of the listing
last:
type: string
description: URL to the last page of the listing
first:
type: string
description: URL to the first page of the listing
CountryIncludes:
x-internal: false
title: Country Includes
oneOf:
- $ref: '#/components/schemas/State'
error:
type: object
properties:
error:
type: string
required:
- error
x-internal: false
resources_list:
type: object
properties:
data:
type: array
items:
allOf:
- $ref: '#/components/schemas/resource_properties'
meta:
type: object
properties:
count:
type: integer
total_count:
type: integer
total_pages:
type: integer
required:
- count
- total_count
- total_pages
links:
type: object
properties:
self:
type: string
next:
type: string
prev:
type: string
last:
type: string
first:
type: string
required:
- self
- next
- prev
- last
- first
required:
- data
- meta
- links
x-internal: false
State:
type: object
description: States within Spree are used to scope address data slightly more than country. States are useful for tax purposes, as different states in a country may impose different tax rates on different products. In addition to this, different states may cause different tax rates and shipping methods to be used for an order, similar to how countries affect it also.
title: State
properties:
abbr:
type: string
example: NY
description: State abbreviation
name:
type: string
example: New York
description: State name
x-internal: false
resource:
type: object
properties:
data:
$ref: '#/components/schemas/resource_properties'
required:
- data
x-internal: false
ListMeta:
type: object
x-internal: false
title: Pagination Meta
properties:
count:
type: number
example: 7
description: Number of items on the current listing
total_count:
type: number
example: 145
description: Number of all items matching the criteria
total_pages:
type: number
example: 10
description: Number of all pages containing items matching the criteria
resource_properties:
type: object
properties:
id:
type: string
type:
type: string
attributes:
type: object
relationships:
type: object
required:
- id
- type
- attributes
x-internal: false
Country:
title: Country
description: Countries within Spree are used as a container for states. Countries can be zone members, and also link to an address. The difference between one country and another on an address record can determine which tax rates and shipping methods are used for the order.[Read more about Countries in Spree](/developer/core-concepts/addresses#countries)
type: object
x-internal: false
properties:
id:
type: string
example: '1'
type:
type: string
default: country
attributes:
type: object
properties:
iso:
type: string
example: US
iso3:
type: string
example: USA
iso_name:
type: string
example: UNITED STATES
name:
type: string
example: United States
states_required:
type: boolean
zipcode_required:
type: boolean
default:
type: boolean
relationships:
type: object
properties:
states:
type: object
description: States associated with this Country
properties:
data:
type: array
items:
$ref: '#/components/schemas/State'
required:
- id
- type
- attributes
- relationships
responses:
Country:
description: 200 Success - Returns the `country` object.
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Country'
included:
type: array
items:
$ref: '#/components/schemas/CountryIncludes'
required:
- data
404NotFound:
description: 404 Not Found - Resource not found.
content:
application/vnd.api+json:
schema:
properties:
error:
type: string
example: The resource you were looking for could not be found.
default: The resource you were looking for could not be found.
examples:
404 Example:
value:
error: The resource you were looking for could not be found.
CountryList:
description: 200 Success - Returns an array of `country` objects.
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Country'
included:
type: array
items:
$ref: '#/components/schemas/CountryIncludes'
meta:
$ref: '#/components/schemas/ListMeta'
links:
$ref: '#/components/schemas/ListLinks'
required:
- data
- meta
- links
examples:
All Countries:
value:
data:
- id: '1'
type: country
attributes:
iso: AD
iso3: AND
iso_name: ANDORRA
name: Andorra
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '3'
type: country
attributes:
iso: AF
iso3: AFG
iso_name: AFGHANISTAN
name: Afghanistan
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '5'
type: country
attributes:
iso: AI
iso3: AIA
iso_name: ANGUILLA
name: Anguilla
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '6'
type: country
attributes:
iso: AL
iso3: ALB
iso_name: ALBANIA
name: Albania
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '7'
type: country
attributes:
iso: AM
iso3: ARM
iso_name: ARMENIA
name: Armenia
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '9'
type: country
attributes:
iso: AR
iso3: ARG
iso_name: ARGENTINA
name: Argentina
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '10'
type: country
attributes:
iso: AS
iso3: ASM
iso_name: AMERICAN SAMOA
name: American Samoa
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '11'
type: country
attributes:
iso: AT
iso3: AUT
iso_name: AUSTRIA
name: Austria
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '14'
type: country
attributes:
iso: AZ
iso3: AZE
iso_name: AZERBAIJAN
name: Azerbaijan
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '15'
type: country
attributes:
iso: BA
iso3: BIH
iso_name: BOSNIA AND HERZEGOVINA
name: Bosnia and Herzegovina
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '16'
type: country
attributes:
iso: BB
iso3: BRB
iso_name: BARBADOS
name: Barbados
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '17'
type: country
attributes:
iso: BD
iso3: BGD
iso_name: BANGLADESH
name: Bangladesh
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '18'
type: country
attributes:
iso: BE
iso3: BEL
iso_name: BELGIUM
name: Belgium
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '20'
type: country
attributes:
iso: BG
iso3: BGR
iso_name: BULGARIA
name: Bulgaria
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '21'
type: country
attributes:
iso: BH
iso3: BHR
iso_name: BAHRAIN
name: Bahrain
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '24'
type: country
attributes:
iso: BL
iso3: BLM
iso_name: SAINT BARTHÉLEMY
name: Saint Barthélemy
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '26'
type: country
attributes:
iso: BN
iso3: BRN
iso_name: BRUNEI DARUSSALAM
name: Brunei Darussalam
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '28'
type: country
attributes:
iso: BQ
iso3: BES
iso_name: BONAIRE, SINT EUSTATIUS AND SABA
name: Bonaire, Sint Eustatius and Saba
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '31'
type: country
attributes:
iso: BT
iso3: BTN
iso_name: BHUTAN
name: Bhutan
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '33'
type: country
attributes:
iso: BY
iso3: BLR
iso_name: BELARUS
name: Belarus
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '36'
type: country
attributes:
iso: CC
iso3: CCK
iso_name: COCOS (KEELING) ISLANDS
name: Cocos (Keeling) Islands
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '40'
type: country
attributes:
iso: CH
iso3: CHE
iso_name: SWITZERLAND
name: Switzerland
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '43'
type: country
attributes:
iso: CL
iso3: CHL
iso_name: CHILE
name: Chile
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '46'
type: country
attributes:
iso: CO
iso3: COL
iso_name: COLOMBIA
name: Colombia
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '47'
type: country
attributes:
iso: CR
iso3: CRI
iso_name: COSTA RICA
name: Costa Rica
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '48'
type: country
attributes:
iso: CU
iso3: CUB
iso_name: CUBA
name: Cuba
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '49'
type: country
attributes:
iso: CV
iso3: CPV
iso_name: CABO VERDE
name: Cabo Verde
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '50'
type: country
attributes:
iso: CW
iso3: CUW
iso_name: CURAÇAO
name: Curaçao
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '51'
type: country
attributes:
iso: CX
iso3: CXR
iso_name: CHRISTMAS ISLAND
name: Christmas Island
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '52'
type: country
attributes:
iso: CY
iso3: CYP
iso_name: CYPRUS
name: Cyprus
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '53'
type: country
attributes:
iso: CZ
iso3: CZE
iso_name: CZECHIA
name: Czechia
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '54'
type: country
attributes:
iso: DE
iso3: DEU
iso_name: GERMANY
name: Germany
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '56'
type: country
attributes:
iso: DK
iso3: DNK
iso_name: DENMARK
name: Denmark
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '58'
type: country
attributes:
iso: DO
iso3: DOM
iso_name: DOMINICAN REPUBLIC
name: Dominican Republic
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '59'
type: country
attributes:
iso: DZ
iso3: DZA
iso_name: ALGERIA
name: Algeria
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '60'
type: country
attributes:
iso: EC
iso3: ECU
iso_name: ECUADOR
name: Ecuador
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '61'
type: country
attributes:
iso: EE
iso3: EST
iso_name: ESTONIA
name: Estonia
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '62'
type: country
attributes:
iso: EG
iso3: EGY
iso_name: EGYPT
name: Egypt
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '65'
type: country
attributes:
iso: ET
iso3: ETH
iso_name: ETHIOPIA
name: Ethiopia
states_required: false
zipcode_required: true
default: false
relationships:
checkout_zone_applicable_states:
data: []
- id: '66'
type: country
attributes:
iso: FI
iso3: FIN
iso_name: FINLAND
# --- truncated at 32 KB (129 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree/refs/heads/main/openapi/spree-countries-api-openapi.yml