Using REST API

Please review the following documentation to learn how to use the REST API. The current section allows you to acknowledge yourself with taxamo API basics - how to invoke API operations, how to authenticate calls and how to use desired format for request and response messages.

Taxamo API

Taxamo is build around RESTful API and currently it is the only way to communicate with it - even the JavaScript API or merchant dashboard use REST API underneath.

Currently, there is only one version of the API - /v1. As more versions will appear in the future, we will add them under different urls to make the migration as painless as possible.

The API is build around Transaction resource, which represents customer purchase and calculated tax. To calculate tax without creating a transaction, you can use /api/v1/tax endpoint.

There are also endpoints to locate IP address for tax purposes, retrieve transaction statistics and retrieve dictionaries.

Example API call

$ curl \
 https://api.taxamo.com/api/v1/dictionaries/product_types?public_token=SamplePublicTestKey1
TaxamoApi taxamoApi = new TaxamoApi("SamplePrivateTestKey1");

GetProductTypesDictOut result;

try {
    result = taxamoApi.getProductTypesDict();
} catch (ApiException ae) {
    // handle exception
}
{
  "dictionary": [
    {
      "code": "default"
    },
    {
      "code": "e-service"
    },
    {
      "code": "e-book"
    },
    {
      "code": "e-newspaper"
    }
  ]
}
class GetProductTypesDictOut {
  dictionary: [class ProductTypeSchema {
  code: default
},
  class ProductTypeSchema {
  code: e-service
},
  class ProductTypeSchema {
  code: e-book
},
  class ProductTypeSchema {
  code: e-newspaper
}
]}

Connecting to API

The Taxamo RESTful API is available through HTTP(S)/1.1 protocol and utilizes HTTP verbs and response codes.

If you want to use Taxamo directly from a website through JavaScript, you should review the JavaScript API.

For either production and test mode, RESTful API is available under https://api.taxamo.com/api/v1 URL - you just need to use a set of tokens according to the mode you want to use.

Example requests in API documentation are written using cURL command line tool, but you don’t have to use it at all.

Since Taxamo RESTful API is Swagger 1.2 compliant, it can be browsed and client libraries can be generated. For developers’ convenience, we have provided some of client bindings already:

If your technology is not listed above and you would like to use a client library, please contact us.

HTTP verbs and paths

HTTP verbs and paths for endpoints are following the REST conventions:

  • GET / - retrieve a list of resources. If supported, filtering, paging, and sorting is done through query params.
  • GET /:id - retrieve one resource
  • POST / - create new resource instance
  • PUT /:id - update existing resource
  • DELETE /:id - delete existing resource
  • POST /:id/action_name - execute action on a resource, for example confirm the transaction

Response codes

The following HTTP response codes are used:

  • 200 OK - successful operation
  • 400 Bad Request - invalid input parameters
  • 401 Unauthorized - missing or invalid access token
  • 500 Internal Server Error - unexpected error, please contact system support

Authenticating calls

Each Taxamo API invocation requires either public or private token. In some cases - POST /api/v1/transactions for example, both tokens can be used, resulting in more capabilities when the endpoint is invoked with a private token.

Public and private API tokens are available from a merchant dashboard, in Account settings panel. Public token is meant to be used when invoking the service through a user’s browser - for example from JavaScript.

Private token, on the other hand, is meant to be used when you are connecting from your service directly to the Taxamo REST API.

Tokens can be provided in two or three ways (depending on the request type):

  • query string parameter named respectively public_token or private_token
  • as an HTTP header named Public-Token for public token and Private-Token for private_token
  • inside request body as a field named respectively public_token or private_token. This option is of course available only when the operation has request body - e.g. is a POST or PUT.

Please consult documentation for individual endpoints to see what kind of access tokens are supported and how can they be supplied.

Test and production modes

There are two sets of API tokens:

  • Test tokens - used for testing and integration purposes. When using test tokens, transactions will not be settled with the actual tax authority, and if you are using Taxamo PSP integration, it will be invoked in test/sandbox mode.
  • Production tokens - transactions stored with production tokens will be used for actual settlement or billing. Production tokens will be generated once the merchant’s account is successfully registered for MOSS.

Examples

Public token in query params

$ curl https://api.taxamo.com/api/v1/dictionaries/product_types?public_token=SamplePublicTestKey1
{
  "dictionary": [
    { "code": "default" },
    { "code": "e-service" },
    { "code": "e-book"}
  ]
}
// With taxamo-java lib private token is supplied upon API object initialization
TaxamoApi api = new TaxamoApi("SamplePrivateTestKey1");

Private token as an HTTP header

