API Country

The Country resource represents the tax rates applied to orders from the different countries where a store sells its products.

Merchants select the countries for which they wish to accept sales for their products when they set up their Shipping Countries on the Regions and Taxes page of the toolbox.

The Country resource lets you access the countries and tax rates set up by the merchant. The countries list includes a default entry called 'Rest of World', which represents all non-specified countries.

You can use the Country resource to modify the sales tax rate for a country or sub-region to account for surtaxes or exemptions that apply to the store.

Country Properties

id	{ "id" : 113 } A unique numeric identifier for the country.
name	{ "name": "Australia" } The full name of the country in English.
code	{ "code": "AU" } The 2-letter international country code.
tax	{ "tax": 0.1 } The national sales tax rate applied to orders made by customers from that country.
tax_percentage	{ "tax_percentage": 10.0 } The national sales tax rate applied to orders made by customers from that country. This is expressed as a percentage.
tax_name	{ "tax_name": "GST" } The name of the national sales tax.
tax_inclusive	{ "tax_inclusive": true } Indicates whether prices are quoted including or excluding sales tax.
free_shipping	{ "free_shipping": true } Indicates that the country 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 country.
currency	{ "currency": "AUD" } The currency used in this country.
unit_system	{ "unit_system": "metric" } The unit system used in this country.
provinces	{ "provinces": [ { "id": 1218, "name": "Australian Capital Territory", "code": "ACT", "country_id": 113, "tax": 0.00, "tax_percentage": 0.0, "tax_name": "GST", "free_shipping": true, "handling_fee": 0.0 }, ... ] } The sub-regions of a country, such as its provinces or states.

Endpoints

GET /api/countries.json

Retrieve a list of all countries.

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.
fields	A comma-separated list of fields to return in the response. If a list of fields is provided, then the provinces field will always be excluded.

Example Request and Response

GET /api/countries.json

HTTP/1.1 200 OK

{
  "countries": [
    {
      "id": 270,
      "name": "Algeria",
      "code": "DZ",
      "tax": 0.17,
      "tax_percentage": 17.0,
      "tax_name": "VAT",
      "tax_inclusive": true,
      "free_shipping": false,
      "handling_fee": 0.0,
      "currency": "DZD",
      "unit_system": "metric",
      "provinces": [
      ]
    }, ...
  ]
}

Examples using filters

GET /api/countries.json?fields=id,name,currency

GET /api/countries/count.json

Return a count of the number of countries.

Example Request and Response

GET /api/countries/count.json

HTTP/1.1 200 OK

{
  "count": 15
}

GET /api/countries/COUNTRY_ID.json

Retrieves a single country by ID.

Optional Parameters

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

Example Request and Response

GET /api/countries/270.json

HTTP/1.1 200 OK

{
  "country": {
    "id": 270,
    "name": "Algeria",
    "code": "DZ",
    "tax": 0.17,
    "tax_percentage": 17.0,
    "tax_name": "VAT",
    "tax_inclusive": true,
    "free_shipping": false,
    "handling_fee": 0.0,
    "currency": "DZD",
    "unit_system": "metric",
    "provinces": [
    ]
  }
}

POST /api/countries.json

Add a country to the store.

Example Request and Response

POST /api/countries.json

{
  "country": {
    "code": "FR"
  }
}

or

{
  "country": {
    "name": "France",
    "tax": 0.15,
    "tax_name": "VAT",
    ...
  }
}

HTTP/1.1 201 Created

PUT /api/countries/COUNTRY_ID.json

Updates a store country.

Example Request and Response

PUT /api/countries/270.json

{
  "country": {
    "id": 270,
    "free_shipping": true
  }
}

HTTP/1.1 200 OK

DELETE /api/countries/COUNTRY_ID.json

Deletes a country from the store.

Example Request and Response

DELETE /api/countries/270.json

HTTP/1.1 200 OK

{}

Further Reference

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