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

Province

Version 2019-10

The Province resource represents the sales tax that's applied to orders from the sub-regions of a country. It represents any type of sub-region, such as states, provinces, territories, and counties.

You can use the Province resource to retrieve and update available provinces for only the countries that a shop owner has added to a shipping zone. Merchants add countries to a shipping zone from the Shipping page of their Shopify admin.

For information on accessing the tax information for an entire country, including its provinces, see the Country resource.

Caution

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

Countries that have provinces in Shopify

Shopify provides provincial tax rates for the following countries:

A-J M-Z
Argentina (24 provinces) Malaysia (16 states/territories)
Australia (8 states/territories) Mexico (32 states)
Brazil (27 states) New Zealand (16 regions)
Canada (13 provinces/territories) Nigeria (37 states)
China (31 provinces) Panama (13 regions)
Colombia (33 provinces) Portugal (20 regions)
Egypt (29 governorates) Romania (42 counties)
Guatemala (22 regions) Russia (82 regions)
India (36 states) South Africa (9 provinces)
Indonesia (34 provinces) South Korea (17 provinces)
Ireland (26 counties) Spain (52 provinces)
Italy (110 provinces) United Arab Emirates (7 emirates)
Japan (47 prefectures) United States (62 states/territories)

What you can 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 province.
country_id 
"country_id": 879921427

The ID for the country that the province belongs to.
id 
"id": 205434194

The ID for the province.
name 
"name": "Alberta"

The full name of the province.
shipping_zone_id 
"shipping_zone_id": 2038345

The ID for the shipping zone that the province belongs to.
tax 
"tax": 0.08

The sales tax rate to be applied to orders made by customers from this province.
tax_name 
"tax_name": "PST"

The name of the tax for this province.
tax_type 
"tax_type": "normal"

The tax type. Valid values: null, normal, harmonized, or compounded.

A harmonized tax is a combination of provincial and federal sales taxes.

Normal and harmonized tax rates are applied to the pre-tax value of an order, but a compounded tax rate is applied on top of other tax rates. For example, if a $100 order receives a 5% normal tax rate and a 2% compound tax rate, then the post-tax total is $107.10 ((100 x 1.05) x 1.02 = 107.1).
tax_percentage 
"tax_percentage": 8.0

The province's tax in percent format.

Endpoints

GET /admin/api/unstable/countries/{country_id}/provinces.json
Retrieves a list of provinces
since_id

Restrict results to after the specified ID.
fields

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

Retrieve all provinces for a country

GET /admin/api/unstable/countries/879921427/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
    }
  ]
}

Retrieve all provinces for a country after the specified ID

GET /admin/api/unstable/countries/879921427/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/api/unstable/countries/{country_id}/provinces/count.json
Retrieves a count of provinces for a country

Count all provinces

GET /admin/api/unstable/countries/879921427/provinces/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 13
}
GET /admin/api/unstable/countries/{country_id}/provinces/{province_id}.json
Retrieves a single province for a country
fields

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

Retrieve a single province

GET /admin/api/unstable/countries/879921427/provinces/224293623.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/api/unstable/countries/{country_id}/provinces/{province_id}.json
Updates an existing province for a country.

Update a province's tax rate

PUT /admin/api/unstable/countries/879921427/provinces/224293623.json
{
  "province": {
    "id": 224293623,
    "tax": 0.09
  }
}
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
  }
}
Version 2020-01

The Province resource represents the sales tax that's applied to orders from the sub-regions of a country. It represents any type of sub-region, such as states, provinces, territories, and counties.

You can use the Province resource to retrieve and update available provinces for only the countries that a shop owner has added to a shipping zone. Merchants add countries to a shipping zone from the Shipping page of their Shopify admin.

For information on accessing the tax information for an entire country, including its provinces, see the Country resource.

Caution

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

Countries that have provinces in Shopify

Shopify provides provincial tax rates for the following countries:

