Admin: Created page with "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 sa..."

2018-05-24T00:39:07Z

Created page with "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 sa..."

New page

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

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

== Endpoints ==

=== <code>GET /api/countries/COUNTRY_ID/provinces.json</code> ===

Retrieve a list of all provinces for the country.

==== Optional Parameters ====

{| class="reference"
!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 <code>limit</code> 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 ====

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

</pre>

=== <code>GET /api/countries/COUNTRY_ID/provinces/count.json</code> ===

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

==== Example Request and Response ====

<pre>
GET /api/countries/113/provinces/count.json

HTTP/1.1 200 OK

{
"count": 6
}

</pre>

=== <code>GET /api/countries/COUNTRY_ID/provinces/PROVINCE_ID.json</code> ===

Retrieves a single province by ID.

==== Optional Parameters ====

{| class="reference"
!fields
|A comma-separated list of fields to return in the response.
|}

==== Example Request and Response ====

<pre>
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
}
}
</pre>

=== <code>PUT /api/countries/COUNTRY_ID/provinces/PROVINCE_ID.json</code> ===

Updates a store province.

==== Example Request and Response ====

<pre>
PUT /api/countries/113/provinces/1218.json

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

HTTP/1.1 200 OK
</pre>

== Further Reference ==

* [[An Introduction to the Spiffy Stores API]]
* [[Creating Private API Keys]]
* [[Using the API]]
* [[API Reference]]

API Province - Revision history

Admin: Created page with "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 sa..."