Country
Shop owners can specify the country or countries they will ship their products to. Shop owners are able to do this through their shop admin dashboard in the "Settings" tab, under the "Taxes" tab.
These countries are made available through the API using the country resource. The countries list resource represents the set of countries that have been specified as shipping destinations, including an additional default 'country' called 'Rest of World', which represents the non-specified countries. An important piece of information included with each country is the country's national sales tax rate, which you can modify to account for surtaxes or exemptions that apply to the shop.
What can you do with Country?
The haravan API lets you do the following with the Country resource. More detailed versions of these general actions may be available:
- GET /com/countries.json
Receive a list of all Countries - GET /com/countries/count.json
Receive a count of all Countries - GET /com/countries/#{id}.json
Receive a single Country - POST /com/countries.json
Create a new Country - PUT /com/countries/#{id}.json
Modify an existing Country - DELETE /com/countries/#{id}.json
Remove a Country from the database
Country Properties
carrier_shipping_rate_providers | { "carrier_shipping_rate_providers" : "[ ]" }Information about carrier shipping providers and the rates used. |
code | { "code" : "CA" }The ISO 3166-1 alpha-2 two-letter country code for the country. The code for a given country will be the same as the code for the same country in another shop. |
id | { "id" : 879921427 }The unique numeric identifier for the country. |
name | { "name" : "Canada" }The full name of the country, in English. |
price_based_shipping_rates | { "price_based_shipping_rates" : "[ ]" }Information about price based shipping rates used. |
provinces | { "code" : "AB" }{ "country_id" : 879921427 }{ "id" : 205434194 }{ "name" : "Alberta" }{ "tax" : 0.08 }{ "tax_name" : "null" }{ "tax_type" : "null" }{ "tax_percentage" : 8.0 }
The sub-regions of a country. The term provinces also encompasses states.
|
tax | { "tax" : "0.05" }The national sales tax rate to be applied to orders made by customers from that country. |
weight_based_shipping_rates | { "weight_based_shipping_rates" : "[ ]" }Information about weight based shipping rates used. |
Endpoints
GET/com/countries.json
Get a list of all countries
since_id | Restrict results to after the specified ID |
fields | comma-separated list of fields to include in the response |
Get all countries
GET /com/countries.jsonView Response
HTTP/1.1 200 OK
{
"countries": [
{
"code": "CA",
"id": 879921427,
"name": "Canada",
"tax": 0.05,
"tax_name": "GST",
"provinces": [
{
"code": "AB",
"country_id": 879921427,
"id": 205434194,
"name": "Alberta",
"tax": 0.08,
"tax_name": null,
"tax_type": null,
"tax_percentage": 8.0
},
{
"code": "BC",
"country_id": 879921427,
"id": 170405627,
"name": "British Columbia",
"tax": 0.07,
"tax_name": null,
"tax_type": null,
"tax_percentage": 7.0
},
{
"code": "MB",
"country_id": 879921427,
"id": 342345110,
"name": "Manitoba",
"tax": 0.07,
"tax_name": null,
"tax_type": null,
"tax_percentage": 7.0
},
{
"code": "NB",
"country_id": 879921427,
"id": 92264567,
"name": "New Brunswick",
"tax": 0.15,
"tax_name": null,
"tax_type": null,
"tax_percentage": 15.0
},
{
"code": "NL",
"country_id": 879921427,
"id": 243284171,
"name": "Newfoundland",
"tax": 0.15,
"tax_name": null,
"tax_type": null,
"tax_percentage": 15.0
},
{
"code": "NT",
"country_id": 879921427,
"id": 439598329,
"name": "Northwest Territories",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
},
{
"code": "NS",
"country_id": 879921427,
"id": 448070559,
"name": "Nova Scotia",
"tax": 0.15,
"tax_name": null,
"tax_type": "harmonized",
"tax_percentage": 15.0
},
{
"code": "NU",
"country_id": 879921427,
"id": 670206421,
"name": "Nunavut",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
},
{
"code": "ON",
"country_id": 879921427,
"id": 702530425,
"name": "Ontario",
"tax": 0.08,
"tax_name": null,
"tax_type": null,
"tax_percentage": 8.0
},
{
"code": "PE",
"country_id": 879921427,
"id": 570891722,
"name": "Prince Edward Island",
"tax": 0.1,
"tax_name": null,
"tax_type": null,
"tax_percentage": 10.0
},
{
"code": "QC",
"country_id": 879921427,
"id": 224293623,
"name": "Quebec",
"tax": 0.09,
"tax_name": "HST",
"tax_type": "compounded",
"tax_percentage": 9.0
},
{
"code": "SK",
"country_id": 879921427,
"id": 473391800,
"name": "Saskatchewan",
"tax": 0.09,
"tax_name": null,
"tax_type": null,
"tax_percentage": 9.0
},
{
"code": "YT",
"country_id": 879921427,
"id": 1005264686,
"name": "Yukon",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
}
],
"weight_based_shipping_rates": [
],
"price_based_shipping_rates": [
],
"carrier_shipping_rate_providers": [
]
},
{
"code": "CO",
"id": 359115488,
"name": "Colombia",
"tax": 0.15,
"tax_name": "VAT",
"provinces": [
],
"weight_based_shipping_rates": [
],
"price_based_shipping_rates": [
],
"carrier_shipping_rate_providers": [
]
},
{
"code": "US",
"id": 817138619,
"name": "United States",
"tax": 0.0,
"tax_name": "Federal Tax",
"provinces": [
{
"code": "CA",
"country_id": 817138619,
"id": 952629862,
"name": "California",
"tax": 0.05,
"tax_name": null,
"tax_type": null,
"tax_percentage": 5.0
},
{
"code": "KY",
"country_id": 817138619,
"id": 222234158,
"name": "Kentucky",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
},
{
"code": "CA",
"country_id": 817138619,
"id": 915134533,
"name": "Pennsylvania",
"tax": 0.05,
"tax_name": null,
"tax_type": null,
"tax_percentage": 5.0
}
],
"weight_based_shipping_rates": [
],
"price_based_shipping_rates": [
{
"country_id": 817138619,
"id": 10665840,
"max_order_subtotal": "2000.00",
"min_order_subtotal": "0.00",
"name": "Standard Shipping",
"price": "10.99",
"offsets": [
]
},
{
"country_id": 817138619,
"id": 78195293,
"max_order_subtotal": "2000.00",
"min_order_subtotal": "0.00",
"name": "Expensive Shipping",
"price": "99.99",
"offsets": [
]
}
],
"carrier_shipping_rate_providers": [
]
}
]
}Get all countries after the specified ID
GET /com/countries.json?since_id=359115488View Response
HTTP/1.1 200 OK
{
"countries": [
{
"code": "US",
"id": 817138619,
"name": "United States",
"tax": 0.0,
"tax_name": "Federal Tax",
"provinces": [
{
"code": "CA",
"country_id": 817138619,
"id": 952629862,
"name": "California",
"tax": 0.05,
"tax_name": null,
"tax_type": null,
"tax_percentage": 5.0
},
{
"code": "KY",
"country_id": 817138619,
"id": 222234158,
"name": "Kentucky",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
},
{
"code": "CA",
"country_id": 817138619,
"id": 915134533,
"name": "Pennsylvania",
"tax": 0.05,
"tax_name": null,
"tax_type": null,
"tax_percentage": 5.0
}
],
"weight_based_shipping_rates": [
],
"price_based_shipping_rates": [
{
"country_id": 817138619,
"id": 10665840,
"max_order_subtotal": "2000.00",
"min_order_subtotal": "0.00",
"name": "Standard Shipping",
"price": "10.99",
"offsets": [
]
},
{
"country_id": 817138619,
"id": 78195293,
"max_order_subtotal": "2000.00",
"min_order_subtotal": "0.00",
"name": "Expensive Shipping",
"price": "99.99",
"offsets": [
]
}
],
"carrier_shipping_rate_providers": [
]
},
{
"code": "CA",
"id": 879921427,
"name": "Canada",
"tax": 0.05,
"tax_name": "GST",
"provinces": [
{
"code": "AB",
"country_id": 879921427,
"id": 205434194,
"name": "Alberta",
"tax": 0.08,
"tax_name": null,
"tax_type": null,
"tax_percentage": 8.0
},
{
"code": "BC",
"country_id": 879921427,
"id": 170405627,
"name": "British Columbia",
"tax": 0.07,
"tax_name": null,
"tax_type": null,
"tax_percentage": 7.0
},
{
"code": "MB",
"country_id": 879921427,
"id": 342345110,
"name": "Manitoba",
"tax": 0.07,
"tax_name": null,
"tax_type": null,
"tax_percentage": 7.0
},
{
"code": "NB",
"country_id": 879921427,
"id": 92264567,
"name": "New Brunswick",
"tax": 0.15,
"tax_name": null,
"tax_type": null,
"tax_percentage": 15.0
},
{
"code": "NL",
"country_id": 879921427,
"id": 243284171,
"name": "Newfoundland",
"tax": 0.15,
"tax_name": null,
"tax_type": null,
"tax_percentage": 15.0
},
{
"code": "NT",
"country_id": 879921427,
"id": 439598329,
"name": "Northwest Territories",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
},
{
"code": "NS",
"country_id": 879921427,
"id": 448070559,
"name": "Nova Scotia",
"tax": 0.15,
"tax_name": null,
"tax_type": "harmonized",
"tax_percentage": 15.0
},
{
"code": "NU",
"country_id": 879921427,
"id": 670206421,
"name": "Nunavut",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
},
{
"code": "ON",
"country_id": 879921427,
"id": 702530425,
"name": "Ontario",
"tax": 0.08,
"tax_name": null,
"tax_type": null,
"tax_percentage": 8.0
},
{
"code": "PE",
"country_id": 879921427,
"id": 570891722,
"name": "Prince Edward Island",
"tax": 0.1,
"tax_name": null,
"tax_type": null,
"tax_percentage": 10.0
},
{
"code": "QC",
"country_id": 879921427,
"id": 224293623,
"name": "Quebec",
"tax": 0.09,
"tax_name": "HST",
"tax_type": "compounded",
"tax_percentage": 9.0
},
{
"code": "SK",
"country_id": 879921427,
"id": 473391800,
"name": "Saskatchewan",
"tax": 0.09,
"tax_name": null,
"tax_type": null,
"tax_percentage": 9.0
},
{
"code": "YT",
"country_id": 879921427,
"id": 1005264686,
"name": "Yukon",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
}
],
"weight_based_shipping_rates": [
],
"price_based_shipping_rates": [
],
"carrier_shipping_rate_providers": [
]
}
]
}GET/com/countries/count.json
Get a count of all countries
GET/com/countries/879921427.json
Show country
fields | comma-separated list of fields to include in the response |
Show country
GET /com/countries/#{id}.jsonView ResponseHTTP/1.1 200 OK
{
"country": {
"code": "CA",
"id": 879921427,
"name": "Canada",
"tax": 0.05,
"tax_name": "GST",
"provinces": [
{
"code": "AB",
"country_id": 879921427,
"id": 205434194,
"name": "Alberta",
"tax": 0.08,
"tax_name": null,
"tax_type": null,
"tax_percentage": 8.0
},
{
"code": "BC",
"country_id": 879921427,
"id": 170405627,
"name": "British Columbia",
"tax": 0.07,
"tax_name": null,
"tax_type": null,
"tax_percentage": 7.0
},
{
"code": "MB",
"country_id": 879921427,
"id": 342345110,
"name": "Manitoba",
"tax": 0.07,
"tax_name": null,
"tax_type": null,
"tax_percentage": 7.0
},
{
"code": "NB",
"country_id": 879921427,
"id": 92264567,
"name": "New Brunswick",
"tax": 0.15,
"tax_name": null,
"tax_type": null,
"tax_percentage": 15.0
},
{
"code": "NL",
"country_id": 879921427,
"id": 243284171,
"name": "Newfoundland",
"tax": 0.15,
"tax_name": null,
"tax_type": null,
"tax_percentage": 15.0
},
{
"code": "NT",
"country_id": 879921427,
"id": 439598329,
"name": "Northwest Territories",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
},
{
"code": "NS",
"country_id": 879921427,
"id": 448070559,
"name": "Nova Scotia",
"tax": 0.15,
"tax_name": null,
"tax_type": "harmonized",
"tax_percentage": 15.0
},
{
"code": "NU",
"country_id": 879921427,
"id": 670206421,
"name": "Nunavut",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
},
{
"code": "ON",
"country_id": 879921427,
"id": 702530425,
"name": "Ontario",
"tax": 0.08,
"tax_name": null,
"tax_type": null,
"tax_percentage": 8.0
},
{
"code": "PE",
"country_id": 879921427,
"id": 570891722,
"name": "Prince Edward Island",
"tax": 0.1,
"tax_name": null,
"tax_type": null,
"tax_percentage": 10.0
},
{
"code": "QC",
"country_id": 879921427,
"id": 224293623,
"name": "Quebec",
"tax": 0.09,
"tax_name": "HST",
"tax_type": "compounded",
"tax_percentage": 9.0
},
{
"code": "SK",
"country_id": 879921427,
"id": 473391800,
"name": "Saskatchewan",
"tax": 0.09,
"tax_name": null,
"tax_type": null,
"tax_percentage": 9.0
},
{
"code": "YT",
"country_id": 879921427,
"id": 1005264686,
"name": "Yukon",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
}
],
"weight_based_shipping_rates": [
],
"price_based_shipping_rates": [
],
"carrier_shipping_rate_providers": [
]
}
}POST/com/countries.json
Create a country
Create a country using haravan's tax rate for the country
HTTP/1.1 201 Created
{
"country": {
"code": "FR",
"id": 980881732,
"name": "France",
"tax": 0.2,
"tax_name": "TVA",
"provinces": [
],
"weight_based_shipping_rates": [
],
"price_based_shipping_rates": [
],
"carrier_shipping_rate_providers": [
]
}
}Create a country using a custom tax rate
HTTP/1.1 201 Created
{
"country": {
"code": "FR",
"id": 980881733,
"name": "France",
"tax": 0.25,
"tax_name": "TVA",
"provinces": [
],
"weight_based_shipping_rates": [
],
"price_based_shipping_rates": [
],
"carrier_shipping_rate_providers": [
]
}
}PUT/com/countries/879921427.json
Update a country
Update the country's tax rate
HTTP/1.1 200 OK
{
"country": {
"code": "CA",
"id": 879921427,
"name": "Canada",
"tax": 0.1,
"tax_name": "GST",
"provinces": [
{
"code": "AB",
"country_id": 879921427,
"id": 205434194,
"name": "Alberta",
"tax": 0.08,
"tax_name": null,
"tax_type": null,
"tax_percentage": 8.0
},
{
"code": "BC",
"country_id": 879921427,
"id": 170405627,
"name": "British Columbia",
"tax": 0.07,
"tax_name": null,
"tax_type": null,
"tax_percentage": 7.0
},
{
"code": "MB",
"country_id": 879921427,
"id": 342345110,
"name": "Manitoba",
"tax": 0.07,
"tax_name": null,
"tax_type": null,
"tax_percentage": 7.0
},
{
"code": "NB",
"country_id": 879921427,
"id": 92264567,
"name": "New Brunswick",
"tax": 0.15,
"tax_name": null,
"tax_type": null,
"tax_percentage": 15.0
},
{
"code": "NL",
"country_id": 879921427,
"id": 243284171,
"name": "Newfoundland",
"tax": 0.15,
"tax_name": null,
"tax_type": null,
"tax_percentage": 15.0
},
{
"code": "NT",
"country_id": 879921427,
"id": 439598329,
"name": "Northwest Territories",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
},
{
"code": "NS",
"country_id": 879921427,
"id": 448070559,
"name": "Nova Scotia",
"tax": 0.15,
"tax_name": null,
"tax_type": "harmonized",
"tax_percentage": 15.0
},
{
"code": "NU",
"country_id": 879921427,
"id": 670206421,
"name": "Nunavut",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
},
{
"code": "ON",
"country_id": 879921427,
"id": 702530425,
"name": "Ontario",
"tax": 0.08,
"tax_name": null,
"tax_type": null,
"tax_percentage": 8.0
},
{
"code": "PE",
"country_id": 879921427,
"id": 570891722,
"name": "Prince Edward Island",
"tax": 0.1,
"tax_name": null,
"tax_type": null,
"tax_percentage": 10.0
},
{
"code": "QC",
"country_id": 879921427,
"id": 224293623,
"name": "Quebec",
"tax": 0.09,
"tax_name": "HST",
"tax_type": "compounded",
"tax_percentage": 9.0
},
{
"code": "SK",
"country_id": 879921427,
"id": 473391800,
"name": "Saskatchewan",
"tax": 0.09,
"tax_name": null,
"tax_type": null,
"tax_percentage": 9.0
},
{
"code": "YT",
"country_id": 879921427,
"id": 1005264686,
"name": "Yukon",
"tax": 0.0,
"tax_name": null,
"tax_type": null,
"tax_percentage": 0.0
}
],
"weight_based_shipping_rates": [
],
"price_based_shipping_rates": [
],
"carrier_shipping_rate_providers": [
]
}
}DELETE/com/countries/879921427.json
Delete a country
Delete a country along with all shipping rates
DELETE /com/countries/#{id}.jsonView ResponseHTTP/1.1 200 OK
{}