$ curl -H "Private-Token: SamplePrivateTestKey1" https://api.taxamo.com/api/v1/tax/vat_numbers/6388047V/validate?country_code=IE
{
  "tax_deducted": true,
  "buyer_tax_number_valid": true,
  "buyer_tax_number": "6388047V",
  "billing_country_code": "IE"
}
// With taxamo-java lib private token is supplied upon API object initialization
TaxamoApi api = new TaxamoApi("SamplePrivateTestKey1");

Public token in request body

$ curl -X 'POST' -H "Content-Type: application/json" -d \
 '{
      "transaction": {
          "transaction_lines": [
              {
                  "custom_id": "line1",
                  "amount": 100
              }
          ],
          "billing_country_code": "IE"
      },
      "public_token": "SamplePublicTestKey1"
  }' \
 https://api.taxamo.com/api/v1/tax/calculate
{
  "order_date": "2013-11-15T14:54:58Z",
  "country_name": "Ireland",
  ...
  "tax_supported": true
}
// With taxamo-java lib private token is supplied upon API object initialization
TaxamoApi api = new TaxamoApi("SamplePrivateTestKey1");

Error handling

If something goes wrong with processing of the request, appropriate HTTP error code is returned - for example 400 Bad Request or 500 Internal server error.

In addition, the response contains errors array, containing error messages - usually just one, but it can contain more in more complex scenarios - multiple validation errors for example.

In some cases, for example tax calculation, even when an error occurs, the response might contain additional information - for example country detected from an IP address. Please consult individual endpoint for detailed information.

Example error response

curl https://api.taxamo.com/api/v1/geoip/wrong_ip?private_token=SamplePrivateTestKey1
{
  "errors": [
    "Please provide correct IPv4 address."
  ]
}
TaxamoApi taxamoApi = new TaxamoApi("SamplePrivateTestKey1");

LocateGivenIPOut result;

try {
    result = taxamoApi.locateGivenIP("wrong ip");
} catch (ApiException ae) {
    ...
    System.out.println(ae);
}

// exception:
com.taxamo.client.common.ApiException: {"errors":["Please provide correct IPv4 or IPv6 address."]}

Supported formats

The REST API supports several input and output formats. By default, it tries to guess it from:

  • Accept HTTP header, e.g. Accept: application/json
  • Content-Type HTTP header, e.g. ’Content-Type: application/json`

The detection can also be overridden using format query parameter, for example ?format=yaml. Default format is JSON.

Currently supported input and output formats are:

Additionally, output can formatted with YAML in HTML for easier browser debugging of the API - try it here.

Default format - JSON

curl https://api.taxamo.com/api/v1/tax/location/calculate?public_token=SamplePublicTestKey1
{
  "tax_supported": null,
  "countries": {
    "by_ip": {
      "tax_supported": true,
      "codenum": 372,
      "code_long": "IRL",
      "name": "Ireland",
      "code": "IE"
    },
    "by_cc": null,
    "by_tax_number": null,
    "detected": null,
    "by_billing": null
  },
  "country_name": null,
  "tax_country_code": null,
  "tax_deducted": false,
  "billing_country_code": null,
  "buyer_credit_card_prefix": null,
  "buyer_ip": "127.0.0.1"
}
// With taxamo-java lib response objects are regular Java object from com.taxamo.client.model package

EDN from Accept header

curl -H "Accept: application/edn" \
 'https://api.taxamo.com/api/v1/tax/location/calculate?public_token=SamplePublicTestKey1'
{:tax_supported nil,
 :countries {:by_ip {:tax_supported true, :codenum 372, :code_long "IRL", :name "Ireland", :code "IE"},
             :by_cc nil,
             :by_tax_number nil,
             :detected nil,
             :by_billing nil},
 :country_name nil,
 :tax_country_code nil,
 :tax_deducted false,
 :billing_country_code nil,
 :buyer_credit_card_prefix nil,
 :buyer_ip "127.0.0.1"}
// With taxamo-java lib response objects are regular Java object from com.taxamo.client.model package

Retrieve YAML with parameter (regardless of headers)

curl -H "Accept: application/edn" \
 'https://api.taxamo.com/api/v1/tax/location/calculate?public_token=SamplePublicTestKey1&format=yaml'
tax_supported: null
countries:
  by_ip: {tax_supported: true, codenum: 372, code_long: IRL, name: Ireland, code: IE}
  by_cc: null
  by_tax_number: null
  detected: null
  by_billing: null
country_name: null
tax_country_code: null
tax_deducted: false
billing_country_code: null
buyer_credit_card_prefix: null
buyer_ip: 127.0.0.1
// With taxamo-java lib response objects are regular Java object from com.taxamo.client.model package