haravan API - Developer Resources Country

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 /admin/countries.json Receive a list of all Countries
GET /admin/countries/count.json Receive a count of all Countries
GET /admin/countries/#{id}.json Receive a single Country
POST /admin/countries.json Create a new Country
PUT /admin/countries/#{id}.json Modify an existing Country
DELETE /admin/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. It is important to note that the id for a given country in one shop will not be the same as the id for the same country in another shop.
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. code: The two letter province or state code. country_id: The unique numeric identifier for the country. id: The unique numeric identifier for the particular province or state. name: The name of the province or state. tax: The tax value in decimal format. tax_name: The name of the tax as it is referred to in the applicable province/state. For example, in Ontario, Canada the tax is referred to as HST. tax_type: A tax_type is applied for a compounded sales tax. For example, the Canadian HST is a compounded sales tax of both PST and GST. tax_percentage: The tax value in percent format.
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/admin/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 /admin/countries.json

View 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 /admin/countries.json?since_id=359115488

View 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/admin/countries/count.json

Get a count of all countries

Count all countries

GET /admin/countries/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 3
}

GET/admin/countries/879921427.json

Show country

fields

comma-separated list of fields to include in the response

Show country

GET /admin/countries/#{id}.json

View Response

HTTP/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/admin/countries.json

Create a country

Create a country using haravan's tax rate for the country

POST /admin/countries.json

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

View Response

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

POST /admin/countries.json

{
  "country": {
    "code": "FR",
    "tax": 0.25
  }
}

View Response

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/admin/countries/879921427.json

Update a country

Update the country's tax rate

PUT /admin/countries/#{id}.json

{
  "country": {
    "id": 879921427,
    "tax": 0.1
  }
}

View Response

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": [
    ]
  }
}