The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Province

Choose a version:

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 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.

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)

Was this section helpful?

Anchor to section titled 'The Province resource'

The Province resource

Properties

code

The standard abbreviation for the province.

country_id

The ID for the country that the province belongs to.

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.

Was this section helpful?

Anchor to section titled 'GET request, Retrieves a list of provinces for a country'

get
Retrieves a list of provinces for a country
deprecated

Important

This endpoint is deprecated as of 2024-07.

Retrieves a list of provinces.

Anchor to section titled 'Parameters of Retrieves a list of provinces for a country'

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.

Was this section helpful?

Anchor to section titled 'Examples of Retrieves a list of provinces for a country'

Examples

Retrieve all provinces for a country

Path parameters

countryid=879921427

string

required

Retrieve all provinces for a country after the specified ID

Was this section helpful?

{}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
    },
    {
      "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
    },
    {
      "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
    },
    {
      "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
    },
    {
      "id": 439598329,
      "country_id": 879921427,
      "name": "Northwest Territories",
      "code": "NT",
      "tax_name": null,
      "tax_type": null,
      "shipping_zone_id": null,
      "tax": 0,
      "tax_percentage": 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
    },
    {
      "id": 670206421,
      "country_id": 879921427,
      "name": "Nunavut",
      "code": "NU",
      "tax_name": null,
      "tax_type": null,
      "shipping_zone_id": null,
      "tax": 0,
      "tax_percentage": 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
    },
    {
      "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
    },
    {
      "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
    },
    {
      "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
    },
    {
      "id": 1005264686,
      "country_id": 879921427,
      "name": "Yukon",
      "code": "YT",
      "tax_name": null,
      "tax_type": null,
      "shipping_zone_id": null,
      "tax": 0,
      "tax_percentage": 0
    }
  ]
}

Anchor to section titled 'GET request, Retrieves a single province for a country'

get
Retrieves a single province for a country
deprecated

Important

This endpoint is deprecated as of version 2024-07.

Retrieves a single province for a country

Anchor to section titled 'Parameters of 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.

Was this section helpful?

Anchor to section titled 'Examples of Retrieves a single province for a country'

Examples

Retrieve a single province

Was this section helpful?

Anchor to section titled 'GET request, Retrieves a count of provinces for a country'

get
Retrieves 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

Anchor to section titled 'Parameters of Retrieves a count of provinces for a country'

Parameters

api_version

string

required

country_id

string

required

Was this section helpful?

Anchor to section titled 'Examples of Retrieves a count of provinces for a country'

Examples

Count all provinces

Path parameters

countryid=879921427

string

required

Was this section helpful?

Anchor to section titled 'PUT request, Updates an existing province for a country'

put
Updates an existing province for a country
deprecated

Requires shipping access scope.

Important

This endpoint is deprecated as of version 2024-07.

Updates an existing province for a country.

Anchor to section titled 'Parameters of Updates an existing province for a country'

Parameters

api_version

string

required

country_id

string

required

province_id

string

required

Was this section helpful?

Anchor to section titled 'Examples of Updates an existing province for a country'

Examples

Update a province's tax rate

Request body

province

Province resource

Was this section helpful?

Province

Important

Caution

Countries that have provinces in Shopify

The Province resource

getRetrieves a list of provinces for a country deprecated

Important

Parameters

Examples

getRetrieves a single province for a country deprecated

Important

Parameters

Examples

getRetrieves a count of provinces for a country deprecated

Important

Parameters

Examples

putUpdates an existing province for a country deprecated

Important

Parameters

Examples

get
Retrieves a list of provinces for a country
deprecated

get
Retrieves a single province for a country
deprecated

get
Retrieves a count of provinces for a country
deprecated

put
Updates an existing province for a country
deprecated