# Country

<div class='note note-caution'>
  <h4>Important</h4>
  <p>The REST Country API is deprecated as of version 2024-07.</p>
  <p>Please refer to the documentation for each individual endpoint and the <a href="https://shopify.dev/changelog/deprecation-notice-country-and-province-endpoints-in-admin-rest-api">developer changelog</a> for more information.</p>
</div>
<p>The Country resource represents the tax rates applied to orders from the different countries where a shop sells its products.</p>
{{ '/api/reference/country.png' | image }}
<p>Merchants select the countries where they sell their products when they set up their shipping zones and rates on the <strong>Shipping</strong> page of the Shopify admin. After adding a country to a shipping zone, store owners can then verify and adjust tax rates for each country on the <strong>Taxes</strong> page.</p>
<p>The Country resource lets you access the countries and tax rates set up by the merchant. The countries list includes a default entry called <strong>Rest of World</strong>, which represents all non-specified countries.</p>
<p>You can use the Country resource to modify the sales tax rate for a country or sub-region to account for surtaxes or exemptions that apply to the store.</p>
<p>For more information on managing tax rates for sub-regions of a country, such as states or provinces, see the <a href="/docs/admin-api/rest/reference/store-properties/province">Province</a> resource.</p>
<div class="note-caution note">
  <h4>Caution</h4>
  <p>As of version 2020-10, you can no longer create or update custom tax values for the Country resource.</p>
</div>

## Resource Properties

### Country

* code: The two-letter country code (<a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166-1 alpha-2</a> format).
  * Type: x-string
  * Example: "CA"
* id: The ID for the country. The ID for a country is unique across all Shopify stores. The ID for a country in one shop will be different from the same country in another shop. 
  * Type: x-string
  * Example: 879921427
* name: The full name of the country in English.
  * Type: x-string
  * Example: "Canada"
* provinces:         <p>The sub-regions of a country, such as its provinces or states. Each sub-region has the following properties:</p>
        <ul>
          <li><strong>code</strong>: The two letter province or state code.</li>
          <li><strong>country_id</strong>: The ID for the country to which this sub-region belongs.</li>
          <li><strong>id</strong>: The ID for the particular sub-region.</li>
          <li><strong>name</strong>: The name of the sub-region.</li>
          <li><strong>tax</strong>: The tax value in decimal format.</li>
          <li><strong>tax_name</strong>: The name of the tax as it is referred to in the applicable sub-region. For example, in Canada, the sales tax in the province Ontario is referred to as HST.</li>
          <li><strong>tax_type</strong>: The tax type. Valid values: <code>null</code>, <code>normal</code>, or <code>harmonized</code>. If the value is <code>harmonized</code>, then the tax is compounded of the provincial and federal sales taxes.</li>
          <li><strong>tax_percentage</strong>: The tax value in percent format.</li>
        </ul>

  * Type: x-string
  * Example: [{"code"=>"ON", "country_id"=>879921427, "id"=>205434194, "name"=>"Ontario", "tax"=>0.13, "tax_name"=>"HST", "tax_type"=>"harmonized", "tax_percentage"=>13}]
* tax: The national sales tax rate applied to orders made by customers from that country.
  * Type: x-string
  * Example: 0.05
## Retrieves a list of countries

<div class='note note-caution'>
  <h4>Important</h4>
  <p>This endpoint is deprecated as of version 2024-07.</p>
  <p>Please see the <a href="https://shopify.dev/docs/api/admin-graphql/2024-01/objects/CountriesInShippingZones">Countries in shipping zone API</a> for a GraphQL alternative.</p>
</div>
<p>Retrieves a list of countries.</p>

### Endpoint
/admin/api/#{api_version}/countries.json (GET)

### Parameters
* api_version (required): 
* fields: Show only certain fields, specified by a comma-separated list of field names.
* since_id: Restrict results to after the specified ID.

### Responses
#### 200
Retrieves a list of countries

Examples:
##### Retrieve all countries
Request:
```
GET /admin/api/unstable/countries.json
```