A-J M-Z
Argentina (24 provinces) Malaysia (16 states/territories)
Australia (8 states/territories) Mexico (32 states)
Brazil (27 states) New Zealand (16 regions)
Canada (13 provinces/territories) Nigeria (37 states)
China (31 provinces) Panama (13 regions)
Colombia (33 provinces) Portugal (20 regions)
Egypt (29 governorates) Romania (42 counties)
Guatemala (22 regions) Russia (82 regions)
India (36 states) South Africa (9 provinces)
Indonesia (34 provinces) South Korea (17 provinces)
Ireland (26 counties) Spain (52 provinces)
Italy (110 provinces) United Arab Emirates (7 emirates)
Japan (47 prefectures) United States (62 states/territories)

What you can 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 province.
country_id 
"country_id": 879921427

The ID for the country that the province belongs to.
id 
"id": 205434194

The ID for the province.
name 
"name": "Alberta"

The full name of the province.
shipping_zone_id 
"shipping_zone_id": 2038345

The ID for the shipping zone that the province belongs to.
tax 
"tax": 0.08

The sales tax rate to be applied to orders made by customers from this province.
tax_name 
"tax_name": "PST"

The name of the tax for this province.
tax_type 
"tax_type": "normal"

The tax type. Valid values: null, normal, harmonized, or compounded.

A harmonized tax is a combination of provincial and federal sales taxes.

Normal and harmonized tax rates are applied to the pre-tax value of an order, but a compounded tax rate is applied on top of other tax rates. For example, if a $100 order receives a 5% normal tax rate and a 2% compound tax rate, then the post-tax total is $107.10 ((100 x 1.05) x 1.02 = 107.1).
tax_percentage 
"tax_percentage": 8.0

The province's tax in percent format.

Endpoints

GET /admin/api/unstable/countries/{country_id}/provinces.json
Retrieves a list of provinces
since_id

Restrict results to after the specified ID.
fields

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

Retrieve all provinces for a country

GET /admin/api/unstable/countries/879921427/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
    }
  ]
}

Retrieve all provinces for a country after the specified ID

GET /admin/api/unstable/countries/879921427/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/api/unstable/countries/{country_id}/provinces/count.json
Retrieves a count of provinces for a country

Count all provinces

GET /admin/api/unstable/countries/879921427/provinces/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 13
}
GET /admin/api/unstable/countries/{country_id}/provinces/{province_id}.json
Retrieves a single province for a country
fields

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

Retrieve a single province

GET /admin/api/unstable/countries/879921427/provinces/224293623.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/api/unstable/countries/{country_id}/provinces/{province_id}.json
Updates an existing province for a country.

Update a province's tax rate

PUT /admin/api/unstable/countries/879921427/provinces/224293623.json
{
  "province": {
    "id": 224293623,
    "tax": 0.09
  }
}
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
  }
}
Version 2020-04

The Province resource represents the sales tax that's applied to orders from the sub-regions of a country. It represents any type of sub-region, such as states, provinces, territories, and counties.

You can use the Province resource to retrieve and update available provinces for only the countries that a shop owner has added to a shipping zone. Merchants add countries to a shipping zone from the Shipping page of their Shopify admin.

For information on accessing the tax information for an entire country, including its provinces, see the Country resource.

Caution

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

Countries that have provinces in Shopify

Shopify provides provincial tax rates for the following countries:

A-J M-Z
Argentina (24 provinces) Malaysia (16 states/territories)
Australia (8 states/territories) Mexico (32 states)
Brazil (27 states) New Zealand (16 regions)
Canada (13 provinces/territories) Nigeria (37 states)
China (31 provinces) Panama (13 regions)
Colombia (33 provinces) Portugal (20 regions)
Egypt (29 governorates) Romania (42 counties)
Guatemala (22 regions) Russia (82 regions)
India (36 states) South Africa (9 provinces)
Indonesia (34 provinces) South Korea (17 provinces)
Ireland (26 counties) Spain (52 provinces)
Italy (110 provinces) United Arab Emirates (7 emirates)
Japan (47 prefectures) United States (62 states/territories)

