Spree Commerce Countries API

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:
  responses:
    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
                    name: Finland
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '68'
                  type: country
                  attributes:
                    iso: FK
                    iso3: FLK
                    iso_name: FALKLAND ISLANDS (MALVINAS)
                    name: Falkland Islands (Malvinas)
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '69'
                  type: country
                  attributes:
                    iso: FM
                    iso3: FSM
                    iso_name: MICRONESIA, FEDERATED STATES OF
                    name: Micronesia, Federated States of
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '70'
                  type: country
                  attributes:
                    iso: FO
                    iso3: FRO
                    iso_name: FAROE ISLANDS
                    name: Faroe Islands
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '71'
                  type: country
                  attributes:
                    iso: FR
                    iso3: FRA
                    iso_name: FRANCE
                    name: France
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '72'
                  type: country
                  attributes:
                    iso: GA
                    iso3: GAB
                    iso_name: GABON
                    name: Gabon
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '73'
                  type: country
                  attributes:
                    iso: GB
                    iso3: GBR
                    iso_name: UNITED KINGDOM
                    name: United Kingdom
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '75'
                  type: country
                  attributes:
                    iso: GE
                    iso3: GEO
                    iso_name: GEORGIA
                    name: Georgia
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '76'
                  type: country
                  attributes:
                    iso: GF
                    iso3: GUF
                    iso_name: FRENCH GUIANA
                    name: French Guiana
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '77'
                  type: country
                  attributes:
                    iso: GG
                    iso3: GGY
                    iso_name: GUERNSEY
                    name: Guernsey
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '79'
                  type: country
                  attributes:
                    iso: GI
                    iso3: GIB
                    iso_name: GIBRALTAR
                    name: Gibraltar
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '80'
                  type: country
                  attributes:
                    iso: GL
                    iso3: GRL
                    iso_name: GREENLAND
                    name: Greenland
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '83'
                  type: country
                  attributes:
                    iso: GP
                    iso3: GLP
                    iso_name: GUADELOUPE
                    name: Guadeloupe
                    states_required: false
                    zipcode_required: true
                    default: false
                  relationships:
                    checkout_zone_applicable_states:
                      data: []
                - id: '85'
                  type: country
                  attributes:
              

# --- truncated at 32 KB (129 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree-commerce/refs/heads/main/openapi/spree-commerce-countries-api-openapi.yml