openapi: 3.0.0
info:
  version: 1.0.0-oas3
  title: BigCommerce Geography
  description: Get countries, states, and provinces.
paths:
  /countries:
    get:
      description: >-
        Get a list of all countries available. A country or territory,
        identifiable by an ISO 3166 country code.
      summary: BigCommerce Get All Countries
      operationId: getCountries
      parameters:
        - name: Accept
          in: header
          required: true
          description: ''
          schema:
            type: string
            default: application/json
        - name: Content-Type
          in: header
          required: true
          description: ''
          schema:
            type: string
            default: application/json
        - name: page
          in: query
          required: false
          description: Number of pages
          schema:
            type: number
            exclusiveMinimum: false
            exclusiveMaximum: false
        - name: limit
          in: query
          required: false
          description: Count per page
          schema:
            type: number
            exclusiveMinimum: false
            exclusiveMaximum: false
        - in: query
          name: country
          schema:
            type: string
        - in: query
          name: country_iso2
          schema:
            type: string
        - in: query
          name: country_iso3
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/countryCollection_Resp'
      tags:
        - Countries
  /countries/{id}:
    get:
      description: >-
        Returns a single *Country*.  Gets a country. A country or territory,
        identifiable by an ISO 3166 country code.
      summary: BigCommerce Get a Country
      operationId: getCountry
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the country.
          schema:
            type: integer
            exclusiveMinimum: false
            exclusiveMaximum: false
        - name: Accept
          in: header
          required: true
          description: ''
          schema:
            type: string
            default: application/json
        - name: Content-Type
          in: header
          required: true
          description: ''
          schema:
            type: string
            default: application/json
      responses:
        '200':
          $ref: '#/components/responses/countriesResponse'
      tags:
        - Countries
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
  /countries/{country_id}/states:
    get:
      description: |-
        Returns a list of *States* belonging to a *Country*. 
        A state or province, identifiable by an ISO 3166 subdivision code.
      summary: BigCommerce Get All Countryʼs States
      operationId: getCountryStates
      parameters:
        - name: country_id
          in: path
          required: true
          description: Id of the country
          schema:
            type: integer
            exclusiveMinimum: false
            exclusiveMaximum: false
        - name: Accept
          in: header
          required: true
          description: ''
          schema:
            type: string
        - name: Content-Type
          in: header
          required: true
          description: ''
          schema:
            type: string
        - name: state
          in: query
          required: false
          description: Name of the state/province.
          schema:
            type: string
        - name: state_abbreviation
          in: query
          required: false
          description: Abbreviation for the state/province.
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Number of pages
          schema:
            type: number
            exclusiveMinimum: false
            exclusiveMaximum: false
        - name: limit
          in: query
          required: false
          description: Count per page
          schema:
            type: number
            exclusiveMinimum: false
            exclusiveMaximum: false
      responses:
        '200':
          $ref: '#/components/responses/countriesStatesCollectionResponse'
      tags:
        - States
    parameters:
      - name: country_id
        in: path
        required: true
        schema:
          type: string
  /countries/{country_id}/states/{id}:
    get:
      operationId: getCountryState
      description: |-
        Returns a *State*. 
        A state or province, identifiable by an ISO 3166 subdivision code.
      summary: BigCommerce Get a Countryʼs State
      parameters:
        - name: country_id
          in: path
          required: true
          description: Id of the country
          schema:
            type: integer
            exclusiveMinimum: false
            exclusiveMaximum: false
        - name: id
          in: path
          required: true
          description: Id of the states
          schema:
            type: integer
            exclusiveMinimum: false
            exclusiveMaximum: false
        - name: Accept
          in: header
          required: true
          description: ''
          schema:
            type: string
            default: application/json
        - name: Content-Type
          in: header
          required: true
          description: ''
          schema:
            type: string
            default: application/json
      responses:
        '200':
          $ref: '#/components/responses/countriesStatesResponse'
      x-unitTests: []
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
      tags:
        - States
    parameters:
      - name: country_id
        in: path
        required: true
        schema:
          type: string
      - schema:
          type: string
        name: id
        in: path
        required: true
  /countries/count:
    get:
      responses:
        '200':
          $ref: '#/components/responses/countResponse'
      summary: BigCommerce Get a Count of All Countries
      tags:
        - Countries
      operationId: getCountriesCount
      description: Returns a count of all countries.
  /countries/states/count:
    get:
      operationId: getStatesCount
      responses:
        '200':
          $ref: '#/components/responses/countResponse'
      summary: BigCommerce Get a Count of All States
      tags:
        - States
      description: Returns a count of all states.
  /countries/states:
    get:
      responses:
        '200':
          $ref: '#/components/responses/countriesStatesCollectionResponse'
      summary: BigCommerce Get All States
      tags:
        - States
      description: Returns a list of all states.
      operationId: getStates
      parameters:
        - schema:
            type: integer
          in: query
          name: limit
          description: The number of results to return per request.
        - schema:
            type: integer
          in: query
          name: page
          description: The ordered grouping of results to return.
  /countries/{country_id}/states/count:
    get:
      operationId: getCountryStatesCount
      responses:
        '200':
          $ref: '#/components/responses/countResponse'
      summary: BigCommerce Get a Count of Country’s States
      tags:
        - States
      description: Returns a count of a countryʼs states.
    parameters:
      - name: country_id
        in: path
        required: true
        schema:
          type: string
