Province (API)

From Shopify Wiki

Jump to: navigation, search

Shopowners can specify which countries they will ship to (in the Regions & Taxes page, located in the Preferences menu), and these countries are made available through the API using the country resource. If any of those countries have states or provinces, those states or provinces are also registered as shipping destinations, each of which can have its own state or provincial sales tax. As with countries, you can modify the sales tax for each state or province to account for surtaxes or exemptions that apply to the shop.

Among the sets of states and provinces supported by Shopify are:

  • Australia's 8 states and territories
  • Canada's 13 provinces and territories
  • Mexico's 32 states
  • Spain's 52 provinces
  • United States' 62 states and territories

States and provinces are represented by the province resource; we use the term "province" to cover both.

Contents

Special note for U.S. Shops using the County Tax feature

County Tax (currently in beta) is a new feature that automatically calculates the state and county sales taxes for a purchase based on the customer's zip code. If the shop has County Tax enabled (new shops have it enabled by default, and as of April 2012, nearly half of all active shops do), the tax rates defined for the state will be ignored in favor of the tax calculated by County Tax, which is more accurate.

What can you do with states or provinces using the Shopify API?

  • Get information about one or more states or provinces of a country currently registered with the shop.
  • Count all the states or provinces of a country currently registered with the shop.
  • Modify the sales tax of a state or province of a country already registered with the shop.

Province properties

Each instance of the province resource has the following properties:

Property Description
code The standard abbrevation for the state or province. The code for a given state or province will be the same as the code for the same state or province in another shop.
id The unique numeric identifier for the state or province. Note that the id for a given state or province in one shop will not be the same as the id for the same state or province in another shop.
name The full name of the state or province.
tax The national sales tax rate to be applied to orders made by customers from that country.
tax_name The national sales tax rate to be applied to orders made by customers from that country.
tax_type The national sales tax rate to be applied to orders made by customers from that country.
tax_percentage The national sales tax rate to be applied to orders made by customers from that country.

Get a list of states or provinces registered with the shop

To get a list of states or provinces for a specific country, use a GET request as shown below: 

GET https://api_key:shared-secret@hostname/admin/countries/country_id/provinces.format?query_parameters

where:

  • api_key is your app's API key
  • shared_secret is your app's shared secret
  • hostname is the shop's "myshopify.com" domain (e.g. thisismyshop.myshopify.com)
  • country_id is the id of the country whose provinces or states you want to rerieve
  • format is either json or xml
  • query_parameters (optional), made up of one or more parameters in parameter=value format, delimited by & characters

Example: Get a list of the states or provinces for a specific country registered with the shop

In this example, we want a list of the provinces of Canada, whose id in our example shop is 3378932.

JSON

The request: 

GET https://api_key:shared-secret@hostname/admin/countries/country_id/provinces.json

The response: 

HTTP/1.1 200 OK[]
 {
   "provinces": [
     {
       "code": "AB",
       "id": 205434194,
       "name": "Alberta",
       "tax": 0.08,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 8.0
     },
     {
       "code": "BC",
       "id": 170405627,
       "name": "British Columbia",
       "tax": 0.07,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 7.0
     },
     {
       "code": "MB",
       "id": 342345110,
       "name": "Manitoba",
       "tax": 0.07,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 7.0
     },
     {
       "code": "NB",
       "id": 92264567,
       "name": "New Brunswick",
       "tax": 0.15,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 15.0
     },
     {
       "code": "NF",
       "id": 243284171,
       "name": "Newfoundland",
       "tax": 0.15,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 15.0
     },
     {
       "code": "NT",
       "id": 439598329,
       "name": "Northwest Territories",
       "tax": 0.0,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 0.0
     },
     {
       "code": "NS",
       "id": 448070559,
       "name": "Nova Scotia",
       "tax": 0.15,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 15.0
     },
     {
       "code": "NU",
       "id": 670206421,
       "name": "Nunavut",
       "tax": 0.0,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 0.0
     },
     {
       "code": "ON",
       "id": 702530425,
       "name": "Ontario",
       "tax": 0.08,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 8.0
     },
     {
       "code": "PE",
       "id": 570891722,
       "name": "Prince Edward Island",
       "tax": 0.1,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 10.0
     },
     {
       "code": "QC",
       "id": 224293623,
       "name": "Quebec",
       "tax": 0.09,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 9.0
     },
     {
       "code": "YT",
       "id": 1005264686,
       "name": "Yukon",
       "tax": 0.0,
       "tax_name": null,
       "tax_type": null,
       "tax_percentage": 0.0
     }
   ]
 }