Response:
```
HTTP/1.1 200 OK
{"countries":[{"id":879921427,"name":"Canada","code":"CA","tax_name":"GST","tax":0.05,"provinces":[{"id":205434194,"country_id":879921427,"name":"Alberta","code":"AB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"id":170405627,"country_id":879921427,"name":"British Columbia","code":"BC","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0},{"id":342345110,"country_id":879921427,"name":"Manitoba","code":"MB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0},{"id":92264567,"country_id":879921427,"name":"New Brunswick","code":"NB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":243284171,"country_id":879921427,"name":"Newfoundland","code":"NL","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":439598329,"country_id":879921427,"name":"Northwest Territories","code":"NT","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"id":448070559,"country_id":879921427,"name":"Nova Scotia","code":"NS","tax_name":null,"tax_type":"harmonized","shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":670206421,"country_id":879921427,"name":"Nunavut","code":"NU","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"id":702530425,"country_id":879921427,"name":"Ontario","code":"ON","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"id":570891722,"country_id":879921427,"name":"Prince Edward Island","code":"PE","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.1,"tax_percentage":10.0},{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0},{"id":473391800,"country_id":879921427,"name":"Saskatchewan","code":"SK","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0},{"id":1005264686,"country_id":879921427,"name":"Yukon","code":"YT","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0}]},{"id":359115488,"name":"Colombia","code":"CO","tax_name":"VAT","tax":0.15,"provinces":[]},{"id":817138619,"name":"United States","code":"US","tax_name":"Federal Tax","tax":0.0,"provinces":[{"id":952629862,"country_id":817138619,"name":"California","code":"CA","tax_name":null,"tax_type":null,"shipping_zone_id":1039932365,"tax":0.05,"tax_percentage":5.0},{"id":222234158,"country_id":817138619,"name":"Kentucky","code":"KY","tax_name":null,"tax_type":null,"shipping_zone_id":1039932365,"tax":0.06,"tax_percentage":6.0},{"id":9350860,"country_id":817138619,"name":"Massachusetts","code":"MA","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.065,"tax_percentage":6.5},{"id":696485510,"country_id":817138619,"name":"Minnesota","code":"MN","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.065,"tax_percentage":6.5},{"id":753050225,"country_id":817138619,"name":"New Jersey","code":"NJ","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.06,"tax_percentage":6.0},{"id":1013111685,"country_id":817138619,"name":"New York","code":"NY","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.04,"tax_percentage":4.0},{"id":915134533,"country_id":817138619,"name":"Pennsylvania","code":"PA","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.05,"tax_percentage":5.0},{"id":591478044,"country_id":817138619,"name":"Rhode Island","code":"RI","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0}]}]}
```
##### Retrieve all countries after the specified ID
Request:
```
GET /admin/api/unstable/countries.json
```

Response:
```
HTTP/1.1 200 OK
{"countries":[{"id":817138619,"name":"United States","code":"US","tax_name":"Federal Tax","tax":0.0,"provinces":[{"id":952629862,"country_id":817138619,"name":"California","code":"CA","tax_name":null,"tax_type":null,"shipping_zone_id":1039932365,"tax":0.05,"tax_percentage":5.0},{"id":222234158,"country_id":817138619,"name":"Kentucky","code":"KY","tax_name":null,"tax_type":null,"shipping_zone_id":1039932365,"tax":0.06,"tax_percentage":6.0},{"id":9350860,"country_id":817138619,"name":"Massachusetts","code":"MA","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.065,"tax_percentage":6.5},{"id":696485510,"country_id":817138619,"name":"Minnesota","code":"MN","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.065,"tax_percentage":6.5},{"id":753050225,"country_id":817138619,"name":"New Jersey","code":"NJ","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.06,"tax_percentage":6.0},{"id":1013111685,"country_id":817138619,"name":"New York","code":"NY","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.04,"tax_percentage":4.0},{"id":915134533,"country_id":817138619,"name":"Pennsylvania","code":"PA","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.05,"tax_percentage":5.0},{"id":591478044,"country_id":817138619,"name":"Rhode Island","code":"RI","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0}]},{"id":879921427,"name":"Canada","code":"CA","tax_name":"GST","tax":0.05,"provinces":[{"id":205434194,"country_id":879921427,"name":"Alberta","code":"AB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"id":170405627,"country_id":879921427,"name":"British Columbia","code":"BC","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0},{"id":342345110,"country_id":879921427,"name":"Manitoba","code":"MB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0},{"id":92264567,"country_id":879921427,"name":"New Brunswick","code":"NB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":243284171,"country_id":879921427,"name":"Newfoundland","code":"NL","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":439598329,"country_id":879921427,"name":"Northwest Territories","code":"NT","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"id":448070559,"country_id":879921427,"name":"Nova Scotia","code":"NS","tax_name":null,"tax_type":"harmonized","shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":670206421,"country_id":879921427,"name":"Nunavut","code":"NU","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"id":702530425,"country_id":879921427,"name":"Ontario","code":"ON","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"id":570891722,"country_id":879921427,"name":"Prince Edward Island","code":"PE","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.1,"tax_percentage":10.0},{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0},{"id":473391800,"country_id":879921427,"name":"Saskatchewan","code":"SK","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0},{"id":1005264686,"country_id":879921427,"name":"Yukon","code":"YT","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0}]}]}
```
## Creates a country

