API version: unstable
API version: 2021-04 Release candidate
API version: 2021-01 Latest
API version: 2020-10
API version: 2020-07
API version: 2020-04
API version: 2020-01 Unsupported
API version: 2019-10 Unsupported

Country

Version 2020-01

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.

What you can do with Country

The Shopify API lets you do the following with the Country resource. More detailed versions of these general actions may be available:

Country properties

code 
"code": "CA"

The two-letter country code (ISO 3166-1 alpha-2 format).
id 
"id": 879921427

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 
"name": "Canada"

The full name of the country in English.
provinces 
"provinces": [
  {
    "code": "ON",
    "country_id": 879921427,
    "id": 205434194,
    "name": "Ontario",
    "tax": 0.13,
    "tax_name": "HST",
    "tax_type": "harmonized",
    "tax_percentage": 13
  }
]

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 
"tax": 0.05

The national sales tax rate applied to orders made by customers from that country.

Endpoints

GET /admin/api/2020-01/countries.json
Retrieves a list of countries.
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all countries

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

Retrieve all countries after the specified ID

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

Count all countries

GET /admin/api/2020-01/countries/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}
GET /admin/api/2020-01/countries/{country_id}.json
Retrieves a specific county.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a specific country by its ID

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

Create a country using Shopify's tax rate for it

POST /admin/api/2020-01/countries.json
{
  "country": {
    "code": "FR"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "country": {
    "id": 1070231511,
    "name": "France",
    "tax": 0.2,
    "code": "FR",
    "tax_name": "TVA",
    "provinces": []
  }
}

Create a country using a custom tax rate 

POST /admin/api/2020-01/countries.json
{
  "country": {
    "code": "FR",
    "tax": 0.2
  }
}
View Response 
HTTP/1.1 201 Created
{
  "country": {
    "id": 1070231512,
    "name": "France",
    "tax": 0.2,
    "code": "FR",
    "tax_name": "TVA",
    "provinces": []
  }
}
PUT /admin/api/2020-01/countries/{country_id}.json
Updates an existing country.

Update a country's tax rate

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

Delete a country

DELETE /admin/api/2020-01/countries/879921427.json
View Response 
HTTP/1.1 200 OK
{
}
Version 2020-04

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.

What you can do with Country

The Shopify API lets you do the following with the Country resource. More detailed versions of these general actions may be available:

Country properties

code 
"code": "CA"

The two-letter country code (ISO 3166-1 alpha-2 format).
id 
"id": 879921427

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 
"name": "Canada"

The full name of the country in English.
provinces 
"provinces": [
  {
    "code": "ON",
    "country_id": 879921427,
    "id": 205434194,
    "name": "Ontario",
    "tax": 0.13,
    "tax_name": "HST",
    "tax_type": "harmonized",
    "tax_percentage": 13
  }
]

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 
"tax": 0.05

The national sales tax rate applied to orders made by customers from that country.

Endpoints

GET /admin/api/2020-04/countries.json
Retrieves a list of countries.
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all countries

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

Retrieve all countries after the specified ID

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

Count all countries

GET /admin/api/2020-04/countries/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}
GET /admin/api/2020-04/countries/{country_id}.json
Retrieves a specific county.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a specific country by its ID

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

Create a country using Shopify's tax rate for it

POST /admin/api/2020-04/countries.json
{
  "country": {
    "code": "FR"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "country": {
    "id": 1070231511,
    "name": "France",
    "tax": 0.2,
    "code": "FR",
    "tax_name": "TVA",
    "provinces": []
  }
}

Create a country using a custom tax rate 

POST /admin/api/2020-04/countries.json
{
  "country": {
    "code": "FR",
    "tax": 0.2
  }
}
View Response 
HTTP/1.1 201 Created
{
  "country": {
    "id": 1070231512,
    "name": "France",
    "tax": 0.2,
    "code": "FR",
    "tax_name": "TVA",
    "provinces": []
  }
}
PUT /admin/api/2020-04/countries/{country_id}.json
Updates an existing country.

Update a country's tax rate

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

Delete a country

DELETE /admin/api/2020-04/countries/879921427.json
View Response 
HTTP/1.1 200 OK
{
}
Version 2020-07

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.

What you can do with Country

The Shopify API lets you do the following with the Country resource. More detailed versions of these general actions may be available:

Country properties

code 
"code": "CA"

The two-letter country code (ISO 3166-1 alpha-2 format).
id 
"id": 879921427

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 
"name": "Canada"

The full name of the country in English.
provinces 
"provinces": [
  {
    "code": "ON",
    "country_id": 879921427,
    "id": 205434194,
    "name": "Ontario",
    "tax": 0.13,
    "tax_name": "HST",
    "tax_type": "harmonized",
    "tax_percentage": 13
  }
]

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 
"tax": 0.05

The national sales tax rate applied to orders made by customers from that country.

Endpoints

GET /admin/api/2020-07/countries.json
Retrieves a list of countries.
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all countries

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

Retrieve all countries after the specified ID

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

Count all countries

GET /admin/api/2020-07/countries/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}
GET /admin/api/2020-07/countries/{country_id}.json
Retrieves a specific county.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a specific country by its ID

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

Create a country using Shopify's tax rate for it

POST /admin/api/2020-07/countries.json
{
  "country": {
    "code": "FR"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "country": {
    "id": 1070231511,
    "name": "France",
    "tax": 0.2,
    "code": "FR",
    "tax_name": "TVA",
    "provinces": []
  }
}

Create a country using a custom tax rate 

POST /admin/api/2020-07/countries.json
{
  "country": {
    "code": "FR",
    "tax": 0.2
  }
}
View Response 
HTTP/1.1 201 Created
{
  "country": {
    "id": 1070231512,
    "name": "France",
    "tax": 0.2,
    "code": "FR",
    "tax_name": "TVA",
    "provinces": []
  }
}
PUT /admin/api/2020-07/countries/{country_id}.json
Updates an existing country.

Update a country's tax rate

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

Delete a country

DELETE /admin/api/2020-07/countries/879921427.json
View Response 
HTTP/1.1 200 OK
{
}
Version 2020-10

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.

What you can do with Country

The Shopify API lets you do the following with the Country resource. More detailed versions of these general actions may be available:

Country properties

code 
"code": "CA"

The two-letter country code (ISO 3166-1 alpha-2 format).
id 
"id": 879921427

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 
"name": "Canada"