External tax calculators

Getting started API reference How-tos Changelog
Search…
How to manage custom tax calculation via external services
Commerce Layer supports automatic tax calculation thanks to the out-of-the-box integration with Avalara and TaxJar. Manual tax calculators can be also configured. On top of that, you also have the complete flexibility to implement any particular custom tax calculation logic building your own external tax calculator.
Whenever the tax calculation is fired, Commerce Layer triggers a POST request to the tax_calculator_url endpoint, sending the order payload (including its line items and their items) in the request body. To trigger the tax update, the order must be not archived and have the following attributes:
a valid shipping_address or a valid billing_address
an external_tax_calculator associated with the market in scope
a positive total_amount_cent
at least one SKU among its line item (gift card are not taxed)
Taxes data granularity
External taxes can be applied either to the whole order or to specific line items, depending on how granular your response is. If you need to pass tax values at line item level and set tax breakdown attributes, you need to include in the response an array containing the line items you want to be affected by the tax update and specify each line item ID, as the payload passed in the request to your external calculator.
Values precedence
When designing your external tax calculator response, bear in mind that some values take precedence over other ones, according to the following logic.
1. Line item tax collectable
If the tax_collectable attribute is specified for a line item, its value is used to compute the tax_amount_cents for the line item, no matter what's the value of the line item tax_rate (if any).
The tax_collectable attribute is a float (e.g. "tax_collectable": 9.0 sets the line item tax_amount_cents to 900).
2. Line item tax rate
If the tax_collectable is missing for a line item, the line item tax_amount_cents is computed using the line item tax_rate.
3. Global tax rate
If both the line item tax_collectable and tax_rate are missing, the line item tax_amount_cents is computed using the tax_rate specified at the data level. If the line items array is missing, that tax rate is applied to the whole order.
Request
The request payload is a JSON:API compliant object you can query to perform your own computation. Aside from the target resource — orders in the specific case — some relationships are also included to avoid useless API roundtrips:
market
line_items
line_items.item
shipping_address
billing_address
1
{
2
  "data": {
3
    "id": "wBXVhKzrnq",
4
    "type": "orders",
5
    "links": { ... },
6
    "attributes": { ... },
7
    "relationships": { ... },
8
    "meta": { ... }
9
  },
10
  "included": [
11
    {
12
      "id": "DvlGRmhdgX",
13
      "type": "markets",
14
      "links": { ... },
15
      "attributes": { ... },
16
      "relationships": { ... },
17
      "meta": { ... }
18
    },
19
    {
20
      "id": "kdPgtRXOKL",
21
      "type": "line_items",
22
      "links": { ... },
23
      "attributes": { ... },
24
      "relationships": { ... },
25
      "meta": { ... }
26
    },
27
    {
28
      "id": "XGZwpOSrWL",
29
      "type": "skus",
30
      "links": { ... },
31
      "attributes": { ... },
32
      "relationships": { ... },
33
      "meta": { ... }
34
    }
35
    {
36
      "id": "BgnguJvXmb",
37
      "type": "addresses",
38
      "links": { ... },
39
      "attributes": { ... },
40
      "relationships": { ... },
41
      "meta": { ... }
42
    },
43
    {
44
      "id": "AlrkugwyVW",
45
      "type": "addresses",
46
      "links": { ... },
47
      "attributes": { ... },
48
      "relationships": { ... },
49
      "meta": { ... }
50
    },
51
    { ... }
52
  ]
53
}
Copied!
Response
Your service response (or error) must match the format described in the examples below.
Applying the same tax rate to the whole order
Response
Error
The successful response must be a JSON object, returning the tax rate to be applied to the whole order, along with some additional information and metadata:
1
{
2
  "success": true,
3
  "data": {
4
    "tax_rate": 0.25,
5
    "metadata": {
6
      "foo": "bar"
7
    }
8
  }
9
}
Copied!
On error, you must respond with an HTTP code >= 400. The response body must be a JSON object containing any other relevant error code and message:
1
{
2
  "success": false,
3
  "error": {
4
    "code": "YOUR-ERROR-CODE",
5
    "message": "Your error message"
6
  }
7
}
Copied!
Applying different tax rates for some line items
Response
Error
The successful response must be a JSON object, returning the specific tax rate to be applied to the line items, along with some additional information and metadata:
1
{
2
  "success": true,
3
  "data": {
4
    "tax_rate": 0.25,
5
    "line_items": [
6
      {
7
        "id": "kxnXtEaGxo",
8
        "tax_rate": 0.3
9
      },
10
      {
11
        "id": "kXBqtrgARW",
12
        "tax_rate": 0.4
13
      }
14
    ],
15
    "metadata": {
16
      "foo": "bar"
17
    }
18
  }
19
}
Copied!
On error, you must respond with an HTTP code >= 400. The response body must be a JSON object containing any other relevant error code and message:
1
{
2
  "success": false,
3
  "error": {
4
    "code": "YOUR-ERROR-CODE",
5
    "message": "Your error message"
6
  }
7
}
Copied!
More complex external tax calculation affecting the tax breakdown
Response
Error
The successful response must be a JSON object, returning specific tax collectable and tax rate values to be applied to the line items, some attributes you want to set in the line items tax breakdown, along with some additional information and metadata:
1
{
2
  "success": true,
3
  "data": {
4
    "freight_taxable": true,
5
    "tax_rate": 0.25,
6
    "line_items": [
7
      {
8
        "id": "kxnXtEaGxo",
9
        "tax_collectable": 2.25,
10
        "country_tax_collectable": 9,
11
        "country_tax_rate": 0.2,
12
        "country_taxable_amount": 9,
13
        "special_tax_rate": 0.05,
14
        "taxable_amount": 10,
15
        "tax_rate": 0.4
16
      },
17
      {
18
        "id": "kXBqtrgARW",
19
        "taxable_amount": 12,
20
        "tax_rate": 0.3
21
      }
22
    ],
23
    "metadata": {
24
      "foo": "bar"
25
    }
26
  }
27
}
Copied!
On error, you must respond with an HTTP code >= 400. The response body must be a JSON object containing any other relevant error code and message:
1
{
2
  "success": false,
3
  "error": {
4
    "code": "YOUR-ERROR-CODE",
5
    "message": "Your error message"
6
  }
7
}
Copied!
Security
When you create a new external tax calculator, a shared secret is generated. We recommend verifying the callback authenticity by signing the payload with that shared secret and comparing the result with the callback signature header.
Callbacks security
External promotions
Handling errors
Last modified 1mo ago
Copy link
Contents
Taxes data granularity