What you can 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 province.
country_id 
"country_id": 879921427

The ID for the country that the province belongs to.
id 
"id": 205434194

The ID for the province.
name 
"name": "Alberta"

The full name of the province.
shipping_zone_id 
"shipping_zone_id": 2038345

The ID for the shipping zone that the province belongs to.
tax 
"tax": 0.08

The sales tax rate to be applied to orders made by customers from this province.
tax_name 
"tax_name": "PST"

The name of the tax for this province.
tax_type 
"tax_type": "normal"

The tax type. Valid values: null, normal, harmonized, or compounded.

A harmonized tax is a combination of provincial and federal sales taxes.

Normal and harmonized tax rates are applied to the pre-tax value of an order, but a compounded tax rate is applied on top of other tax rates. For example, if a $100 order receives a 5% normal tax rate and a 2% compound tax rate, then the post-tax total is $107.10 ((100 x 1.05) x 1.02 = 107.1).
tax_percentage 
"tax_percentage": 8.0

The province's tax in percent format.

Endpoints

GET /admin/api/unstable/countries/{country_id}/provinces.json
Retrieves a list of provinces
since_id

Restrict results to after the specified ID.
fields

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

Retrieve all provinces for a country

GET /admin/api/unstable/countries/879921427/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
    }
  ]
}

Retrieve all provinces for a country after the specified ID

GET /admin/api/unstable/countries/879921427/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/api/unstable/countries/{country_id}/provinces/count.json
Retrieves a count of provinces for a country

Count all provinces

GET /admin/api/unstable/countries/879921427/provinces/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 13
}
GET /admin/api/unstable/countries/{country_id}/provinces/{province_id}.json
Retrieves a single province for a country
fields

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

Retrieve a single province

GET /admin/api/unstable/countries/879921427/provinces/224293623.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/api/unstable/countries/{country_id}/provinces/{province_id}.json
Updates an existing province for a country.

Update a province's tax rate

PUT /admin/api/unstable/countries/879921427/provinces/224293623.json
{
  "province": {
    "id": 224293623,
    "tax": 0.09
  }
}
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
  }
}
Version 2020-07

The Province resource represents the sales tax that's applied to orders from the sub-regions of a country. It represents any type of sub-region, such as states, provinces, territories, and counties.

You can use the Province resource to retrieve and update available provinces for only the countries that a shop owner has added to a shipping zone. Merchants add countries to a shipping zone from the Shipping page of their Shopify admin.

For information on accessing the tax information for an entire country, including its provinces, see the Country resource.

Caution

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

Countries that have provinces in Shopify

Shopify provides provincial tax rates for the following countries:

A-J M-Z
Argentina (24 provinces) Malaysia (16 states/territories)
Australia (8 states/territories) Mexico (32 states)
Brazil (27 states) New Zealand (16 regions)
Canada (13 provinces/territories) Nigeria (37 states)
China (31 provinces) Panama (13 regions)
Colombia (33 provinces) Portugal (20 regions)
Egypt (29 governorates) Romania (42 counties)
Guatemala (22 regions) Russia (82 regions)
India (36 states) South Africa (9 provinces)
Indonesia (34 provinces) South Korea (17 provinces)
Ireland (26 counties) Spain (52 provinces)
Italy (110 provinces) United Arab Emirates (7 emirates)
Japan (47 prefectures) United States (62 states/territories)

What you can 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 province.
country_id 
"country_id": 879921427

The ID for the country that the province belongs to.
id 
"id": 205434194

The ID for the province.
name 
"name": "Alberta"

The full name of the province.
shipping_zone_id 
"shipping_zone_id": 2038345

The ID for the shipping zone that the province belongs to.
tax 
"tax": 0.08

The sales tax rate to be applied to orders made by customers from this province.
tax_name 
"tax_name": "PST"

