API Province

A Country may have a number Provinces, which represent the various states, regions or provinces that make up the country.

Each Province resource contains information about sales tax and shipping that may differ from the national values.

You can use the Province resource to retrieve and update available provinces for only the countries that a store owner has already added.

For information on accessing the tax information for an entire country, including its provinces, see the Country resource.

Province Properties

id	{ "id" : 1218 } A unique numeric identifier for the province.
name	{ "name": "New South Wales" } The full name of the province in English.
code	{ "code": "NSW" } The international province code.
country_id	{ "country_id": 113 } A unique numeric identifier for the province's country.
tax	{ "tax": 0.0 } The provincial sales tax rate applied to orders made by customers from that province.
tax_percentage	{ "tax_percentage": 0.0 } The provincial sales tax rate applied to orders made by customers from that province. This is expressed as a percentage.
tax_name	{ "tax_name": "GST" } The name of the provincial sales tax.
free_shipping	{ "free_shipping": true } Indicates that the province is eligible for free shipping.
handling_fee	{ "handling_fee": 0.0 } The default handling fee that is added to the cost of shipping to the province.

Endpoints

GET /api/countries/COUNTRY_ID/provinces.json

Retrieve a list of all provinces for the country.

Optional Parameters

limit	Number of results returned. The default is 30, with a maximum of 50 in a single request.
page	The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
since_id	Limit the results to only include objects which have an id greater than the given value.
fields	A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/countries/113/provinces.json

HTTP/1.1 200 OK

{
  "provinces": [
    {
      "id": 1218,
      "name": "Australian Capital Territory",
      "code": "ACT",
      "country_id": 113,
      "tax": 0.0,
      "tax_percentage": 0.0,
      "tax_name": "GST",
      "free_shipping": true,
      "handling_fee": 0.0
    }, ...
  ]
}

Examples using filters

GET /api/countries/113/provinces.json?fields=id,name,tax_name

GET /api/countries/COUNTRY_ID/provinces/count.json

Return a count of the number of provinces for the country.

Example Request and Response

GET /api/countries/113/provinces/count.json

HTTP/1.1 200 OK

{
  "count": 6
}

GET /api/countries/COUNTRY_ID/provinces/PROVINCE_ID.json

Retrieves a single province by ID.

Optional Parameters

fields	A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/countries/113/provinces/1218.json

HTTP/1.1 200 OK

{
  "province": {
    "id": 1218,
    "name": "Australian Capital Territory",
    "code": "ACT",
    "country_id": 113,
    "tax": 0.0,
    "tax_percentage": 0.0,
    "tax_name": "GST",
    "free_shipping": true,
    "handling_fee": 0.0
  }
}

PUT /api/countries/COUNTRY_ID/provinces/PROVINCE_ID.json

Updates a store province.

Example Request and Response

PUT /api/countries/113/provinces/1218.json

{
  "province": {
    "id": 1213,
    "free_shipping": false
  }
}

HTTP/1.1 200 OK

Further Reference

• An Introduction to the Spiffy Stores API
• Creating Private API Keys
• Using the API
• API Reference