---
title: Province
description: Manage the tax rates that are applied to orders from a specific province or state.
api_version: 2025-10
api_name: admin-rest
api_type: rest
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
---

![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)

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#get-countries-country-id-provinces)

  [/admin/api/latest/countries/{country\_​id}/provinces.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/province#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#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#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#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#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#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#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.

***

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": 2038345,
  "tax": 0.08,
  "tax_name": "PST",
  "tax_type": "normal",
  "tax_percentage": 8
}
```

***

## getRetrieves a list of provinces for a countrydeprecated

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/2025-10/countries/879921427/provinces.​json

```bash
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/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,
      "shipping_zone_id": null,
      "tax": 0.08,
      "tax_percentage": 8
    },
    {
      "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
    },
    {
      "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
    },
```

### examples

* #### Retrieve all provinces for a country

  #####

  ```curl
  curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/countries/879921427/provinces.json" \
  -H "X-Shopify-Access-Token: {access_token}"
  ```

  #####

  ```remix
  await admin.rest.resources.Province.all({
    session: session,
    country_id: 879921427,
  });
  ```

  #####

  ```ruby
  # Session is activated via Authentication
  test_session = ShopifyAPI::Context.active_session

  ShopifyAPI::Province.all(
    session: test_session,
    country_id: 879921427,
  )
  ```

  #####

  ```node
  // Session is built by the OAuth process

  await shopify.rest.Province.all({
    session: session,
    country_id: 879921427,
  });
  ```

  #### response

  ```json
  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

  #####

  ```curl
  curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/countries/879921427/provinces.json?since_id=536137098" \
  -H "X-Shopify-Access-Token: {access_token}"
  ```

  #####

  ```remix
  await admin.rest.resources.Province.all({
    session: session,
    country_id: 879921427,
    since_id: "536137098",
  });
  ```

  #####

  ```ruby
  # Session is activated via Authentication
  test_session = ShopifyAPI::Context.active_session

  ShopifyAPI::Province.all(
    session: test_session,
    country_id: 879921427,
    since_id: "536137098",
  )
  ```

  #####

  ```node
  // Session is built by the OAuth process

  await shopify.rest.Province.all({
    session: session,
    country_id: 879921427,
    since_id: "536137098",
  });
  ```

  #### response

  ```json
  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}]}
  ```

***

## getRetrieves a single province for a countrydeprecated

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/2025-10/countries/879921427/provinces/224293623.​json

```bash
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/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",
    "shipping_zone_id": null,
    "tax": 0.09,
    "tax_percentage": 9
  }
}
```

### examples

* #### Retrieve a single province

  #####

  ```curl
  curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/countries/879921427/provinces/224293623.json" \
  -H "X-Shopify-Access-Token: {access_token}"
  ```

  #####

  ```remix
  await admin.rest.resources.Province.find({
    session: session,
    country_id: 879921427,
    id: 224293623,
  });
  ```

  #####

  ```ruby
  # Session is activated via Authentication
  test_session = ShopifyAPI::Context.active_session

  ShopifyAPI::Province.find(
    session: test_session,
    country_id: 879921427,
    id: 224293623,
  )
  ```

  #####

  ```node
  // Session is built by the OAuth process

  await shopify.rest.Province.find({
    session: session,
    country_id: 879921427,
    id: 224293623,
  });
  ```

  #### response

  ```json
  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}}
  ```

***

## getRetrieves a count of provinces for a countrydeprecated

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/2025-10/countries/879921427/provinces/count.​json

```bash
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/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/2025-10/countries/879921427/provinces/count.json" \
  -H "X-Shopify-Access-Token: {access_token}"
  ```

  #####

  ```remix
  await admin.rest.resources.Province.count({
    session: session,
    country_id: 879921427,
  });
  ```

  #####

  ```ruby
  # Session is activated via Authentication
  test_session = ShopifyAPI::Context.active_session

  ShopifyAPI::Province.count(
    session: test_session,
    country_id: 879921427,
  )
  ```

  #####

  ```node
  // Session is built by the OAuth process

  await shopify.rest.Province.count({
    session: session,
    country_id: 879921427,
  });
  ```

  #### response

  ```json
  HTTP/1.1 200 OK{"count":13}
  ```

***

## putUpdates an existing province for a countrydeprecated

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

Show province properties

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/2025-10/countries/879921427/provinces/224293623.​json

```bash
curl -d '{"province":{"id":224293623,"tax":0.09}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2025-10/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,
    "id": 224293623,
    "name": "Quebec",
    "code": "QC",
    "tax_name": "HST",
    "tax_type": "compounded",
    "shipping_zone_id": null,
    "tax": 0.09,
    "tax_percentage": 9
  }
}
```

### 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/2025-10/countries/879921427/provinces/224293623.json" \
  -H "X-Shopify-Access-Token: {access_token}" \
  -H "Content-Type: application/json"
  ```

  #####

  ```remix
  const { admin, session } = await authenticate.admin(request);

  const province = new admin.rest.resources.Province({session: session});

  province.country_id = 879921427;
  province.id = 224293623;
  province.tax = 0.09;
  await province.save({
    update: true,
  });
  ```

  #####

  ```ruby
  # Session is activated via Authentication
  test_session = ShopifyAPI::Context.active_session

  province = ShopifyAPI::Province.new(session: test_session)
  province.country_id = 879921427
  province.id = 224293623
  province.tax = 0.09
  province.save!
  ```

  #####

  ```node
  // Session is built by the OAuth process

  const province = new shopify.rest.Province({session: session});
  province.country_id = 879921427;
  province.id = 224293623;
  province.tax = 0.09;
  await province.save({
    update: true,
  });
  ```

  #### response

  ```json
  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}}
  ```