The name of the tax for this province.
tax_type 
"tax_type": "normal"

The tax type. Valid values: null, normal, harmonized, or compounded.

A harmonized tax is a combination of provincial and federal sales taxes.

Normal and harmonized tax rates are applied to the pre-tax value of an order, but a compounded tax rate is applied on top of other tax rates. For example, if a $100 order receives a 5% normal tax rate and a 2% compound tax rate, then the post-tax total is $107.10 ((100 x 1.05) x 1.02 = 107.1).
tax_percentage 
"tax_percentage": 8.0

The province's tax in percent format.

Endpoints

GET /admin/api/unstable/countries/{country_id}/provinces.json
Retrieves a list of provinces
since_id

Restrict results to after the specified ID.
fields

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

Retrieve all provinces for a country

GET /admin/api/unstable/countries/879921427/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
    }
  ]
}

Retrieve all provinces for a country after the specified ID

GET /admin/api/unstable/countries/879921427/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/api/unstable/countries/{country_id}/provinces/count.json
Retrieves a count of provinces for a country

Count all provinces

GET /admin/api/unstable/countries/879921427/provinces/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 13
}
GET /admin/api/unstable/countries/{country_id}/provinces/{province_id}.json
Retrieves a single province for a country
fields

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

Retrieve a single province

GET /admin/api/unstable/countries/879921427/provinces/224293623.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/api/unstable/countries/{country_id}/provinces/{province_id}.json
Updates an existing province for a country.

Update a province's tax rate

PUT /admin/api/unstable/countries/879921427/provinces/224293623.json
{
  "province": {
    "id": 224293623,
    "tax": 0.09
  }
}
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
  }
}
Version 2020-10 (Latest)

The Province resource represents the sales tax that's applied to orders from the sub-regions of a country. It represents any type of sub-region, such as states, provinces, territories, and counties.

You can use the Province resource to retrieve and update available provinces for only the countries that a shop owner has added to a shipping zone. Merchants add countries to a shipping zone from the Shipping page of their Shopify admin.

For information on accessing the tax information for an entire country, including its provinces, see the Country resource.

Caution

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

Countries that have provinces in Shopify

Shopify provides provincial tax rates for the following countries:

A-J M-Z
Argentina (24 provinces) Malaysia (16 states/territories)
Australia (8 states/territories) Mexico (32 states)
Brazil (27 states) New Zealand (16 regions)
Canada (13 provinces/territories) Nigeria (37 states)
China (31 provinces) Panama (13 regions)
Colombia (33 provinces) Portugal (20 regions)
Egypt (29 governorates) Romania (42 counties)
Guatemala (22 regions) Russia (82 regions)
India (36 states) South Africa (9 provinces)
Indonesia (34 provinces) South Korea (17 provinces)
Ireland (26 counties) Spain (52 provinces)
Italy (110 provinces) United Arab Emirates (7 emirates)
Japan (47 prefectures) United States (62 states/territories)

What you can 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 province.
country_id 
"country_id": 879921427

The ID for the country that the province belongs to.
id 
"id": 205434194

The ID for the province.
name 
"name": "Alberta"

The full name of the province.
shipping_zone_id 
"shipping_zone_id": 2038345

The ID for the shipping zone that the province belongs to.
tax 
"tax": 0.08

The sales tax rate to be applied to orders made by customers from this province.
tax_name 
"tax_name": "PST"

The name of the tax for this province.
tax_type 
"tax_type": "normal"

The tax type. Valid values: null, normal, harmonized, or compounded.

A harmonized tax is a combination of provincial and federal sales taxes.

Normal and harmonized tax rates are applied to the pre-tax value of an order, but a compounded tax rate is applied on top of other tax rates. For example, if a $100 order receives a 5% normal tax rate and a 2% compound tax rate, then the post-tax total is $107.10 ((100 x 1.05) x 1.02 = 107.1).
tax_percentage 
"tax_percentage": 8.0