XML

The request: 

GET https://api_key:shared-secret@hostname/admin/countries/country_id/provinces.xml

The response: 

HTTP/1.1 200 OK[]
 <?xml version="1.0" encoding="UTF-8"?>
 <provinces type="array">
   <province>
     <id type="integer">205434194</id>
     <name>Alberta</name>
     <code>AB</code>
     <tax type="float">0.08</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">8.0</tax-percentage>
   </province>
   <province>
     <id type="integer">170405627</id>
     <name>British Columbia</name>
     <code>BC</code>
     <tax type="float">0.07</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">7.0</tax-percentage>
   </province>
   <province>
     <id type="integer">342345110</id>
     <name>Manitoba</name>
     <code>MB</code>
     <tax type="float">0.07</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">7.0</tax-percentage>
   </province>
   <province>
     <id type="integer">92264567</id>
     <name>New Brunswick</name>
     <code>NB</code>
     <tax type="float">0.15</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">15.0</tax-percentage>
   </province>
   <province>
     <id type="integer">243284171</id>
     <name>Newfoundland</name>
     <code>NF</code>
     <tax type="float">0.15</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">15.0</tax-percentage>
   </province>
   <province>
     <id type="integer">439598329</id>
     <name>Northwest Territories</name>
     <code>NT</code>
     <tax type="float">0.0</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">0.0</tax-percentage>
   </province>
   <province>
     <id type="integer">448070559</id>
     <name>Nova Scotia</name>
     <code>NS</code>
     <tax type="float">0.15</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">15.0</tax-percentage>
   </province>
   <province>
     <id type="integer">670206421</id>
     <name>Nunavut</name>
     <code>NU</code>
     <tax type="float">0.0</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">0.0</tax-percentage>
   </province>
   <province>
     <id type="integer">702530425</id>
     <name>Ontario</name>
     <code>ON</code>
     <tax type="float">0.08</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">8.0</tax-percentage>
   </province>
   <province>
     <id type="integer">570891722</id>
     <name>Prince Edward Island</name>
     <code>PE</code>
     <tax type="float">0.1</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">10.0</tax-percentage>
   </province>
   <province>
     <id type="integer">224293623</id>
     <name>Quebec</name>
     <code>QC</code>
     <tax type="float">0.09</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">9.0</tax-percentage>
   </province>
   <province>
     <id type="integer">1005264686</id>
     <name>Yukon</name>
     <code>YT</code>
     <tax type="float">0.0</tax>
     <tax-name nil="true"></tax-name>
     <tax-type nil="true"></tax-type>
     <tax-percentage type="float">0.0</tax-percentage>
   </province>
 </provinces>

Get a single state or province registered with the shop

To get a single state or province for a specific country, use a GET request as shown below: 

GET https://api_key:shared-secret@hostname/admin/countries/country_id/provinces/province_id.format?fields=fields

where:

  • api_key is your app's API key
  • shared_secret is your app's shared secret
  • hostname is the shop's "myshopify.com" domain (e.g. thisismyshop.myshopify.com)
  • country_id is the id of the country of the state or province you want to retrieve
  • province_id is the id of the state or province
  • format is either json or xml
  • fields is an optional comma-separated list of province property names

Example: Get a single state or province registered with the shop

In this example, we want to get the properties of the province of Quebec, whose id<code> in our example shop is <code>224293623.

