API Province
From Spiffy Stores Knowledge Base
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.
Contents
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