Country

Shop owners can specify the country or countries they will ship their products to. Shop owners are able to do this through their shop admin dashboard in the "Settings" tab, under the "Taxes" tab.

Country

These countries are made available through the API using the country resource. The countries list resource represents the set of countries that have been specified as shipping destinations, including an additional default 'country' called 'Rest of World', which represents the non-specified countries. An important piece of information included with each country is the country's national sales tax rate, which you can modify to account for surtaxes or exemptions that apply to the shop.

What can you 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 ISO 3166-1 alpha-2 two-letter country code for the country. The code for a given country will be the same as the code for the same country in another shop.

id
{ "id" : 879921427 }

The unique numeric identifier for the country.
It is important to note that the id for a given country in one shop will not be the same as the id for the same country in another shop.

name
{ "name" : "Canada" }

The full name of the country, in English.

provinces
{ "code" : "AB" }
{ "country_id" : 879921427 }
{ "id" : 205434194 }
{ "name" : "Alberta" }
{ "tax" : 0.08 }
{ "tax_name" : null }
{ "tax_type" : null }
{ "tax_percentage" : 8.0 }

The sub-regions of a country. The term provinces also encompasses states.

  • code: The two letter province or state code.
  • country_id: The unique numeric identifier for the country.
  • id: The unique numeric identifier for the particular province or state.
  • name: The name of the province or state.
  • tax: The tax value in decimal format.
  • tax_name: The name of the tax as it is referred to in the applicable province/state. For example, in Ontario, Canada the tax is referred to as HST.
  • tax_type: A tax_type is applied for a compounded sales tax. For example, the Canadian HST is a compounded sales tax of both PST and GST.
  • tax_percentage: The tax value in percent format.

tax
{ "tax" : 0.05 }

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

Endpoints

GET/admin/countries.json

Get a list of all countries

since_id

Restrict results to after the specified ID

fields

comma-separated list of fields to include in the response

Get all countries

GET /admin/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.0,
          "tax_name": null,
          "tax_type": null,
          "shipping_zone_id": 1039932365,
          "tax_percentage": 0.0
        },
        {
          "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
        }
      ]
    }
  ]
}

Get all countries after the specified ID

GET /admin/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.0,
          "tax_name": null,
          "tax_type": null,
          "shipping_zone_id": 1039932365,
          "tax_percentage": 0.0
        },
        {
          "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": 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/countries/count.json

Get a count of all countries

Count all countries

GET /admin/countries/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 3
}
GET/admin/countries/879921427.json

Show country

fields

comma-separated list of fields to include in the response

Show country

GET /admin/countries/#{id}.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/countries.json

Create a country

Create a country using Shopify's tax rate for the country

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

Create a country using a custom tax rate

POST /admin/countries.json
{
  "country": {
    "code": "FR",
    "tax": 0.25
  }
}
View Response
HTTP/1.1 201 Created
{
  "country": {
    "id": 988409122,
    "name": "France",
    "tax": 0.25,
    "code": "FR",
    "tax_name": "TVA",
    "provinces": [
    ]
  }
}
PUT/admin/countries/879921427.json

Update a country

Update the country's tax rate

PUT /admin/countries/#{id}.json
{
  "country": {
    "id": 879921427,
    "tax": 0.1
  }
}
View Response
HTTP/1.1 200 OK
{
  "country": {
    "id": 879921427,
    "name": "Canada",
    "tax": 0.1,
    "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/countries/879921427.json

Delete a country

Delete a country

DELETE /admin/countries/#{id}.json
View Response
HTTP/1.1 200 OK
{}