JSON

The request: 

GET https://api_key:shared-secret@hostname/admin/countries/3378932/provinces/224293623.json

The response: 

HTTP/1.1 200 OK[]
 {
   "province": {
     "code": "QC",
     "id": 224293623,
     "name": "Quebec",
     "tax": 0.09,
     "tax_name": null,
     "tax_type": null,
     "tax_percentage": 9.0
   }
 }

XML

The request: 

GET https://api_key:shared-secret@hostname/admin/countries/3378932/provinces/'224293623.xml

The response: 

HTTP/1.1 200 OK[]
 <?xml version="1.0" encoding="UTF-8"?>
 <province>
   <id type="integer">224293623</id>
   <name>Quebec</name>
   <code>QC</code>
   <tax type="float">0.09</tax>
   <tax-name nil="true"></tax-name>
   <tax-type nil="true"></tax-type>
   <tax-percentage type="float">9.0</tax-percentage>
 </province>

Count provinces or states of a country registered with the shop

To get the number of provinces or states for a specific country, use a GET request as shown below: 

GET https://api_key:shared-secret@hostname/admin/countries/country_id/provinces/count.format

where:

  • api_key is your app's API key
  • shared_secret is your app's shared secret
  • hostname is the shop's "myshopify.com" domain (e.g. thisismyshop.myshopify.com)
  • country_id is the id of the country whose provinces or states you want to count
  • format is either json or xml

Example: Count the provinces or states of a country registered with the shop

In this example, we want to count the provinces of Canada, whose id in our example shop is 3378932.

JSON

The request: 

GET https://api_key:shared-secret@hostname/admin/countries/3378932/provinces/count.json

The response: 

HTTP/1.1 200 OK[]
 {
   "count": 13
 }

XML

The request: 

GET https://api_key:shared-secret@hostname/admin/countries/3378932/provinces/count.xml

The response: 

HTTP/1.1 200 OK[]
 <?xml version="1.0" encoding="UTF-8"?>
 <count type="integer">13</count>

Modify the sales tax of a state or province registered with the shop

To modify the sales tax of a state or province, use a PUT request as shown below: 

PUT https://api_key:shared-secret@hostname/admin/countries/country_id/provinces/province_id.format

where:

  • api_key is your app's API key
  • shared_secret is your app's shared secret
  • hostname is the shop's "myshopify.com" domain (e.g. thisismyshop.myshopify.com)
  • country_id is the id of the country whose state or province you want to modify
  • * province_id is the id of the state or province you want to modify
  • format is either json or xml

Example: Modify the sales tax of a state or province registered with the shop

In this example, we want to change the sales tax of Quebec to 15%. In our example shop, its id is 224293623.

JSON

The request: 

PUT https://api_key:shared-secret@hostname/admin/countries/country_id/provinces/province_id.json

The request body: 

{
   "province": {
     "id": 224293623,
     "tax": 0.15
   }
 }

The response: 

HTTP/1.1 200 OK[]
 {
   "province": {
     "code": "QC",
     "id": 224293623,
     "name": "Quebec",
     "tax": 0.15,
     "tax_name": null,
     "tax_type": null,
     "tax_percentage": 15.0
   }
 }

XML

The request: 

PUT https://api_key:shared-secret@hostname/admin/countries/country_id/provinces/province_id.xml

The request body: 

<?xml version="1.0" encoding="UTF-8"?>
 <province>
   <id type="integer">224293623</id>
   <tax type="float">0.15</tax>
 </province>

The response: 

HTTP/1.1 200 OK[]
 <?xml version="1.0" encoding="UTF-8"?>
 <province>
   <id type="integer">224293623</id>
   <name>Quebec</name>
   <code>QC</code>
   <tax type="float">0.15</tax>
   <tax-name nil="true"></tax-name>
   <tax-type nil="true"></tax-type>
   <tax-percentage type="float">15.0</tax-percentage>
 </province>
Retrieved from "http://wiki.shopify.com/Province_(API)"