--- title: Province description: >- Manage the tax rates that are applied to orders from a specific province or state. api_version: 2026-07 source_url: html: 'https://shopify.dev/docs/api/admin-rest/latest/resources/province' md: 'https://shopify.dev/docs/api/admin-rest/latest/resources/province.md' api_name: admin-rest api_type: rest --- The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql). For details and migration steps, visit our [migration guide](https://shopify.dev/docs/apps/build/graphql/migrate). # Province **Multiple access scopes needed — refer to each endpoint for access scope requirements.:** **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](https://shopify.dev/changelog/deprecation-notice-country-and-province-endpoints-in-admin-rest-api) 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. ![](https://shopify.dev/assets/api/reference/province.png) You can use the Province resource to retrieve and update [available sub-regions](#countries-that-have-provinces-in-shopify) 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](https://shopify.dev/api/admin-rest/latest/resources/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) | \# ## Endpoints * [get](https://shopify.dev/docs/api/admin-rest/latest/resources/province.md#get-countries-country-id-provinces) [/admin/api/latest/countries/{country\_​id}/provinces.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/province.md#get-countries-country-id-provinces) Retrieves a list of provinces for a country **deprecated** * [get](https://shopify.dev/docs/api/admin-rest/latest/resources/province.md#get-countries-country-id-provinces-province-id) [/admin/api/latest/countries/{country\_​id}/provinces/{province\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/province.md#get-countries-country-id-provinces-province-id) Retrieves a single province for a country **deprecated** * [get](https://shopify.dev/docs/api/admin-rest/latest/resources/province.md#get-countries-country-id-provinces-count) [/admin/api/latest/countries/{country\_​id}/provinces/count.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/province.md#get-countries-country-id-provinces-count) Retrieves a count of provinces for a country **deprecated** * [put](https://shopify.dev/docs/api/admin-rest/latest/resources/province.md#put-countries-country-id-provinces-province-id) [/admin/api/latest/countries/{country\_​id}/provinces/{province\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/province.md#put-countries-country-id-provinces-province-id) Updates an existing province for a country **deprecated** *** ## The Province resource ### Properties *** code The standard abbreviation for the province. *** country\_id The ID for the country that the province belongs to. *** id The ID for the province. *** name The full name of the province. *** shipping\_zone\_id The ID for the shipping zone that the province belongs to. Deprecated: this field now returns null and will be removed in a future API version. *** tax The sales tax rate to be applied to orders made by customers from this province. *** tax\_name The name of the tax for this province. *** 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`). *** tax\_percentage The province's tax in percent format. *** {} ## The Province resource ```json { "code": "AB", "country_id": 879921427, "id": 205434194, "name": "Alberta", "shipping_zone_id": null, "tax": 0.08, "tax_name": "PST", "tax_type": "normal", "tax_percentage": 8 } ``` *** ## getRetrieves a list of provinces for a country**deprecated** **Important:** This endpoint is deprecated as of 2024-07. Retrieves a list of provinces. ### Parameters *** api\_version **string** **required** *** country\_id **string** **required** *** fields Show only certain fields, specified by a comma-separated list of fields names. *** since\_id Restrict results to after the specified ID. *** ### Examples ### Retrieve all provinces for a country ### Path parameters country\_​id=​879921427 **string** **required** ### Retrieve all provinces for a country after the specified ID ### Path parameters country\_​id=​879921427 **string** **required** ### Query parameters since\_​id=​536137098 Restrict results to after the specified ID. get ## /admin/api/2026-07/countries/879921427/provinces.​json ```bash curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427/provinces.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` {} ## Response JSON ```json HTTP/1.1 200 OK { "provinces": [ { "id": 205434194, "country_id": 879921427, "name": "Alberta", "code": "AB", "tax_name": null, "tax_type": null, "tax": 0.08, "tax_percentage": 8, "shipping_zone_id": null }, { "id": 170405627, "country_id": 879921427, "name": "British Columbia", "code": "BC", "tax_name": null, "tax_type": null, "tax": 0.07, "tax_percentage": 7, "shipping_zone_id": null }, { "id": 342345110, "country_id": 879921427, "name": "Manitoba", "code": "MB", "tax_name": null, "tax_type": null, "tax": 0.07, "tax_percentage": 7, "shipping_zone_id": null }, ``` ### examples * #### Retrieve all provinces for a country ##### ```curl curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427/provinces.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` #### response ```json HTTP/1.1 200 OK{"provinces":[{"id":205434194,"country_id":879921427,"name":"Alberta","code":"AB","tax_name":null,"tax_type":null,"tax":0.08,"tax_percentage":8,"shipping_zone_id":null},{"id":170405627,"country_id":879921427,"name":"British Columbia","code":"BC","tax_name":null,"tax_type":null,"tax":0.07,"tax_percentage":7,"shipping_zone_id":null},{"id":342345110,"country_id":879921427,"name":"Manitoba","code":"MB","tax_name":null,"tax_type":null,"tax":0.07,"tax_percentage":7,"shipping_zone_id":null},{"id":92264567,"country_id":879921427,"name":"New Brunswick","code":"NB","tax_name":null,"tax_type":null,"tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"id":243284171,"country_id":879921427,"name":"Newfoundland","code":"NL","tax_name":null,"tax_type":null,"tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"id":439598329,"country_id":879921427,"name":"Northwest Territories","code":"NT","tax_name":null,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null},{"id":448070559,"country_id":879921427,"name":"Nova Scotia","code":"NS","tax_name":null,"tax_type":"harmonized","tax":0.15,"tax_percentage":15,"shipping_zone_id":null},{"id":670206421,"country_id":879921427,"name":"Nunavut","code":"NU","tax_name":null,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null},{"id":702530425,"country_id":879921427,"name":"Ontario","code":"ON","tax_name":null,"tax_type":null,"tax":0.08,"tax_percentage":8,"shipping_zone_id":null},{"id":570891722,"country_id":879921427,"name":"Prince Edward Island","code":"PE","tax_name":null,"tax_type":null,"tax":0.1,"tax_percentage":10,"shipping_zone_id":null},{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","tax":0.09,"tax_percentage":9,"shipping_zone_id":null},{"id":473391800,"country_id":879921427,"name":"Saskatchewan","code":"SK","tax_name":null,"tax_type":null,"tax":0.09,"tax_percentage":9,"shipping_zone_id":null},{"id":1005264686,"country_id":879921427,"name":"Yukon","code":"YT","tax_name":null,"tax_type":null,"tax":0,"tax_percentage":0,"shipping_zone_id":null}]} ``` * #### Retrieve all provinces for a country after the specified ID ##### ```curl curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427/provinces.json?since_id=536137098" \ -H "X-Shopify-Access-Token: {access_token}" ``` *** ## getRetrieves a single province for a country**deprecated** **Important:** This endpoint is deprecated as of version 2024-07. Retrieves a single province for a country ### Parameters *** api\_version **string** **required** *** country\_id **string** **required** *** province\_id **string** **required** *** fields Show only certain fields, specified by a comma-separated list of field names. *** ### Examples ### Retrieve a single province get ## /admin/api/2026-07/countries/879921427/provinces/224293623.​json ```bash curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427/provinces/224293623.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` {} ## Response JSON ```json HTTP/1.1 200 OK { "province": { "id": 224293623, "country_id": 879921427, "name": "Quebec", "code": "QC", "tax_name": "HST", "tax_type": "compounded", "tax": 0.09, "tax_percentage": 9, "shipping_zone_id": null } } ``` ### examples * #### Retrieve a single province ##### ```curl curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427/provinces/224293623.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` #### response ```json HTTP/1.1 200 OK{"province":{"id":224293623,"country_id":879921427,"name":"Quebec","code":"QC","tax_name":"HST","tax_type":"compounded","tax":0.09,"tax_percentage":9,"shipping_zone_id":null}} ``` *** ## getRetrieves a count of provinces for a country**deprecated** **Important:** This endpoint is deprecated as of version 2024-07. Retrieves a count of provinces for a country ### Parameters *** api\_version **string** **required** *** country\_id **string** **required** *** ### Examples ### Count all provinces ### Path parameters country\_​id=​879921427 **string** **required** get ## /admin/api/2026-07/countries/879921427/provinces/count.​json ```bash curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427/provinces/count.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` {} ## Response JSON ```json HTTP/1.1 200 OK { "count": 13 } ``` ### examples * #### Count all provinces ##### ```curl curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427/provinces/count.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` #### response ```json HTTP/1.1 200 OK{"count":13} ``` *** ## putUpdates an existing province for a country**deprecated** **Requires \`shipping\` access scope.:** **Important:** This endpoint is deprecated as of version 2024-07. **Caution:** As of version 2020-10, the tax field is deprecated. Updates an existing province for a country. ### Parameters *** api\_version **string** **required** *** country\_id **string** **required** *** province\_id **string** **required** *** ### Examples ### Update a province's tax rate ### Request body province​ **Province resource** province.id:​224293623 The ID for the province. province.tax:​0.09 The sales tax rate to be applied to orders made by customers from this province. put ## /admin/api/2026-07/countries/879921427/provinces/224293623.​json ```bash curl -d '{"province":{"id":224293623,"tax":0.09}}' \ -X PUT "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427/provinces/224293623.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` {} ## Response JSON ```json HTTP/1.1 200 OK { "province": { "country_id": 879921427, "tax_name": "HST", "name": "Quebec", "code": "QC", "id": 224293623, "tax_type": "compounded", "tax": 0.09, "tax_percentage": 9, "shipping_zone_id": null } } ``` ### examples * #### Update a province's tax rate ##### ```curl curl -d '{"province":{"id":224293623,"tax":0.09}}' \ -X PUT "https://your-development-store.myshopify.com/admin/api/2026-07/countries/879921427/provinces/224293623.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` #### response ```json HTTP/1.1 200 OK{"province":{"country_id":879921427,"tax_name":"HST","name":"Quebec","code":"QC","id":224293623,"tax_type":"compounded","tax":0.09,"tax_percentage":9,"shipping_zone_id":null}} ```