--- title: Country description: >- Manage the country and provincial tax rates that are applied to applicable items at checkout. api_version: 2026-07 source_url: html: 'https://shopify.dev/docs/api/admin-rest/latest/resources/country' md: 'https://shopify.dev/docs/api/admin-rest/latest/resources/country.md' api_name: admin-rest api_type: rest --- The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql). For details and migration steps, visit our [migration guide](https://shopify.dev/docs/apps/build/graphql/migrate). # Country **Multiple access scopes needed — refer to each endpoint for access scope requirements.:** **Important:** The REST Country API is deprecated as of version 2024-07. Please refer to the documentation for each individual endpoint and the [developer changelog](https://shopify.dev/changelog/deprecation-notice-country-and-province-endpoints-in-admin-rest-api) for more information. The Country resource represents the tax rates applied to orders from the different countries where a shop sells its products. ![](https://shopify.dev/assets/api/reference/country.png) Merchants select the countries where they sell their products when they set up their shipping zones and rates on the **Shipping** 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 **Taxes** page. The Country resource lets you access the countries and tax rates set up by the merchant. The countries list includes a default entry called **Rest of World**, which represents all non-specified countries. 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. For more information on managing tax rates for sub-regions of a country, such as states or provinces, see the [Province](https://shopify.dev/docs/admin-api/rest/reference/store-properties/province) resource. **Caution:** As of version 2020-10, you can no longer create or update custom tax values for the Country resource. \# ## Endpoints * [post](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#post-countries) [/admin/api/latest/countries.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#post-countries) Creates a country **deprecated** * [get](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#get-countries) [/admin/api/latest/countries.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#get-countries) Retrieves a list of countries **deprecated** * [get](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#get-countries-country-id) [/admin/api/latest/countries/{country\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#get-countries-country-id) Retrieves a specific country **deprecated** * [get](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#get-countries-count) [/admin/api/latest/countries/count.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#get-countries-count) Retrieves a count of countries **deprecated** * [put](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#put-countries-country-id) [/admin/api/latest/countries/{country\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#put-countries-country-id) Updates an existing country **deprecated** * [del](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#delete-countries-country-id) [/admin/api/latest/countries/{country\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/country.md#delete-countries-country-id) Deletes a country **deprecated** *** ## The Country resource ### Properties *** code **deprecated** The two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format). *** id **deprecated** 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. *** name **deprecated** The full name of the country in English. *** provinces **deprecated** The sub-regions of a country, such as its provinces or states. Each sub-region has the following properties: * **code**: The two letter province or state code. * **country\_id**: The ID for the country to which this sub-region belongs. * **id**: The ID for the particular sub-region. * **name**: The name of the sub-region. * **tax**: The tax value in decimal format. * **tax\_name**: 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. * **tax\_type**: The tax type. Valid values: `null`, `normal`, or `harmonized`. If the value is `harmonized`, then the tax is compounded of the provincial and federal sales taxes. * **tax\_percentage**: The tax value in percent format. *** tax **deprecated** The national sales tax rate applied to orders made by customers from that country. *** {} ## The Country resource ```json { "code": "CA", "id": 879921427, "name": "Canada", "provinces": [ { "code": "ON", "country_id": 879921427, "id": 205434194, "name": "Ontario", "tax": 0.13, "tax_name": "HST", "tax_type": "harmonized", "tax_percentage": 13 } ], "tax": 0.05 } ``` *** ## postCreates a country**deprecated** **Requires \`shipping\` access scope.:** **Important:** This endpoint is deprecated as of 2024-07. **Caution:** As of version 2020-10, the tax field is deprecated. Creates a country. ### Parameters *** api\_version **string** **required** *** ### Examples ### Create a country using Shopify's tax rate for it ### Request body country​ **Country resource** country.code:​"FR" **deprecated** The two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format). ### Create a country using a custom tax rate ### Request body country​ **Country resource** country.code:​"FR" **deprecated** The two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format). country.tax:​0.2 **deprecated** The national sales tax rate applied to orders made by customers from that country. post ## /admin/api/2026-07/countries.​json ```bash curl -d '{"country":{"code":"FR"}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2026-07/countries.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` {} ## Response JSON ```json HTTP/1.1 201 Created { "country": { "id": 980881735, "name": "France", "code": "FR", "tax_name": "TVA", "tax": 0.2, "provinces": [] } } ``` ### examples * #### Create a country using Shopify's tax rate for it ##### ```curl curl -d '{"country":{"code":"FR"}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2026-07/countries.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` #### response ```json HTTP/1.1 201 Created{"country":{"id":980881735,"name":"France","code":"FR","tax_name":"TVA","tax":0.2,"provinces":[]}} ``` * #### Create a country using a custom tax rate ##### ```curl curl -d '{"country":{"code":"FR","tax":0.2}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2026-07/countries.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` *** ## getRetrieves a list of countries**deprecated** **Important:** This endpoint is deprecated as of version 2024-07. Please see the [Countries in shipping zone API](https://shopify.dev/docs/api/admin-graphql/2024-01/objects/CountriesInShippingZones) for a GraphQL alternative. Retrieves a list of countries. ### Parameters *** api\_version **string** **required** *** fields Show only certain fields, specified by a comma-separated list of field names. *** since\_id Restrict results to after the specified ID. *** ### Examples ### Retrieve all countries ### Retrieve all countries after the specified ID ### Query parameters since\_​id=​359115488 Restrict results to after the specified ID. get ## /admin/api/2026-07/countries.​json ```bash curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` {} ## Response JSON ```json 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, "tax": 0.08, "tax_percentage": 8, "shipping_zone_id": null }, { "id": 170405627, "country_id": 879921427, "name": "British Columbia", "code": "BC", "tax_name": null, "tax_type": null, "tax": 0.07, "tax_percentage": 7, "shipping_zone_id": null }, { "id": 342345110, "country_id": 879921427, "name": "Manitoba", ``` ### examples * #### Retrieve all countries ##### ```curl curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` #### response ```json 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,"tax":0.08,"tax_percentage":8,"shipping_zone_id":null},{"id":170405627,"country_id":879921427,"name":"British Columbia","code":"BC","tax_name":null,"tax_type":null,"tax":0.07,"tax_percentage":7,"shipping_zone_id":null},{"id":342345110,"country_id":879921427,"name":"Manitoba","code":"MB","tax_name":null,"tax_type":null,"tax":0.07,"tax_percentage":7,"shipping_zone_id":null},{"id":92264567,"country_id":879921427,"name":"New Brunswick","code":"NB","tax_name":null,"tax_type":null,"tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"id":243284171,"country_id":879921427,"name":"Newfoundland","code":"NL","tax_name":null,"tax_type":null,"tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"id":439598329,"country_id":879921427,"name":"Northwest Territories","code":"NT","tax_name":null,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null},{"id":448070559,"country_id":879921427,"name":"Nova Scotia","code":"NS","tax_name":null,"tax_type":"harmonized","tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"id":670206421,"country_id":879921427,"name":"Nunavut","code":"NU","tax_name":null,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null},{"id":702530425,"country_id":879921427,"name":"Ontario","code":"ON","tax_name":null,"tax_type":null,"tax":0.08,"tax_percentage":8,"shipping_zone_id":null},{"id":570891722,"country_id":879921427,"name":"Prince Edward Island","code":"PE","tax_name":null,"tax_type":null,"tax":0.1,"tax_percentage":10,"shipping_zone_id":null},{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","tax":0.09,"tax_percentage":9,"shipping_zone_id":null},{"id":473391800,"country_id":879921427,"name":"Saskatchewan","code":"SK","tax_name":null,"tax_type":null,"tax":0.09,"tax_percentage":9,"shipping_zone_id":null},{"id":1005264686,"country_id":879921427,"name":"Yukon","code":"YT","tax_name":null,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null}]},{"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,"provinces":[{"id":952629862,"country_id":817138619,"name":"California","code":"CA","tax_name":null,"tax_type":null,"tax":0.05,"tax_percentage":5,"shipping_zone_id":null},{"id":222234158,"country_id":817138619,"name":"Kentucky","code":"KY","tax_name":null,"tax_type":null,"tax":0.06,"tax_percentage":6,"shipping_zone_id":null},{"id":9350860,"country_id":817138619,"name":"Massachusetts","code":"MA","tax_name":null,"tax_type":null,"tax":0.065,"tax_percentage":6.5,"shipping_zone_id":null},{"id":696485510,"country_id":817138619,"name":"Minnesota","code":"MN","tax_name":null,"tax_type":null,"tax":0.065,"tax_percentage":6.5,"shipping_zone_id":null},{"id":753050225,"country_id":817138619,"name":"New Jersey","code":"NJ","tax_name":null,"tax_type":null,"tax":0.06,"tax_percentage":6,"shipping_zone_id":null},{"id":1013111685,"country_id":817138619,"name":"New York","code":"NY","tax_name":null,"tax_type":null,"tax":0.04,"tax_percentage":4,"shipping_zone_id":null},{"id":915134533,"country_id":817138619,"name":"Pennsylvania","code":"PA","tax_name":null,"tax_type":null,"tax":0.05,"tax_percentage":5,"shipping_zone_id":null},{"id":591478044,"country_id":817138619,"name":"Rhode Island","code":"RI","tax_name":null,"tax_type":null,"tax":0.07,"tax_percentage":7,"shipping_zone_id":null}]}]} ``` * #### Retrieve all countries after the specified ID ##### ```curl curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries.json?since_id=359115488" \ -H "X-Shopify-Access-Token: {access_token}" ``` *** ## getRetrieves a specific country**deprecated** **Important:** This endpoint is deprecated as of version 2024-07. Please see the [Countries in shipping zone API](https://shopify.dev/docs/api/admin-graphql/2024-01/objects/CountriesInShippingZones) for a GraphQL alternative. Retrieves a specific country ### Parameters *** api\_version **string** **required** *** country\_id **string** **required** *** fields Show only certain fields, specified by a comma-separated list of field names. *** ### Examples ### Retrieve a specific country by its ID ### Path parameters country\_​id=​879921427 **string** **required** get ## /admin/api/2026-07/countries/879921427.​json ```bash curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` {} ## Response JSON ```json 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, "tax": 0.08, "tax_percentage": 8, "shipping_zone_id": null }, { "id": 170405627, "country_id": 879921427, "name": "British Columbia", "code": "BC", "tax_name": null, "tax_type": null, "tax": 0.07, "tax_percentage": 7, "shipping_zone_id": null }, { "id": 342345110, "country_id": 879921427, "name": "Manitoba", "code": "MB", ``` ### examples * #### Retrieve a specific country by its ID ##### ```curl curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` #### response ```json 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,"tax":0.08,"tax_percentage":8,"shipping_zone_id":null},{"id":170405627,"country_id":879921427,"name":"British Columbia","code":"BC","tax_name":null,"tax_type":null,"tax":0.07,"tax_percentage":7,"shipping_zone_id":null},{"id":342345110,"country_id":879921427,"name":"Manitoba","code":"MB","tax_name":null,"tax_type":null,"tax":0.07,"tax_percentage":7,"shipping_zone_id":null},{"id":92264567,"country_id":879921427,"name":"New Brunswick","code":"NB","tax_name":null,"tax_type":null,"tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"id":243284171,"country_id":879921427,"name":"Newfoundland","code":"NL","tax_name":null,"tax_type":null,"tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"id":439598329,"country_id":879921427,"name":"Northwest Territories","code":"NT","tax_name":null,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null},{"id":448070559,"country_id":879921427,"name":"Nova Scotia","code":"NS","tax_name":null,"tax_type":"harmonized","tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"id":670206421,"country_id":879921427,"name":"Nunavut","code":"NU","tax_name":null,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null},{"id":702530425,"country_id":879921427,"name":"Ontario","code":"ON","tax_name":null,"tax_type":null,"tax":0.08,"tax_percentage":8,"shipping_zone_id":null},{"id":570891722,"country_id":879921427,"name":"Prince Edward Island","code":"PE","tax_name":null,"tax_type":null,"tax":0.1,"tax_percentage":10,"shipping_zone_id":null},{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","tax":0.09,"tax_percentage":9,"shipping_zone_id":null},{"id":473391800,"country_id":879921427,"name":"Saskatchewan","code":"SK","tax_name":null,"tax_type":null,"tax":0.09,"tax_percentage":9,"shipping_zone_id":null},{"id":1005264686,"country_id":879921427,"name":"Yukon","code":"YT","tax_name":null,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null}]}} ``` *** ## getRetrieves a count of countries**deprecated** **Important:** This endpoint is deprecated as of 2024-07. Please see the [Countries in shipping zone API](https://shopify.dev/docs/api/admin-graphql/2024-01/objects/CountriesInShippingZones) for a GraphQL alternative. Retrieves a count of countries. ### Parameters *** api\_version **string** **required** *** ### Examples ### Count all countries get ## /admin/api/2026-07/countries/count.​json ```bash curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/count.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` {} ## Response JSON ```json HTTP/1.1 200 OK { "count": 3 } ``` ### examples * #### Count all countries ##### ```curl curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/count.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` #### response ```json HTTP/1.1 200 OK{"count":3} ``` *** ## putUpdates an existing country**deprecated** **Requires \`shipping\` access scope.:** **Important:** This endpoint is deprecated as of 2024-07. Please see the [Countries in shipping zone API](https://shopify.dev/docs/api/admin-graphql/2024-01/objects/CountriesInShippingZones) for a GraphQL alternative. **Caution:** As of version 2020-10, the tax field is deprecated. Updates an existing country. ### Parameters *** api\_version **string** **required** *** country\_id **string** **required** *** ### Examples ### Update a country's tax rate ### Path parameters country\_​id=​879921427 **string** **required** ### Request body country​ **Country resource** country.id:​879921427 **deprecated** 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. country.tax:​0.05 **deprecated** The national sales tax rate applied to orders made by customers from that country. put ## /admin/api/2026-07/countries/879921427.​json ```bash curl -d '{"country":{"id":879921427,"tax":0.05}}' \ -X PUT "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` {} ## Response JSON ```json HTTP/1.1 200 OK { "country": { "name": "Canada", "code": "CA", "id": 879921427, "tax_name": "GST", "tax": 0.05, "provinces": [ { "country_id": 879921427, "tax_name": "Tax", "name": "Alberta", "code": "AB", "id": 205434194, "tax_type": null, "tax": 0.08, "tax_percentage": 8, "shipping_zone_id": null }, { "country_id": 879921427, "tax_name": "Tax", "name": "British Columbia", "code": "BC", "id": 170405627, "tax_type": null, "tax": 0.07, "tax_percentage": 7, "shipping_zone_id": null }, { "country_id": 879921427, "tax_name": "Tax", "name": "Manitoba", "code": "MB", ``` ### examples * #### Update a country's tax rate ##### ```curl curl -d '{"country":{"id":879921427,"tax":0.05}}' \ -X PUT "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` #### response ```json HTTP/1.1 200 OK{"country":{"name":"Canada","code":"CA","id":879921427,"tax_name":"GST","tax":0.05,"provinces":[{"country_id":879921427,"tax_name":"Tax","name":"Alberta","code":"AB","id":205434194,"tax_type":null,"tax":0.08,"tax_percentage":8,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"British Columbia","code":"BC","id":170405627,"tax_type":null,"tax":0.07,"tax_percentage":7,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"Manitoba","code":"MB","id":342345110,"tax_type":null,"tax":0.07,"tax_percentage":7,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"New Brunswick","code":"NB","id":92264567,"tax_type":null,"tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"Newfoundland","code":"NL","id":243284171,"tax_type":null,"tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"Northwest Territories","code":"NT","id":439598329,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"Nova Scotia","code":"NS","id":448070559,"tax_type":"harmonized","tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"Nunavut","code":"NU","id":670206421,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"Ontario","code":"ON","id":702530425,"tax_type":null,"tax":0.08,"tax_percentage":8,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"Prince Edward Island","code":"PE","id":570891722,"tax_type":null,"tax":0.1,"tax_percentage":10,"shipping_zone_id":null},{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","tax":0.09,"tax_percentage":9,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"Saskatchewan","code":"SK","id":473391800,"tax_type":null,"tax":0.09,"tax_percentage":9,"shipping_zone_id":null},{"country_id":879921427,"tax_name":"Tax","name":"Yukon","code":"YT","id":1005264686,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null}]}} ``` *** ## delDeletes a country**deprecated** **Requires \`shipping\` access scope.:** **Important:** This endpoint is deprecated as of version 2024-07. ### Parameters *** api\_version **string** **required** *** country\_id **string** **required** *** ### Examples ### Delete a country ### Path parameters country\_​id=​879921427 **string** **required** del ## /admin/api/2026-07/countries/879921427.​json ```bash curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` {} ## Response JSON ```json HTTP/1.1 200 OK {} ``` ### examples * #### Delete a country ##### ```curl curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` #### response ```json HTTP/1.1 200 OK{} ```