Province

Shop owners can specify which country or countries they will ship to and these countries are made available through the API using the country resource. Shop owners can do this by navigating to the "Preferences" tab under "Regions & Taxes." If any of those countries have states or provinces, those states or provinces are also registered as shipping destinations, each of which can have its own state or provincial sales tax.

Province

As with countries, you can modify the sales tax for each state or province to account for surtaxes or exemptions that apply to the shop.

Among the sets of states and provinces supported by Shopify are:

  • Australia's 8 states and territories
  • Canada's 13 provinces and territories
  • Mexico's 32 states
  • Spain's 52 provinces
  • United States' 62 states and territories

Reminder

States and provinces are represented by the province resource. We use the term "province" to cover both.

What can you do with Province?

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

Province Properties

code
{ "code" : "AB" }

The standard abbreviation for the state or province.

country_id
{ "country_id" : 879921427 }

The unique numeric identifier for the country.

id
{ "id" : 205434194 }

The unique numeric identifier for the state or province.

name
{ "name" : "Alberta" }

The full name of the state or province.

shipping_zone_id
{ "shipping_zone_id" : 2038345 }

The unique numeric identifier for the shipping zone the province belongs to.

tax
{ "tax" : 0.08 }

The national sales tax rate to be applied to orders made by customers from that province or state.

tax_name
{ "tax_name" : null }

The name of the tax for that province or state.

tax_type
{ "tax_type" : "harmonized" }

Compounded sales tax. For example, the Canadian HST (also known as, the "Harmonized Sales tax") is a compounded sales tax of both PST and GST.

tax_percentage
{ "tax_percentage" : 8.0 }

The province or state's tax in percent format.

Endpoints

GET/admin/countries/879921427/provinces.json

Get all provinces

country_id

The id of the country the province belongs to

since_id

Restrict results to after the specified ID

fields

comma-separated list of fields to include in the response

Get all provinces for a country

GET /admin/countries/#{id}/provinces.json
View Response
HTTP/1.1 200 OK
{
  "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 all provinces for a country after the specified ID

GET /admin/countries/#{id}/provinces.json?since_id=536137098
View Response
HTTP/1.1 200 OK
{
  "provinces": [
    {
      "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": 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": 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/879921427/provinces/count.json

Get a count of all provinces

Get a count all provinces

GET /admin/countries/#{id}/provinces/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 13
}
GET/admin/countries/879921427/provinces/224293623.json

Get a single province for a country

country_id

The id of the country the province belongs to

fields

comma-separated list of fields to include in the response

Show province

GET /admin/countries/#{id}/provinces/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "province": {
    "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
  }
}
PUT/admin/countries/879921427/provinces/224293623.json

Update a province's tax rate

PUT /admin/countries/#{id}/provinces/#{id}.json
{
  "province": {
    "id": 224293623,
    "tax": 0.15
  }
}
View Response
HTTP/1.1 200 OK
{
  "province": {
    "id": 224293623,
    "country_id": 879921427,
    "name": "Quebec",
    "code": "QC",
    "tax": 0.15,
    "tax_name": "HST",
    "tax_type": "compounded",
    "shipping_zone_id": null,
    "tax_percentage": 15.0
  }
}