The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Anchor to section titled 'undefined'

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 for more information.

The Country resource represents the tax rates applied to orders from the different countries where a shop sells its products.

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 resource.

Caution

As of version 2020-10, you can no longer create or update custom tax values for the Country resource.

Was this section helpful?
#Endpoints
Anchor to section titled 'The Country resource'

The Country resource

Properties
code
deprecated
The two-letter country code (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:

tax
deprecated
The national sales tax rate applied to orders made by customers from that country.
Was this section helpful?
{}The Country resource
{
  "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
}
Anchor to section titled 'POST request, Creates a country'

post
Creates a country
deprecated

Requires shipping access scope.

Important

This endpoint is deprecated as of 2024-07.

Creates a country.
Anchor to section titled 'Parameters of Creates a country'

Parameters

api_version
string
required
Was this section helpful?
Anchor to section titled 'Examples of Creates a country'

Examples

Request body
country
Country resource
Was this section helpful?
post
/admin/api/2024-10/countries.json
Copy
curl -d '{"country":{"code":"FR"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-10/countries.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 201 Created
{
  "country": {
    "id": 1070231511,
    "name": "France",
    "code": "FR",
    "tax_name": "TVA",
    "tax": 0.2,
    "provinces": []
  }
}
Anchor to section titled 'GET request, Retrieves a list of countries'

get
Retrieves a list of countries
deprecated

Important

This endpoint is deprecated as of version 2024-07.

Please see the Countries in shipping zone API for a GraphQL alternative.

Retrieves a list of countries.

Anchor to section titled 'Parameters of 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.
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a list of countries'

Examples

Was this section helpful?
get
/admin/api/2024-10/countries.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/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,
          "shipping_zone_id": null,
          "tax": 0.08,
          "tax_percentage": 8
        },
        {
          "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
        },
        {
          "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
        },
        {
          "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
        },
        {
          "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
        },
        {
          "id": 439598329,
          "country_id": 879921427,
          "name": "Northwest Territories",
          "code": "NT",
          "tax_name": null,
          "tax_type": null,
          "shipping_zone_id": null,
          "tax": 0,
          "tax_percentage": 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
        },
        {
          "id": 670206421,
          "country_id": 879921427,
          "name": "Nunavut",
          "code": "NU",
          "tax_name": null,
          "tax_type": null,
          "shipping_zone_id": null,
          "tax": 0,
          "tax_percentage": 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
        },
        {
          "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
        },
        {
          "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
        },
        {
          "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
        },
        {
          "id": 1005264686,
          "country_id": 879921427,
          "name": "Yukon",
          "code": "YT",
          "tax_name": null,
          "tax_type": null,
          "shipping_zone_id": null,
          "tax": 0,
          "tax_percentage": 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,
      "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
        },
        {
          "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
        },
        {
          "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
        },
        {
          "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
        },
        {
          "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
        },
        {
          "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
        }
      ]
    }
  ]
}
Anchor to section titled 'GET request, Retrieves a specific country'

get
Retrieves a specific country
deprecated

Important

This endpoint is deprecated as of version 2024-07.

Please see the Countries in shipping zone API for a GraphQL alternative.

Retrieves a specific country

Anchor to section titled 'Parameters of 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.
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a specific country'

Examples

Path parameters
countryid=879921427
string
required
Was this section helpful?
get
/admin/api/2024-10/countries/879921427.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/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,
        "shipping_zone_id": null,
        "tax": 0.08,
        "tax_percentage": 8
      },
      {
        "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
      },
      {
        "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
      },
      {
        "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
      },
      {
        "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
      },
      {
        "id": 439598329,
        "country_id": 879921427,
        "name": "Northwest Territories",
        "code": "NT",
        "tax_name": null,
        "tax_type": null,
        "shipping_zone_id": null,
        "tax": 0,
        "tax_percentage": 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
      },
      {
        "id": 670206421,
        "country_id": 879921427,
        "name": "Nunavut",
        "code": "NU",
        "tax_name": null,
        "tax_type": null,
        "shipping_zone_id": null,
        "tax": 0,
        "tax_percentage": 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
      },
      {
        "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
      },
      {
        "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
      },
      {
        "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
      },
      {
        "id": 1005264686,
        "country_id": 879921427,
        "name": "Yukon",
        "code": "YT",
        "tax_name": null,
        "tax_type": null,
        "shipping_zone_id": null,
        "tax": 0,
        "tax_percentage": 0
      }
    ]
  }
}
Anchor to section titled 'GET request, Retrieves a count of countries'

get
Retrieves a count of countries
deprecated

Important

This endpoint is deprecated as of 2024-07.

Please see the Countries in shipping zone API for a GraphQL alternative.

Retrieves a count of countries.

Anchor to section titled 'Parameters of Retrieves a count of countries'

Parameters

api_version
string
required
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a count of countries'

Examples

Was this section helpful?
get
/admin/api/2024-10/countries/count.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/countries/count.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "count": 3
}
Anchor to section titled 'PUT request, Updates an existing country'

put
Updates 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 for a GraphQL alternative.

Updates an existing country.
Anchor to section titled 'Parameters of Updates an existing country'

Parameters

api_version
string
required
country_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Updates an existing country'

Examples

Path parameters
countryid=879921427
string
required
Request body
country
Country resource
Was this section helpful?
put
/admin/api/2024-10/countries/879921427.json
Copy
curl -d '{"country":{"id":879921427,"tax":0.05}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2024-10/countries/879921427.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
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
      },
      {
        "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
      },
      {
        "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
      },
      {
        "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
      },
      {
        "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
      },
      {
        "country_id": 879921427,
        "tax_name": "Tax",
        "id": 439598329,
        "name": "Northwest Territories",
        "code": "NT",
        "tax_type": null,
        "shipping_zone_id": null,
        "tax": 0,
        "tax_percentage": 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
      },
      {
        "country_id": 879921427,
        "tax_name": "Tax",
        "id": 670206421,
        "name": "Nunavut",
        "code": "NU",
        "tax_type": null,
        "shipping_zone_id": null,
        "tax": 0,
        "tax_percentage": 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
      },
      {
        "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
      },
      {
        "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
      },
      {
        "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
      },
      {
        "country_id": 879921427,
        "tax_name": "Tax",
        "id": 1005264686,
        "name": "Yukon",
        "code": "YT",
        "tax_type": null,
        "shipping_zone_id": null,
        "tax": 0,
        "tax_percentage": 0
      }
    ]
  }
}
Anchor to section titled 'DELETE request, Deletes a country'

del
Deletes a country
deprecated

Requires shipping access scope.

Important

This endpoint is deprecated as of version 2024-07.

Anchor to section titled 'Parameters of Deletes a country'

Parameters

api_version
string
required
country_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Deletes a country'

Examples

Path parameters
countryid=879921427
string
required
Was this section helpful?
del
/admin/api/2024-10/countries/879921427.json
Copy
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2024-10/countries/879921427.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{}