The province's tax in percent format.

Endpoints

GET /admin/api/unstable/countries/{country_id}/provinces.json
Retrieves a list of provinces
since_id

Restrict results to after the specified ID.
fields

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

Retrieve all provinces for a country

GET /admin/api/unstable/countries/879921427/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
    }
  ]
}

Retrieve all provinces for a country after the specified ID

GET /admin/api/unstable/countries/879921427/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/api/unstable/countries/{country_id}/provinces/count.json
Retrieves a count of provinces for a country

Count all provinces

GET /admin/api/unstable/countries/879921427/provinces/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 13
}
GET /admin/api/unstable/countries/{country_id}/provinces/{province_id}.json
Retrieves a single province for a country
fields

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

Retrieve a single province

GET /admin/api/unstable/countries/879921427/provinces/224293623.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/api/unstable/countries/{country_id}/provinces/{province_id}.json
Updates an existing province for a country.

Update a province's tax rate

PUT /admin/api/unstable/countries/879921427/provinces/224293623.json
{
  "province": {
    "id": 224293623,
    "tax": 0.09
  }
}
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
  }
}
Version 2021-01 (Release candidate)

The Province resource represents the sales tax that's applied to orders from the sub-regions of a country. It represents any type of sub-region, such as states, provinces, territories, and counties.

You can use the Province resource to retrieve and update available provinces for only the countries that a shop owner has added to a shipping zone. Merchants add countries to a shipping zone from the Shipping page of their Shopify admin.

For information on accessing the tax information for an entire country, including its provinces, see the Country resource.

Caution

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

Countries that have provinces in Shopify

Shopify provides provincial tax rates for the following countries:

A-J M-Z
Argentina (24 provinces) Malaysia (16 states/territories)
Australia (8 states/territories) Mexico (32 states)
Brazil (27 states) New Zealand (16 regions)
Canada (13 provinces/territories) Nigeria (37 states)
China (31 provinces) Panama (13 regions)
Colombia (33 provinces) Portugal (20 regions)
Egypt (29 governorates) Romania (42 counties)
Guatemala (22 regions) Russia (82 regions)
India (36 states) South Africa (9 provinces)
Indonesia (34 provinces) South Korea (17 provinces)
Ireland (26 counties) Spain (52 provinces)
Italy (110 provinces) United Arab Emirates (7 emirates)
Japan (47 prefectures) United States (62 states/territories)

What you can 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 province.
country_id 
"country_id": 879921427

The ID for the country that the province belongs to.
id 
"id": 205434194

The ID for the province.
name 
"name": "Alberta"

The full name of the province.
shipping_zone_id 
"shipping_zone_id": 2038345

The ID for the shipping zone that the province belongs to.
tax 
"tax": 0.08

The sales tax rate to be applied to orders made by customers from this province.
tax_name 
"tax_name": "PST"

The name of the tax for this province.
tax_type 
"tax_type": "normal"

The tax type. Valid values: null, normal, harmonized, or compounded.

A harmonized tax is a combination of provincial and federal sales taxes.

Normal and harmonized tax rates are applied to the pre-tax value of an order, but a compounded tax rate is applied on top of other tax rates. For example, if a $100 order receives a 5% normal tax rate and a 2% compound tax rate, then the post-tax total is $107.10 ((100 x 1.05) x 1.02 = 107.1).
tax_percentage 
"tax_percentage": 8.0

The province's tax in percent format.

Endpoints

GET /admin/api/unstable/countries/{country_id}/provinces.json
Retrieves a list of provinces
since_id

Restrict results to after the specified ID.
fields

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

Retrieve all provinces for a country

GET /admin/api/unstable/countries/879921427/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
    }
  ]
}

Retrieve all provinces for a country after the specified ID

GET /admin/api/unstable/countries/879921427/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/api/unstable/countries/{country_id}/provinces/count.json
Retrieves a count of provinces for a country

Count all provinces

