Calculations
Tax calculations
This endpoint calculates tax for an invoice based on the provided request data. To learn more about how tax is calculated, see the tax calculation guide.
It processes the invoice details and returns calculated tax information, including individual tax items and total tax due.
- Input: Details about the invoice.
- Output: Response with total tax due and calculated tax details broken up by line item and jurisdiction.
Raises an HTTPException if there’s an error processing while the request,
translating to a non 200 status code response.
POST
/
calculations
Calculate Tax for Invoice
curl --request POST \
--url https://api.taxwire.com/calculations \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"currency": "USD",
"discount_amount": "100",
"vendor_discount_amount": "100",
"transaction_date": "2024-03-15T12:00:00Z",
"line_items": [
{
"customer": {
"address": {
"city": "Anytown",
"line1": "123 Main St",
"postal_code": "12345",
"state": "CA"
},
"tax_ids": [
{
"country": "DE",
"type": "eu_vat",
"value": "DE123456789"
}
]
},
"id": "item_123",
"product": {
"tax_attributes": [
"DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"
]
},
"quantity": "1",
"unit_price": "100"
}
]
}
'import requests
url = "https://api.taxwire.com/calculations"
payload = {
"currency": "USD",
"discount_amount": "100",
"vendor_discount_amount": "100",
"transaction_date": "2024-03-15T12:00:00Z",
"line_items": [
{
"customer": {
"address": {
"city": "Anytown",
"line1": "123 Main St",
"postal_code": "12345",
"state": "CA"
},
"tax_ids": [
{
"country": "DE",
"type": "eu_vat",
"value": "DE123456789"
}
]
},
"id": "item_123",
"product": { "tax_attributes": ["DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"] },
"quantity": "1",
"unit_price": "100"
}
]
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
currency: 'USD',
discount_amount: '100',
vendor_discount_amount: '100',
transaction_date: '2024-03-15T12:00:00Z',
line_items: [
{
customer: {
address: {city: 'Anytown', line1: '123 Main St', postal_code: '12345', state: 'CA'},
tax_ids: [{country: 'DE', type: 'eu_vat', value: 'DE123456789'}]
},
id: 'item_123',
product: {tax_attributes: ['DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED']},
quantity: '1',
unit_price: '100'
}
]
})
};
fetch('https://api.taxwire.com/calculations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.taxwire.com/calculations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'currency' => 'USD',
'discount_amount' => '100',
'vendor_discount_amount' => '100',
'transaction_date' => '2024-03-15T12:00:00Z',
'line_items' => [
[
'customer' => [
'address' => [
'city' => 'Anytown',
'line1' => '123 Main St',
'postal_code' => '12345',
'state' => 'CA'
],
'tax_ids' => [
[
'country' => 'DE',
'type' => 'eu_vat',
'value' => 'DE123456789'
]
]
],
'id' => 'item_123',
'product' => [
'tax_attributes' => [
'DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED'
]
],
'quantity' => '1',
'unit_price' => '100'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.taxwire.com/calculations"
payload := strings.NewReader("{\n \"currency\": \"USD\",\n \"discount_amount\": \"100\",\n \"vendor_discount_amount\": \"100\",\n \"transaction_date\": \"2024-03-15T12:00:00Z\",\n \"line_items\": [\n {\n \"customer\": {\n \"address\": {\n \"city\": \"Anytown\",\n \"line1\": \"123 Main St\",\n \"postal_code\": \"12345\",\n \"state\": \"CA\"\n },\n \"tax_ids\": [\n {\n \"country\": \"DE\",\n \"type\": \"eu_vat\",\n \"value\": \"DE123456789\"\n }\n ]\n },\n \"id\": \"item_123\",\n \"product\": {\n \"tax_attributes\": [\n \"DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED\"\n ]\n },\n \"quantity\": \"1\",\n \"unit_price\": \"100\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.taxwire.com/calculations")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"currency\": \"USD\",\n \"discount_amount\": \"100\",\n \"vendor_discount_amount\": \"100\",\n \"transaction_date\": \"2024-03-15T12:00:00Z\",\n \"line_items\": [\n {\n \"customer\": {\n \"address\": {\n \"city\": \"Anytown\",\n \"line1\": \"123 Main St\",\n \"postal_code\": \"12345\",\n \"state\": \"CA\"\n },\n \"tax_ids\": [\n {\n \"country\": \"DE\",\n \"type\": \"eu_vat\",\n \"value\": \"DE123456789\"\n }\n ]\n },\n \"id\": \"item_123\",\n \"product\": {\n \"tax_attributes\": [\n \"DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED\"\n ]\n },\n \"quantity\": \"1\",\n \"unit_price\": \"100\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.taxwire.com/calculations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"currency\": \"USD\",\n \"discount_amount\": \"100\",\n \"vendor_discount_amount\": \"100\",\n \"transaction_date\": \"2024-03-15T12:00:00Z\",\n \"line_items\": [\n {\n \"customer\": {\n \"address\": {\n \"city\": \"Anytown\",\n \"line1\": \"123 Main St\",\n \"postal_code\": \"12345\",\n \"state\": \"CA\"\n },\n \"tax_ids\": [\n {\n \"country\": \"DE\",\n \"type\": \"eu_vat\",\n \"value\": \"DE123456789\"\n }\n ]\n },\n \"id\": \"item_123\",\n \"product\": {\n \"tax_attributes\": [\n \"DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED\"\n ]\n },\n \"quantity\": \"1\",\n \"unit_price\": \"100\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"tax_amount": "2999",
"line_items": [
{
"id": "<string>",
"tax_amount": "<string>",
"taxes": [
{
"detail": "County Transportation Fund",
"jurisdiction_name": "California",
"jurisdiction_type": "state",
"tax_amount": "10",
"tax_type": "California District Transaction Tax",
"is_registered": true,
"rule_name": "Clothing taxability rule",
"taxable_base": "100",
"tax_rate": "0.05",
"rate_type": "percentage"
}
],
"tax_amount_before_discounts": "<string>",
"discounts": [
{
"id": "disc_123",
"tax_amount_reduction": "400"
}
]
}
],
"currency": "USD"
}{
"errors": [
{
"status": "422",
"code": "validation_required_field",
"title": "Missing quantity",
"detail": "Please provide a value for the required quantity field",
"source": {
"pointer": "/data/attributes/line_items/0/quantity"
}
}
]
}{
"errors": [
{
"status": "429",
"code": "rate_limit_error",
"title": "Too Many Requests",
"detail": "Rate limit exceeded"
}
]
}{
"errors": [
{
"status": "500",
"code": "system_internal_error",
"title": "Internal Error",
"detail": "An unexpected error occurred. Our team has been notified."
}
]
}Currency
Acurrency we do not support returns 422. See currency support.
Note on registrations
By default, tax will be calculated as zero if you attempt to perform a calculation in a customer location where your company is not yet registered. If you provide anX-Include-Unregistered: true header, this requirement is overridden, and tax will be nonzero in some cases even when unregistered in that jurisdiction.Authorizations
APIKeyHeaderHTTPBearer
Body
application/json
Create calculation request model.
The currency of the transaction. Defaults to USD. The currency must be a valid ISO 4217 currency code.
Required string length:
3Example:
"USD"
Amount of discount applied to the transaction. Amount is expressed in the currency of the transaction and in denominations of the smallest unit of the currency, such as cents for USD. e.g: "100" would be 100 cents or $1.00 in a USD transaction.
Example:
"100"
Amount of discount applied to the vendor in the transaction. Most of the time, you should use the discount_amount field instead. Unlike discount_amount, this discount is funded by the vendor and typically does not reduce the taxable base of the transaction. Amount is expressed in the currency of the transaction and in denominations of the smallest unit of the currency, such as cents for USD. e.g: "100" would be 100 cents or $1.00 in a USD transaction.
Example:
"100"
List of line items for an invoice or transaction. Required for sale transactions, optional for credits. A credit transaction without line_items will be assumed to be a full refund of the invoice.
Show child attributes
Show child attributes
Example:
[
{
"customer": {
"address": {
"city": "Anytown",
"line1": "123 Main St",
"postal_code": "12345",
"state": "CA"
},
"tax_ids": [
{
"country": "DE",
"type": "eu_vat",
"value": "DE123456789"
}
]
},
"id": "item_123",
"product": {
"tax_attributes": [
"DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"
]
},
"quantity": "1",
"unit_price": "100"
}
]
Response
Successful Response
Response model containing the calculated tax details for an invoice.
Total tax amount due, expressed in the smallest unit of currency for the invoice.e.g: "2999", which for a USD invoice means $29.99
Example:
"2999"
List of line items for the invoice
Show child attributes
Show child attributes
Three-letter currency code. Values are limited to valid ISO 4217 currency codes. e.g: USD
Required string length:
3Example:
"USD"
⌘I
Calculate Tax for Invoice
curl --request POST \
--url https://api.taxwire.com/calculations \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"currency": "USD",
"discount_amount": "100",
"vendor_discount_amount": "100",
"transaction_date": "2024-03-15T12:00:00Z",
"line_items": [
{
"customer": {
"address": {
"city": "Anytown",
"line1": "123 Main St",
"postal_code": "12345",
"state": "CA"
},
"tax_ids": [
{
"country": "DE",
"type": "eu_vat",
"value": "DE123456789"
}
]
},
"id": "item_123",
"product": {
"tax_attributes": [
"DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"
]
},
"quantity": "1",
"unit_price": "100"
}
]
}
'import requests
url = "https://api.taxwire.com/calculations"
payload = {
"currency": "USD",
"discount_amount": "100",
"vendor_discount_amount": "100",
"transaction_date": "2024-03-15T12:00:00Z",
"line_items": [
{
"customer": {
"address": {
"city": "Anytown",
"line1": "123 Main St",
"postal_code": "12345",
"state": "CA"
},
"tax_ids": [
{
"country": "DE",
"type": "eu_vat",
"value": "DE123456789"
}
]
},
"id": "item_123",
"product": { "tax_attributes": ["DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED"] },
"quantity": "1",
"unit_price": "100"
}
]
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
currency: 'USD',
discount_amount: '100',
vendor_discount_amount: '100',
transaction_date: '2024-03-15T12:00:00Z',
line_items: [
{
customer: {
address: {city: 'Anytown', line1: '123 Main St', postal_code: '12345', state: 'CA'},
tax_ids: [{country: 'DE', type: 'eu_vat', value: 'DE123456789'}]
},
id: 'item_123',
product: {tax_attributes: ['DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED']},
quantity: '1',
unit_price: '100'
}
]
})
};
fetch('https://api.taxwire.com/calculations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.taxwire.com/calculations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'currency' => 'USD',
'discount_amount' => '100',
'vendor_discount_amount' => '100',
'transaction_date' => '2024-03-15T12:00:00Z',
'line_items' => [
[
'customer' => [
'address' => [
'city' => 'Anytown',
'line1' => '123 Main St',
'postal_code' => '12345',
'state' => 'CA'
],
'tax_ids' => [
[
'country' => 'DE',
'type' => 'eu_vat',
'value' => 'DE123456789'
]
]
],
'id' => 'item_123',
'product' => [
'tax_attributes' => [
'DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED'
]
],
'quantity' => '1',
'unit_price' => '100'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.taxwire.com/calculations"
payload := strings.NewReader("{\n \"currency\": \"USD\",\n \"discount_amount\": \"100\",\n \"vendor_discount_amount\": \"100\",\n \"transaction_date\": \"2024-03-15T12:00:00Z\",\n \"line_items\": [\n {\n \"customer\": {\n \"address\": {\n \"city\": \"Anytown\",\n \"line1\": \"123 Main St\",\n \"postal_code\": \"12345\",\n \"state\": \"CA\"\n },\n \"tax_ids\": [\n {\n \"country\": \"DE\",\n \"type\": \"eu_vat\",\n \"value\": \"DE123456789\"\n }\n ]\n },\n \"id\": \"item_123\",\n \"product\": {\n \"tax_attributes\": [\n \"DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED\"\n ]\n },\n \"quantity\": \"1\",\n \"unit_price\": \"100\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.taxwire.com/calculations")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"currency\": \"USD\",\n \"discount_amount\": \"100\",\n \"vendor_discount_amount\": \"100\",\n \"transaction_date\": \"2024-03-15T12:00:00Z\",\n \"line_items\": [\n {\n \"customer\": {\n \"address\": {\n \"city\": \"Anytown\",\n \"line1\": \"123 Main St\",\n \"postal_code\": \"12345\",\n \"state\": \"CA\"\n },\n \"tax_ids\": [\n {\n \"country\": \"DE\",\n \"type\": \"eu_vat\",\n \"value\": \"DE123456789\"\n }\n ]\n },\n \"id\": \"item_123\",\n \"product\": {\n \"tax_attributes\": [\n \"DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED\"\n ]\n },\n \"quantity\": \"1\",\n \"unit_price\": \"100\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.taxwire.com/calculations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"currency\": \"USD\",\n \"discount_amount\": \"100\",\n \"vendor_discount_amount\": \"100\",\n \"transaction_date\": \"2024-03-15T12:00:00Z\",\n \"line_items\": [\n {\n \"customer\": {\n \"address\": {\n \"city\": \"Anytown\",\n \"line1\": \"123 Main St\",\n \"postal_code\": \"12345\",\n \"state\": \"CA\"\n },\n \"tax_ids\": [\n {\n \"country\": \"DE\",\n \"type\": \"eu_vat\",\n \"value\": \"DE123456789\"\n }\n ]\n },\n \"id\": \"item_123\",\n \"product\": {\n \"tax_attributes\": [\n \"DIGITAL_PROPERTY.DIGITAL_SOFTWARE._DOWNLOADED\"\n ]\n },\n \"quantity\": \"1\",\n \"unit_price\": \"100\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"tax_amount": "2999",
"line_items": [
{
"id": "<string>",
"tax_amount": "<string>",
"taxes": [
{
"detail": "County Transportation Fund",
"jurisdiction_name": "California",
"jurisdiction_type": "state",
"tax_amount": "10",
"tax_type": "California District Transaction Tax",
"is_registered": true,
"rule_name": "Clothing taxability rule",
"taxable_base": "100",
"tax_rate": "0.05",
"rate_type": "percentage"
}
],
"tax_amount_before_discounts": "<string>",
"discounts": [
{
"id": "disc_123",
"tax_amount_reduction": "400"
}
]
}
],
"currency": "USD"
}{
"errors": [
{
"status": "422",
"code": "validation_required_field",
"title": "Missing quantity",
"detail": "Please provide a value for the required quantity field",
"source": {
"pointer": "/data/attributes/line_items/0/quantity"
}
}
]
}{
"errors": [
{
"status": "429",
"code": "rate_limit_error",
"title": "Too Many Requests",
"detail": "Rate limit exceeded"
}
]
}{
"errors": [
{
"status": "500",
"code": "system_internal_error",
"title": "Internal Error",
"detail": "An unexpected error occurred. Our team has been notified."
}
]
}