# Province
<div class='note note-caution'>
<h4>Important</h4>
<p>The REST Province API is deprecated as of version 2024-07.</p>
<p>Please refer to the documentation for each individual endpoint and the <a href="https://shopify.dev/changelog/deprecation-notice-country-and-province-endpoints-in-admin-rest-api">developer changelog</a> for more information.</p>
</div>
<p>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.</p>
{{ '/api/reference/province.png' | image }}
<p>You can use the Province resource to retrieve and update <a href="#countries-that-have-provinces-in-shopify">available sub-regions</a> for only the countries that a shop owner has added to a shipping zone. Merchants add countries to a shipping zone from the <strong>Shipping</strong> page of their Shopify admin.</p>
<p>For information on accessing the tax information for an entire country, including its provinces, see the <a href="/api/admin-rest/latest/resources/country">Country</a> resource.</p>
<div class="note-caution note">
<h4>Caution</h4>
<p>As of version 2020-10, you can no longer update custom tax values for the Province resource.</p>
</div>
<h2>Countries that have provinces in Shopify</h2>
<p>Shopify provides provincial tax rates for the following countries:</p>
<table>
<thead>
<tr>
<th>A-J</th>
<th>M-Z</th>
</tr>
</thead>
<tbody>
<tr>
<td>Argentina (24 provinces)</td>
<td>Mexico (32 states)</td>
</tr>
<tr>
<td>Australia (8 states/territories)</td>
<td>New Zealand (16 regions)</td>
</tr>
<tr>
<td>Brazil (27 states)</td>
<td>Nigeria (37 states)</td>
</tr>
<tr>
<td>Canada (13 provinces/territories)</td>
<td>Panama (13 regions)</td>
</tr>
<tr>
<td>Chile (16 regions)</td>
<td>Peru (26 regions)</td>
</tr>
<tr>
<td>China (31 provinces)</td>
<td>Philippines (82 provinces)</td>
</tr>
<tr>
<td>Colombia (33 provinces)</td>
<td>Portugal (20 regions)</td>
</tr>
<tr>
<td>Egypt (29 governorates)</td>
<td>Romania (42 counties)</td>
</tr>
<tr>
<td>Guatemala (22 regions)</td>
<td>Russia (82 regions)</td>
</tr>
<tr>
<td>Hong Kong (3 regions)</td>
<td>South Africa (9 provinces)</td>
<tr>
<td>India (36 states)</td>
<td>South Korea (17 provinces)</td>
</tr>
<tr>
<td>Indonesia (34 provinces)</td>
<td>Spain (52 provinces)</td>
</tr>
<tr>
<td>Ireland (26 counties)</td>
<td>Thailand (78 provinces)</td>
</tr>
<tr>
<td>Italy (110 provinces)</td>
<td>United Arab Emirates (7 emirates)</td>
</tr>
<tr>
<td>Japan (47 prefectures)</td>
<td>United Kingdom (5 constituent countries/provinces)</td>
</tr>
<tr>
<td>Malaysia (16 states/territories)</td>
<td>United States (62 states/territories)</td>
</tr>
</tbody>
</table>
## 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: <code>null</code>, <code>normal</code>, <code>harmonized</code>, or <code>compounded</code>.
<p>A harmonized tax is a combination of provincial and federal sales taxes.</p>
<p>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 (<code>(100 x 1.05) x 1.02 = 107.1</code>).</p>
* 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
<div class='note note-caution'>
<h4>Important</h4>
<p>This endpoint is deprecated as of 2024-07.</p>
</div>
<p>Retrieves a list of provinces.</p>
### 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
<div class='note note-caution'>
<h4>Important</h4>
<p>This endpoint is deprecated as of version 2024-07.</p>
</div>
<p>Retrieves a count of provinces for a country</p>
### 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
<div class='note note-caution'>
<h4>Important</h4>
<p>This endpoint is deprecated as of version 2024-07.</p>
</div>
<p>Retrieves a single province for a country</p>
### 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
<div class='note note-caution'>
<h4>Important</h4>
<p>This endpoint is deprecated as of version 2024-07.</p>
</div>
<aside class="note caution">
<h4>Caution</h4>
<p>As of version 2020-10, the tax field is deprecated.</p>
</aside>
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}}
```