GET /admin/api/unstable/countries/879921427/provinces/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 13
}
GET /admin/api/unstable/countries/{country_id}/provinces/{province_id}.json
Retrieves a single province for a country
fields

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

Retrieve a single province

GET /admin/api/unstable/countries/879921427/provinces/224293623.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/api/unstable/countries/{country_id}/provinces/{province_id}.json
Updates an existing province for a country.

Update a province's tax rate

PUT /admin/api/unstable/countries/879921427/provinces/224293623.json
{
  "province": {
    "id": 224293623,
    "tax": 0.09
  }
}
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
  }
}
Version unstable

The Province resource represents the sales tax that's applied to orders from the sub-regions of a country. It represents any type of sub-region, such as states, provinces, territories, and counties.

You can use the Province resource to retrieve and update available provinces for only the countries that a shop owner has added to a shipping zone. Merchants add countries to a shipping zone from the Shipping page of their Shopify admin.

For information on accessing the tax information for an entire country, including its provinces, see the Country resource.

Caution

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

Countries that have provinces in Shopify

Shopify provides provincial tax rates for the following countries:

A-J M-Z
Argentina (24 provinces) Malaysia (16 states/territories)
Australia (8 states/territories) Mexico (32 states)
Brazil (27 states) New Zealand (16 regions)
Canada (13 provinces/territories) Nigeria (37 states)
China (31 provinces) Panama (13 regions)
Colombia (33 provinces) Portugal (20 regions)
Egypt (29 governorates) Romania (42 counties)
Guatemala (22 regions) Russia (82 regions)
India (36 states) South Africa (9 provinces)
Indonesia (34 provinces) South Korea (17 provinces)
Ireland (26 counties) Spain (52 provinces)
Italy (110 provinces) United Arab Emirates (7 emirates)
Japan (47 prefectures) United States (62 states/territories)

What you can 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 province.
country_id 
"country_id": 879921427

The ID for the country that the province belongs to.
id 
"id": 205434194

The ID for the province.
name 
"name": "Alberta"

The full name of the province.
shipping_zone_id 
"shipping_zone_id": 2038345

The ID for the shipping zone that the province belongs to.
tax 
"tax": 0.08

The sales tax rate to be applied to orders made by customers from this province.
tax_name 
"tax_name": "PST"

The name of the tax for this province.
tax_type 
"tax_type": "normal"

The tax type. Valid values: null, normal, harmonized, or compounded.

A harmonized tax is a combination of provincial and federal sales taxes.

Normal and harmonized tax rates are applied to the pre-tax value of an order, but a compounded tax rate is applied on top of other tax rates. For example, if a $100 order receives a 5% normal tax rate and a 2% compound tax rate, then the post-tax total is $107.10 ((100 x 1.05) x 1.02 = 107.1).
tax_percentage 
"tax_percentage": 8.0

The province's tax in percent format.

Endpoints

GET /admin/api/unstable/countries/{country_id}/provinces.json
Retrieves a list of provinces
since_id

Restrict results to after the specified ID.
fields

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

Retrieve all provinces for a country

GET /admin/api/unstable/countries/879921427/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
    }
  ]
}

Retrieve all provinces for a country after the specified ID

GET /admin/api/unstable/countries/879921427/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/api/unstable/countries/{country_id}/provinces/count.json
Retrieves a count of provinces for a country

Count all provinces

GET /admin/api/unstable/countries/879921427/provinces/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 13
}
GET /admin/api/unstable/countries/{country_id}/provinces/{province_id}.json
Retrieves a single province for a country
fields

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

Retrieve a single province

GET /admin/api/unstable/countries/879921427/provinces/224293623.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/api/unstable/countries/{country_id}/provinces/{province_id}.json
Updates an existing province for a country.

Update a province's tax rate

PUT /admin/api/unstable/countries/879921427/provinces/224293623.json
{
  "province": {
    "id": 224293623,
    "tax": 0.09
  }
}
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
  }
}