<div class='note note-caution'>
  <h4>Important</h4>
  <p>This endpoint is deprecated as of 2024-07.</p>
</div>
<aside class="note caution">
  <h4>Caution</h4>
  <p>As of version 2020-10, the tax field is deprecated.</p>
</aside>
Creates a country.

### Endpoint
/admin/api/#{api_version}/countries.json (POST)

### Parameters
* api_version (required): 

### Responses
#### 201
Creates a country

Examples:
##### Create a country using Shopify's tax rate for it
Request:
```
POST /admin/api/unstable/countries.json
{"country":{"code":"FR"}}
```

Response:
```
HTTP/1.1 201 Created
{"country":{"id":980881734,"name":"France","code":"FR","tax_name":"TVA","tax":0.2,"provinces":[]}}
```
##### Create a country using a custom tax rate 
Request:
```
POST /admin/api/unstable/countries.json
{"country":{"code":"FR","tax":0.2}}
```

Response:
```
HTTP/1.1 201 Created
{"country":{"id":980881733,"name":"France","code":"FR","tax_name":"TVA","tax":0.2,"provinces":[]}}
```
## Retrieves a count of countries

<div class='note note-caution'>
  <h4>Important</h4>
  <p>This endpoint is deprecated as of 2024-07.</p>
  <p>Please see the <a href="https://shopify.dev/docs/api/admin-graphql/2024-01/objects/CountriesInShippingZones">Countries in shipping zone API</a> for a GraphQL alternative.</p>
</div>
<p>Retrieves a count of countries.</p>

### Endpoint
/admin/api/#{api_version}/countries/count.json (GET)

### Parameters
* api_version (required): 

### Responses
#### 200
Retrieves a count of countries

Examples:
##### Count all countries
Request:
```
GET /admin/api/unstable/countries/count.json
```

Response:
```
HTTP/1.1 200 OK
{"count":3}
```
## Retrieves a specific country

<div class='note note-caution'>
  <h4>Important</h4>
  <p>This endpoint is deprecated as of version 2024-07.</p>
  <p>Please see the <a href="https://shopify.dev/docs/api/admin-graphql/2024-01/objects/CountriesInShippingZones">Countries in shipping zone API</a> for a GraphQL alternative.</p>
</div>
<p>Retrieves a specific country</p>

### Endpoint
/admin/api/#{api_version}/countries/{country_id}.json (GET)

### Parameters
* api_version (required): 
* country_id (required): 
* fields: Show only certain fields, specified by a comma-separated list of field names.

### Responses
#### 200
Retrieves a specific country

Examples:
##### Retrieve a specific country by its ID
Request:
```
GET /admin/api/unstable/countries/879921427.json
```

