# Province

Important

The REST Province API is deprecated as of version 2024-07.

Please refer to the documentation for each individual endpoint and the developer changelog for more information.

The Province resource represents the sales tax that's applied to orders based the sub-regions of a country. Sub-regions might include counties, emirates, governorates, prefectures, provinces, regions, states, and territories.

{{ '/api/reference/province.png' | image }}

You can use the Province resource to retrieve and update available sub-regions 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) Mexico (32 states)
Australia (8 states/territories) New Zealand (16 regions)
Brazil (27 states) Nigeria (37 states)
Canada (13 provinces/territories) Panama (13 regions)
Chile (16 regions) Peru (26 regions)
China (31 provinces) Philippines (82 provinces)
Colombia (33 provinces) Portugal (20 regions)
Egypt (29 governorates) Romania (42 counties)
Guatemala (22 regions) Russia (82 regions)
Hong Kong (3 regions) South Africa (9 provinces)
India (36 states) South Korea (17 provinces)
Indonesia (34 provinces) Spain (52 provinces)
Ireland (26 counties) Thailand (78 provinces)
Italy (110 provinces) United Arab Emirates (7 emirates)
Japan (47 prefectures) United Kingdom (5 constituent countries/provinces)
Malaysia (16 states/territories) United States (62 states/territories)
## Resource Properties ### Province * code: The standard abbreviation for the province. * Type: x-string * Example: "AB" * country_id: The ID for the country that the province belongs to. * Type: x-string * Example: 879921427 * id: The ID for the province. * Type: x-string * Example: 205434194 * name: The full name of the province. * Type: x-string * Example: "Alberta" * shipping_zone_id: The ID for the shipping zone that the province belongs to. * Type: x-string * Example: 2038345 * tax: The sales tax rate to be applied to orders made by customers from this province. * Type: x-string * Example: 0.08 * tax_name: The name of the tax for this province. * Type: x-string * Example: "PST" * tax_type: 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).

* Type: x-string * Example: "normal" * tax_percentage: The province's tax in percent format. * Type: x-string * Example: 8.0 ## Retrieves a list of provinces for a country

Important

This endpoint is deprecated as of 2024-07.

Retrieves a list of provinces.

### Endpoint /admin/api/#{api_version}/countries/{country_id}/provinces.json (GET) ### Parameters * api_version (required): * country_id (required): * fields: Show only certain fields, specified by a comma-separated list of fields names. * since_id: Restrict results to after the specified ID. ### Responses #### 200 Retrieves a list of provinces for a country Examples: ##### Retrieve all provinces for a country Request: ``` GET /admin/api/unstable/countries/879921427/provinces.json ``` Response: ``` HTTP/1.1 200 OK {"provinces":[{"id":205434194,"country_id":879921427,"name":"Alberta","code":"AB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"id":170405627,"country_id":879921427,"name":"British Columbia","code":"BC","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0},{"id":342345110,"country_id":879921427,"name":"Manitoba","code":"MB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.07,"tax_percentage":7.0},{"id":92264567,"country_id":879921427,"name":"New Brunswick","code":"NB","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":243284171,"country_id":879921427,"name":"Newfoundland","code":"NL","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":439598329,"country_id":879921427,"name":"Northwest Territories","code":"NT","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"id":448070559,"country_id":879921427,"name":"Nova Scotia","code":"NS","tax_name":null,"tax_type":"harmonized","shipping_zone_id":null,"tax":0.15,"tax_percentage":15.0},{"id":670206421,"country_id":879921427,"name":"Nunavut","code":"NU","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"id":702530425,"country_id":879921427,"name":"Ontario","code":"ON","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"id":570891722,"country_id":879921427,"name":"Prince Edward Island","code":"PE","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.1,"tax_percentage":10.0},{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0},{"id":473391800,"country_id":879921427,"name":"Saskatchewan","code":"SK","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0},{"id":1005264686,"country_id":879921427,"name":"Yukon","code":"YT","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0}]} ``` ##### Retrieve all provinces for a country after the specified ID Request: ``` GET /admin/api/unstable/countries/879921427/provinces.json ``` Response: ``` HTTP/1.1 200 OK {"provinces":[{"id":570891722,"country_id":879921427,"name":"Prince Edward Island","code":"PE","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.1,"tax_percentage":10.0},{"id":670206421,"country_id":879921427,"name":"Nunavut","code":"NU","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0},{"id":702530425,"country_id":879921427,"name":"Ontario","code":"ON","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.08,"tax_percentage":8.0},{"id":1005264686,"country_id":879921427,"name":"Yukon","code":"YT","tax_name":null,"tax_type":null,"shipping_zone_id":null,"tax":0.0,"tax_percentage":0.0}]} ``` ## Retrieves a count of provinces for a country

Important

This endpoint is deprecated as of version 2024-07.

Retrieves a count of provinces for a country

### Endpoint /admin/api/#{api_version}/countries/{country_id}/provinces/count.json (GET) ### Parameters * api_version (required): * country_id (required): ### Responses #### 200 Retrieves a count of provinces for a country Examples: ##### Count all provinces Request: ``` GET /admin/api/unstable/countries/879921427/provinces/count.json ``` Response: ``` HTTP/1.1 200 OK {"count":13} ``` ## Retrieves a single province for a country

Important

This endpoint is deprecated as of version 2024-07.

Retrieves a single province for a country

### Endpoint /admin/api/#{api_version}/countries/{country_id}/provinces/{province_id}.json (GET) ### Parameters * api_version (required): * country_id (required): * province_id (required): * fields: Show only certain fields, specified by a comma-separated list of field names. ### Responses #### 200 Retrieves a single province for a country Examples: ##### Retrieve a single province Request: ``` GET /admin/api/unstable/countries/879921427/provinces/224293623.json ``` Response: ``` HTTP/1.1 200 OK {"province":{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0}} ``` ## Updates an existing province for a country

Important

This endpoint is deprecated as of version 2024-07.

Updates an existing province for a country. ### Endpoint /admin/api/#{api_version}/countries/{country_id}/provinces/{province_id}.json (PUT) ### Parameters * api_version (required): * country_id (required): * province_id (required): ### Responses #### 200 Updates an existing province for a country Examples: ##### Update a province's tax rate Request: ``` PUT /admin/api/unstable/countries/879921427/provinces/224293623.json {"province":{"id":224293623,"tax":0.09}} ``` Response: ``` HTTP/1.1 200 OK {"province":{"country_id":879921427,"id":224293623,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","shipping_zone_id":null,"tax":0.09,"tax_percentage":9.0}} ```