security:
  - X-Auth-Token: []
tags:
  - name: Countries
  - name: States
servers:
  - url: https://api.bigcommerce.com/stores/{store_hash}/v2
    variables:
      store_hash:
        default: store_hash
        description: Permanent ID of the BigCommerce store.
    description: BigCommerce API Gateway
components:
  responses:
    countriesResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/country_Full'
          examples:
            response:
              value:
                id: 1
                country: Afghanistan
                country_iso2: AF
                country_iso3: AFG
                states:
                  url: >-
                    https://api.bigcommerce.com/stores/h10wocxy6s/v2/countries/1/states
                  resource: /countries/1/states
    countriesStatesResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/countriesState_Full'
    countryCollection_Resp:
      description: ''
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/country_Full'
          example:
            - id: 1
              country: Afghanistan
              country_iso2: AF
              country_iso3: AFG
              states:
                url: >-
                  https://api.bigcommerce.com/stores/store_hash/v2/countries/1/states
                resource: /countries/1/states
            - id: 2
              country: Albania
              country_iso2: AL
              country_iso3: ALB
              states:
                url: >-
                  https://api.bigcommerce.com/stores/store_hash/v2/countries/2/states
                resource: /countries/2/states
    countriesStatesCollectionResponse:
      description: ''
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/countriesState_Full'
    countResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/count_Full'
          examples:
            response:
              value:
                count: 241
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--|:--|:-|

        |  Information & Settings | modify | `store_v2_information` | 

        |  Information & Settings | read-only | `store_v2_information_read_only`
        |


        ### Authentication header


        | Header | Argument | Description |

        |:-|:|:|

        | `X-Auth-Token` | `access_token` | For more about API accounts that
        generate `access_token`s, see our [Guide to API
        Accounts](/docs/start/authentication/api-accounts). |


        ### Further reading


        For example requests and more information about authenticating
        BigCommerce APIs, see [Authentication and Example
        Requests](/docs/start/authentication#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API
        Accounts](/docs/start/authentication/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status
        Codes](/docs/start/about/status-codes).
      type: apiKey
      in: header
  schemas:
    country_Full:
      title: country_Full
      example:
        id: 13
        country: Australia
        country_iso2: AU
        country_iso3: AUS
        states:
          url: >-
            https://api.bigcommerce.com/stores/{store_hash}/v2/countries/13/states
          resource: /countries/13/states
      allOf:
        - type: object
          properties:
            id:
              type: integer
              description: Id of the country.
              example: 13
        - $ref: '#/components/schemas/country_Base'
        - type: object
          properties:
            states:
              $ref: '#/components/schemas/countriesStates_Full'
      x-internal: false
    countriesStates_Full:
      title: countriesStates_Full
      type: object
      properties:
        url:
          description: ''
          example: >-
            https://api.bigcommerce.com/stores/{store_hash}/v2/countries/13/states
          type: string
        resource:
          description: ''
          example: /countries/13/states
          type: string
      description: Refers to the `states` object return in `GET` countries requests.
      x-internal: false
    countriesState_Full:
      title: countriesState_Full
      example:
        id: 208
        state: Australian Capital Territory
        state_abbreviation: ACT
        country_id: 13
      type: object
      properties:
        id:
          description: Numeric ID of the state/province.
          example: 208
          type: integer
        state:
          description: Name of the state/province.
          example: Australian Capital Territory
          type: string
        state_abbreviation:
          description: Abbreviation for the state/province.
          example: ACT
          type: string
        country_id:
          description: Numeric ID of the state’s/province’s associated country.
          example: 13
          type: integer
      description: 'Refers to the state returned in `GET` states requests. '
      x-internal: false
    country_Base:
      type: object
      title: country_Base
      properties:
        country:
          type: string
          example: Australia
          description: Country name.
        country_iso2:
          type: string
          description: 2-letter country code.
          example: AU
        country_iso3:
          type: string
          description: 3-letter country code.
          example: AUS
      x-internal: false
    count_Full:
      type: object
      properties:
        count:
          type: integer
          minimum: 1
      x-internal: false