Response:
```
HTTP/1.1 200 OK
{"country":{"id":879921427,"name":"Canada","code":"CA","tax_name":"GST","tax":0.05,"provinces":[{"id":205434194,"country_id":879921427,"name":"Alberta","code":"AB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"id":170405627,"country_id":879921427,"name":"British Columbia","code":"BC","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0},{"id":342345110,"country_id":879921427,"name":"Manitoba","code":"MB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0},{"id":92264567,"country_id":879921427,"name":"New Brunswick","code":"NB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":243284171,"country_id":879921427,"name":"Newfoundland","code":"NL","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":439598329,"country_id":879921427,"name":"Northwest Territories","code":"NT","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"id":448070559,"country_id":879921427,"name":"Nova Scotia","code":"NS","tax_name":null,"tax_type":"harmonized","shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":670206421,"country_id":879921427,"name":"Nunavut","code":"NU","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"id":702530425,"country_id":879921427,"name":"Ontario","code":"ON","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"id":570891722,"country_id":879921427,"name":"Prince Edward Island","code":"PE","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.1,"tax_percentage":10.0},{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0},{"id":473391800,"country_id":879921427,"name":"Saskatchewan","code":"SK","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0},{"id":1005264686,"country_id":879921427,"name":"Yukon","code":"YT","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0}]}}
```
## Updates an existing country

<div class='note note-caution'>
  <h4>Important</h4>
  <p>This endpoint is deprecated as of 2024-07.</p>
  <p>Please see the <a href="https://shopify.dev/docs/api/admin-graphql/2024-01/objects/CountriesInShippingZones">Countries in shipping zone API</a> for a GraphQL alternative.</p>
</div>
<aside class="note caution">
  <h4>Caution</h4>
  <p>As of version 2020-10, the tax field is deprecated.</p>
</aside>
Updates an existing country.

### Endpoint
/admin/api/#{api_version}/countries/{country_id}.json (PUT)

### Parameters
* api_version (required): 
* country_id (required): 

### Responses
#### 200
Updates an existing country

Examples:
##### Update a country's tax rate
Request:
```
PUT /admin/api/unstable/countries/879921427.json
{"country":{"id":879921427,"tax":0.05}}
```

Response:
```
HTTP/1.1 200 OK
{"country":{"id":879921427,"name":"Canada","code":"CA","tax_name":"GST","tax":0.05,"provinces":[{"country_id":879921427,"tax_name":"Tax","id":205434194,"name":"Alberta","code":"AB","tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"country_id":879921427,"tax_name":"Tax","id":170405627,"name":"British Columbia","code":"BC","tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0},{"country_id":879921427,"tax_name":"Tax","id":342345110,"name":"Manitoba","code":"MB","tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0},{"country_id":879921427,"tax_name":"Tax","id":92264567,"name":"New Brunswick","code":"NB","tax_type":null,"shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"country_id":879921427,"tax_name":"Tax","id":243284171,"name":"Newfoundland","code":"NL","tax_type":null,"shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"country_id":879921427,"tax_name":"Tax","id":439598329,"name":"Northwest Territories","code":"NT","tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"country_id":879921427,"tax_name":"Tax","id":448070559,"name":"Nova Scotia","code":"NS","tax_type":"harmonized","shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"country_id":879921427,"tax_name":"Tax","id":670206421,"name":"Nunavut","code":"NU","tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"country_id":879921427,"tax_name":"Tax","id":702530425,"name":"Ontario","code":"ON","tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"country_id":879921427,"tax_name":"Tax","id":570891722,"name":"Prince Edward Island","code":"PE","tax_type":null,"shipping_zone_id":null,"tax":0.1,"tax_percentage":10.0},{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0},{"country_id":879921427,"tax_name":"Tax","id":473391800,"name":"Saskatchewan","code":"SK","tax_type":null,"shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0},{"country_id":879921427,"tax_name":"Tax","id":1005264686,"name":"Yukon","code":"YT","tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0}]}}
```
## Deletes a country

<div class='note note-caution'>
  <h4>Important</h4>
  <p>This endpoint is deprecated as of version 2024-07.</p>
</div>

### Endpoint
/admin/api/#{api_version}/countries/{country_id}.json (DELETE)

### Parameters
* api_version (required): 
* country_id (required): 

### Responses
#### 200
Deletes a country

Examples:
##### Delete a country
Request:
```
DELETE /admin/api/unstable/countries/879921427.json
```

Response:
```
HTTP/1.1 200 OK
{}
```