openapi: 3.1.0
info:
  title: 'Admin Management: Geography'
  version: 1.0.0
paths:
  /stores/{store_hash}/v2/countries:
    get:
      operationId: getCountries
      summary: List Countries
      description: Get a list of all countries available. A country or territory, identifiable by an ISO 3166 country code.
      tags:
        - countries
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: Number of pages.
          required: false
          schema:
            type: number
            format: double
        - name: limit
          in: query
          description: Count per page.
          required: false
          schema:
            type: number
            format: double
        - name: country
          in: query
          required: false
          schema:
            type: string
        - name: country_iso2
          in: query
          required: false
          schema:
            type: string
        - name: country_iso3
          in: query
          required: false
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


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


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


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: ''
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/country_Full'
  /stores/{store_hash}/v2/countries/{id}:
    get:
      operationId: getCountry
      summary: Get Country
      description: Returns a single *Country*.  Gets a country. A country or territory, identifiable by an ISO 3166 country code.
      tags:
        - countries
      parameters:
        - name: id
          in: path
          description: The ID of the country.
          required: true
          schema:
            type: integer
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


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


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


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: ''
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/country_Full'
  /stores/{store_hash}/v2/countries/count:
    get:
      operationId: getCountriesCount
      summary: Get Count of Countries
      description: Returns a count of all countries.
      tags:
        - countries
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


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


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


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/count_Full'
  /stores/{store_hash}/v2/countries/{country_id}/states:
    get:
      operationId: getCountryStates
      summary: List Countryʼs States
      description: |-
        Returns a list of *States* belonging to a *Country*. 
        A state or province, identifiable by an ISO 3166 subdivision code.
      tags:
        - states
      parameters:
        - name: country_id
          in: path
          description: Id of the country
          required: true
          schema:
            type: integer
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: state
          in: query
          description: Name of the state/province.
          required: false
          schema:
            type: string
        - name: state_abbreviation
          in: query
          description: Abbreviation for the state/province.
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: Number of pages.
          required: false
          schema:
            type: number
            format: double
        - name: limit
          in: query
          description: Count per page.
          required: false
          schema:
            type: number
            format: double
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


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


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


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: ''
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/countriesState_Full'
  /stores/{store_hash}/v2/countries/{country_id}/states/{id}:
    get:
      operationId: getCountryState
      summary: Get Countryʼs State
      description: |-
        Returns a *State*. 
        A state or province, identifiable by an ISO 3166 subdivision code.
      tags:
        - states
      parameters:
        - name: country_id
          in: path
          description: Id of the country
          required: true
          schema:
            type: integer
        - name: id
          in: path
          description: Id of the states
          required: true
          schema:
            type: integer
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


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


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


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: ''
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/countriesState_Full'
  /stores/{store_hash}/v2/countries/states/count:
    get:
      operationId: getStatesCount
      summary: Get Count of States
      description: Returns a count of all states.
      tags:
        - states
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


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


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


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/count_Full'
  /stores/{store_hash}/v2/countries/states:
    get:
      operationId: getStates
      summary: List States
      description: Returns a list of all states.
      tags:
        - states
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: The number of results to return per request.
          required: false
          schema:
            type: integer
        - name: page
          in: query
          description: The ordered grouping of results to return.
          required: false
          schema:
            type: integer
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


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


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


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/countriesState_Full'
  /stores/{store_hash}/v2/countries/{country_id}/states/count:
    get:
      operationId: getCountryStatesCount
      summary: Get Count of Country’s States
      description: Returns a count of a countryʼs states.
      tags:
        - states
      parameters:
        - name: country_id
          in: path
          required: true
          schema:
            type: integer
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


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


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


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/count_Full'
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    countriesStates_Full:
      type: object
      properties:
        url:
          type: string
        resource:
          type: string
      description: Refers to the `states` object return in `GET` countries requests.
      title: countriesStates_Full
    country_Full:
      type: object
      properties:
        country:
          type: string
          description: Country name.
        country_iso2:
          type: string
          description: 2-letter country code.
        country_iso3:
          type: string
          description: 3-letter country code.
        id:
          type: integer
          description: Id of the country.
        states:
          $ref: '#/components/schemas/countriesStates_Full'
      title: country_Full
    count_Full:
      type: object
      properties:
        count:
          type: integer
      title: count_Full
    countriesState_Full:
      type: object
      properties:
        id:
          type: integer
          description: Numeric ID of the state/province.
        state:
          type: string
          description: Name of the state/province.
        state_abbreviation:
          type: string
          description: Abbreviation for the state/province.
        country_id:
          type: integer
          description: Numeric ID of the state’s/province’s associated country.
      description: 'Refers to the state returned in `GET` states requests. '
      title: countriesState_Full
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


        ### Further reading


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


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


        For a list of API status codes, see [API Status
        Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
