Create a calculation
curl --request POST \
--url https://api.numeralhq.com/tax/calculations \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--header 'X-API-Version: <x-api-version>' \
--data '
{
"customer": {
"address": {
"address_line_1": "<string>",
"address_line_2": "<string>",
"address_city": "<string>",
"address_province": "<string>",
"address_postal_code": "<string>",
"address_country": "<string>",
"address_type": "<string>"
},
"ip": {
"value": "<string>",
"resolution": "<string>"
},
"id": "<string>",
"type": "<string>",
"tax_ids": [
{
"type": "<string>",
"value": "<string>"
}
],
"skip_tax_id_validation": true
},
"order_details": {
"customer_currency_code": "<string>",
"tax_included_in_amount": true,
"automatic_tax": "<string>",
"line_items": [
{
"amount": 123,
"quantity": 123,
"product_category": "<string>",
"reference_product_id": "<string>",
"fallback_product_category": "<string>",
"reference_line_item_id": "<string>"
}
]
},
"origin_address": {
"address_line_1": "<string>",
"address_line_2": "<string>",
"address_city": "<string>",
"address_province": "<string>",
"address_postal_code": "<string>",
"address_country": "<string>"
},
"transacted_at": 123,
"default_customer_type": "<string>",
"invalid_tax_id_customer_fallback_type": "<string>",
"metadata": {}
}
'import requests
url = "https://api.numeralhq.com/tax/calculations"
payload = {
"customer": {
"address": {
"address_line_1": "<string>",
"address_line_2": "<string>",
"address_city": "<string>",
"address_province": "<string>",
"address_postal_code": "<string>",
"address_country": "<string>",
"address_type": "<string>"
},
"ip": {
"value": "<string>",
"resolution": "<string>"
},
"id": "<string>",
"type": "<string>",
"tax_ids": [
{
"type": "<string>",
"value": "<string>"
}
],
"skip_tax_id_validation": True
},
"order_details": {
"customer_currency_code": "<string>",
"tax_included_in_amount": True,
"automatic_tax": "<string>",
"line_items": [
{
"amount": 123,
"quantity": 123,
"product_category": "<string>",
"reference_product_id": "<string>",
"fallback_product_category": "<string>",
"reference_line_item_id": "<string>"
}
]
},
"origin_address": {
"address_line_1": "<string>",
"address_line_2": "<string>",
"address_city": "<string>",
"address_province": "<string>",
"address_postal_code": "<string>",
"address_country": "<string>"
},
"transacted_at": 123,
"default_customer_type": "<string>",
"invalid_tax_id_customer_fallback_type": "<string>",
"metadata": {}
}
headers = {
"Authorization": "<authorization>",
"X-API-Version": "<x-api-version>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: '<authorization>',
'X-API-Version': '<x-api-version>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
customer: {
address: {
address_line_1: '<string>',
address_line_2: '<string>',
address_city: '<string>',
address_province: '<string>',
address_postal_code: '<string>',
address_country: '<string>',
address_type: '<string>'
},
ip: {value: '<string>', resolution: '<string>'},
id: '<string>',
type: '<string>',
tax_ids: [{type: '<string>', value: '<string>'}],
skip_tax_id_validation: true
},
order_details: {
customer_currency_code: '<string>',
tax_included_in_amount: true,
automatic_tax: '<string>',
line_items: [
{
amount: 123,
quantity: 123,
product_category: '<string>',
reference_product_id: '<string>',
fallback_product_category: '<string>',
reference_line_item_id: '<string>'
}
]
},
origin_address: {
address_line_1: '<string>',
address_line_2: '<string>',
address_city: '<string>',
address_province: '<string>',
address_postal_code: '<string>',
address_country: '<string>'
},
transacted_at: 123,
default_customer_type: '<string>',
invalid_tax_id_customer_fallback_type: '<string>',
metadata: {}
})
};
fetch('https://api.numeralhq.com/tax/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.numeralhq.com/tax/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([
'customer' => [
'address' => [
'address_line_1' => '<string>',
'address_line_2' => '<string>',
'address_city' => '<string>',
'address_province' => '<string>',
'address_postal_code' => '<string>',
'address_country' => '<string>',
'address_type' => '<string>'
],
'ip' => [
'value' => '<string>',
'resolution' => '<string>'
],
'id' => '<string>',
'type' => '<string>',
'tax_ids' => [
[
'type' => '<string>',
'value' => '<string>'
]
],
'skip_tax_id_validation' => true
],
'order_details' => [
'customer_currency_code' => '<string>',
'tax_included_in_amount' => true,
'automatic_tax' => '<string>',
'line_items' => [
[
'amount' => 123,
'quantity' => 123,
'product_category' => '<string>',
'reference_product_id' => '<string>',
'fallback_product_category' => '<string>',
'reference_line_item_id' => '<string>'
]
]
],
'origin_address' => [
'address_line_1' => '<string>',
'address_line_2' => '<string>',
'address_city' => '<string>',
'address_province' => '<string>',
'address_postal_code' => '<string>',
'address_country' => '<string>'
],
'transacted_at' => 123,
'default_customer_type' => '<string>',
'invalid_tax_id_customer_fallback_type' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json",
"X-API-Version: <x-api-version>"
],
]);
$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.numeralhq.com/tax/calculations"
payload := strings.NewReader("{\n \"customer\": {\n \"address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\",\n \"address_type\": \"<string>\"\n },\n \"ip\": {\n \"value\": \"<string>\",\n \"resolution\": \"<string>\"\n },\n \"id\": \"<string>\",\n \"type\": \"<string>\",\n \"tax_ids\": [\n {\n \"type\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"skip_tax_id_validation\": true\n },\n \"order_details\": {\n \"customer_currency_code\": \"<string>\",\n \"tax_included_in_amount\": true,\n \"automatic_tax\": \"<string>\",\n \"line_items\": [\n {\n \"amount\": 123,\n \"quantity\": 123,\n \"product_category\": \"<string>\",\n \"reference_product_id\": \"<string>\",\n \"fallback_product_category\": \"<string>\",\n \"reference_line_item_id\": \"<string>\"\n }\n ]\n },\n \"origin_address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\"\n },\n \"transacted_at\": 123,\n \"default_customer_type\": \"<string>\",\n \"invalid_tax_id_customer_fallback_type\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("X-API-Version", "<x-api-version>")
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.numeralhq.com/tax/calculations")
.header("Authorization", "<authorization>")
.header("X-API-Version", "<x-api-version>")
.header("Content-Type", "application/json")
.body("{\n \"customer\": {\n \"address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\",\n \"address_type\": \"<string>\"\n },\n \"ip\": {\n \"value\": \"<string>\",\n \"resolution\": \"<string>\"\n },\n \"id\": \"<string>\",\n \"type\": \"<string>\",\n \"tax_ids\": [\n {\n \"type\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"skip_tax_id_validation\": true\n },\n \"order_details\": {\n \"customer_currency_code\": \"<string>\",\n \"tax_included_in_amount\": true,\n \"automatic_tax\": \"<string>\",\n \"line_items\": [\n {\n \"amount\": 123,\n \"quantity\": 123,\n \"product_category\": \"<string>\",\n \"reference_product_id\": \"<string>\",\n \"fallback_product_category\": \"<string>\",\n \"reference_line_item_id\": \"<string>\"\n }\n ]\n },\n \"origin_address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\"\n },\n \"transacted_at\": 123,\n \"default_customer_type\": \"<string>\",\n \"invalid_tax_id_customer_fallback_type\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.numeralhq.com/tax/calculations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["X-API-Version"] = '<x-api-version>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customer\": {\n \"address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\",\n \"address_type\": \"<string>\"\n },\n \"ip\": {\n \"value\": \"<string>\",\n \"resolution\": \"<string>\"\n },\n \"id\": \"<string>\",\n \"type\": \"<string>\",\n \"tax_ids\": [\n {\n \"type\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"skip_tax_id_validation\": true\n },\n \"order_details\": {\n \"customer_currency_code\": \"<string>\",\n \"tax_included_in_amount\": true,\n \"automatic_tax\": \"<string>\",\n \"line_items\": [\n {\n \"amount\": 123,\n \"quantity\": 123,\n \"product_category\": \"<string>\",\n \"reference_product_id\": \"<string>\",\n \"fallback_product_category\": \"<string>\",\n \"reference_line_item_id\": \"<string>\"\n }\n ]\n },\n \"origin_address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\"\n },\n \"transacted_at\": 123,\n \"default_customer_type\": \"<string>\",\n \"invalid_tax_id_customer_fallback_type\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"testmode": true,
"id": "calc_1793039299123",
"object": "tax.calculation",
"customer_currency_code": "USD",
"line_items": [
{
"line_item_id": "li_1793039299101",
"product": {
"reference_line_item_id": "widget",
"reference_product_id": "default-general-merchandise",
"reference_product_name": "Default GENERAL_MERCHANDISE Product",
"product_tax_code": "GENERAL_MERCHANDISE"
},
"tax_jurisdictions": [
{
"tax_rate": 0.0625,
"tax_due_decimal": 625,
"fee_amount": 0,
"rate_type": "GENERAL STATE SALES TAX",
"tax_authority_name": "Illinois",
"tax_authority_type": "",
"tax_type": "SALES",
"note": ""
},
{
"tax_rate": 0.03,
"tax_due_decimal": 300,
"fee_amount": 0,
"rate_type": "GENERAL COUNTY LOCAL SALES TAX",
"tax_authority_name": "Cook County",
"tax_authority_type": "",
"tax_type": "SALES",
"note": ""
},
{
"tax_rate": 0.0125,
"tax_due_decimal": 125,
"fee_amount": 0,
"rate_type": "GENERAL CITY LOCAL SALES TAX",
"tax_authority_name": "Chicago",
"tax_authority_type": "",
"tax_type": "SALES",
"note": ""
}
],
"tax_amount": 1050,
"amount_excluding_tax": 10000,
"amount_including_tax": 11050,
"quantity": 2
},
"... shipping line, tax_amount 105 on 1000 ..."
],
"total_tax_amount": 1155,
"tax_included_in_amount": false,
"total_amount_excluding_tax": 11000,
"total_amount_including_tax": 12155,
"expires_at": 1793125699,
"customer": {
"type": "CONSUMER"
},
"automatic_tax": "auto",
"address_resolution_status": "EXACT",
"address_used": {
"address_line_1": "233 S Wacker Dr",
"address_city": "Chicago",
"address_province": "IL",
"address_postal_code": "60606",
"address_country": "US"
},
"location_source": "address",
"resolution_precision": "STREET",
"effective_tax_rate": 0.105
}
{
"code": 400,
"type": "MISSING_FIELD",
"message": "Field 'order_details.automatic_tax' is required"
}
Create a calculation
Quote the tax for a cart. Returns a Calculation object.
POST
/
tax
/
calculations
Create a calculation
curl --request POST \
--url https://api.numeralhq.com/tax/calculations \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--header 'X-API-Version: <x-api-version>' \
--data '
{
"customer": {
"address": {
"address_line_1": "<string>",
"address_line_2": "<string>",
"address_city": "<string>",
"address_province": "<string>",
"address_postal_code": "<string>",
"address_country": "<string>",
"address_type": "<string>"
},
"ip": {
"value": "<string>",
"resolution": "<string>"
},
"id": "<string>",
"type": "<string>",
"tax_ids": [
{
"type": "<string>",
"value": "<string>"
}
],
"skip_tax_id_validation": true
},
"order_details": {
"customer_currency_code": "<string>",
"tax_included_in_amount": true,
"automatic_tax": "<string>",
"line_items": [
{
"amount": 123,
"quantity": 123,
"product_category": "<string>",
"reference_product_id": "<string>",
"fallback_product_category": "<string>",
"reference_line_item_id": "<string>"
}
]
},
"origin_address": {
"address_line_1": "<string>",
"address_line_2": "<string>",
"address_city": "<string>",
"address_province": "<string>",
"address_postal_code": "<string>",
"address_country": "<string>"
},
"transacted_at": 123,
"default_customer_type": "<string>",
"invalid_tax_id_customer_fallback_type": "<string>",
"metadata": {}
}
'import requests
url = "https://api.numeralhq.com/tax/calculations"
payload = {
"customer": {
"address": {
"address_line_1": "<string>",
"address_line_2": "<string>",
"address_city": "<string>",
"address_province": "<string>",
"address_postal_code": "<string>",
"address_country": "<string>",
"address_type": "<string>"
},
"ip": {
"value": "<string>",
"resolution": "<string>"
},
"id": "<string>",
"type": "<string>",
"tax_ids": [
{
"type": "<string>",
"value": "<string>"
}
],
"skip_tax_id_validation": True
},
"order_details": {
"customer_currency_code": "<string>",
"tax_included_in_amount": True,
"automatic_tax": "<string>",
"line_items": [
{
"amount": 123,
"quantity": 123,
"product_category": "<string>",
"reference_product_id": "<string>",
"fallback_product_category": "<string>",
"reference_line_item_id": "<string>"
}
]
},
"origin_address": {
"address_line_1": "<string>",
"address_line_2": "<string>",
"address_city": "<string>",
"address_province": "<string>",
"address_postal_code": "<string>",
"address_country": "<string>"
},
"transacted_at": 123,
"default_customer_type": "<string>",
"invalid_tax_id_customer_fallback_type": "<string>",
"metadata": {}
}
headers = {
"Authorization": "<authorization>",
"X-API-Version": "<x-api-version>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: '<authorization>',
'X-API-Version': '<x-api-version>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
customer: {
address: {
address_line_1: '<string>',
address_line_2: '<string>',
address_city: '<string>',
address_province: '<string>',
address_postal_code: '<string>',
address_country: '<string>',
address_type: '<string>'
},
ip: {value: '<string>', resolution: '<string>'},
id: '<string>',
type: '<string>',
tax_ids: [{type: '<string>', value: '<string>'}],
skip_tax_id_validation: true
},
order_details: {
customer_currency_code: '<string>',
tax_included_in_amount: true,
automatic_tax: '<string>',
line_items: [
{
amount: 123,
quantity: 123,
product_category: '<string>',
reference_product_id: '<string>',
fallback_product_category: '<string>',
reference_line_item_id: '<string>'
}
]
},
origin_address: {
address_line_1: '<string>',
address_line_2: '<string>',
address_city: '<string>',
address_province: '<string>',
address_postal_code: '<string>',
address_country: '<string>'
},
transacted_at: 123,
default_customer_type: '<string>',
invalid_tax_id_customer_fallback_type: '<string>',
metadata: {}
})
};
fetch('https://api.numeralhq.com/tax/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.numeralhq.com/tax/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([
'customer' => [
'address' => [
'address_line_1' => '<string>',
'address_line_2' => '<string>',
'address_city' => '<string>',
'address_province' => '<string>',
'address_postal_code' => '<string>',
'address_country' => '<string>',
'address_type' => '<string>'
],
'ip' => [
'value' => '<string>',
'resolution' => '<string>'
],
'id' => '<string>',
'type' => '<string>',
'tax_ids' => [
[
'type' => '<string>',
'value' => '<string>'
]
],
'skip_tax_id_validation' => true
],
'order_details' => [
'customer_currency_code' => '<string>',
'tax_included_in_amount' => true,
'automatic_tax' => '<string>',
'line_items' => [
[
'amount' => 123,
'quantity' => 123,
'product_category' => '<string>',
'reference_product_id' => '<string>',
'fallback_product_category' => '<string>',
'reference_line_item_id' => '<string>'
]
]
],
'origin_address' => [
'address_line_1' => '<string>',
'address_line_2' => '<string>',
'address_city' => '<string>',
'address_province' => '<string>',
'address_postal_code' => '<string>',
'address_country' => '<string>'
],
'transacted_at' => 123,
'default_customer_type' => '<string>',
'invalid_tax_id_customer_fallback_type' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json",
"X-API-Version: <x-api-version>"
],
]);
$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.numeralhq.com/tax/calculations"
payload := strings.NewReader("{\n \"customer\": {\n \"address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\",\n \"address_type\": \"<string>\"\n },\n \"ip\": {\n \"value\": \"<string>\",\n \"resolution\": \"<string>\"\n },\n \"id\": \"<string>\",\n \"type\": \"<string>\",\n \"tax_ids\": [\n {\n \"type\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"skip_tax_id_validation\": true\n },\n \"order_details\": {\n \"customer_currency_code\": \"<string>\",\n \"tax_included_in_amount\": true,\n \"automatic_tax\": \"<string>\",\n \"line_items\": [\n {\n \"amount\": 123,\n \"quantity\": 123,\n \"product_category\": \"<string>\",\n \"reference_product_id\": \"<string>\",\n \"fallback_product_category\": \"<string>\",\n \"reference_line_item_id\": \"<string>\"\n }\n ]\n },\n \"origin_address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\"\n },\n \"transacted_at\": 123,\n \"default_customer_type\": \"<string>\",\n \"invalid_tax_id_customer_fallback_type\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("X-API-Version", "<x-api-version>")
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.numeralhq.com/tax/calculations")
.header("Authorization", "<authorization>")
.header("X-API-Version", "<x-api-version>")
.header("Content-Type", "application/json")
.body("{\n \"customer\": {\n \"address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\",\n \"address_type\": \"<string>\"\n },\n \"ip\": {\n \"value\": \"<string>\",\n \"resolution\": \"<string>\"\n },\n \"id\": \"<string>\",\n \"type\": \"<string>\",\n \"tax_ids\": [\n {\n \"type\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"skip_tax_id_validation\": true\n },\n \"order_details\": {\n \"customer_currency_code\": \"<string>\",\n \"tax_included_in_amount\": true,\n \"automatic_tax\": \"<string>\",\n \"line_items\": [\n {\n \"amount\": 123,\n \"quantity\": 123,\n \"product_category\": \"<string>\",\n \"reference_product_id\": \"<string>\",\n \"fallback_product_category\": \"<string>\",\n \"reference_line_item_id\": \"<string>\"\n }\n ]\n },\n \"origin_address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\"\n },\n \"transacted_at\": 123,\n \"default_customer_type\": \"<string>\",\n \"invalid_tax_id_customer_fallback_type\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.numeralhq.com/tax/calculations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["X-API-Version"] = '<x-api-version>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customer\": {\n \"address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\",\n \"address_type\": \"<string>\"\n },\n \"ip\": {\n \"value\": \"<string>\",\n \"resolution\": \"<string>\"\n },\n \"id\": \"<string>\",\n \"type\": \"<string>\",\n \"tax_ids\": [\n {\n \"type\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"skip_tax_id_validation\": true\n },\n \"order_details\": {\n \"customer_currency_code\": \"<string>\",\n \"tax_included_in_amount\": true,\n \"automatic_tax\": \"<string>\",\n \"line_items\": [\n {\n \"amount\": 123,\n \"quantity\": 123,\n \"product_category\": \"<string>\",\n \"reference_product_id\": \"<string>\",\n \"fallback_product_category\": \"<string>\",\n \"reference_line_item_id\": \"<string>\"\n }\n ]\n },\n \"origin_address\": {\n \"address_line_1\": \"<string>\",\n \"address_line_2\": \"<string>\",\n \"address_city\": \"<string>\",\n \"address_province\": \"<string>\",\n \"address_postal_code\": \"<string>\",\n \"address_country\": \"<string>\"\n },\n \"transacted_at\": 123,\n \"default_customer_type\": \"<string>\",\n \"invalid_tax_id_customer_fallback_type\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"testmode": true,
"id": "calc_1793039299123",
"object": "tax.calculation",
"customer_currency_code": "USD",
"line_items": [
{
"line_item_id": "li_1793039299101",
"product": {
"reference_line_item_id": "widget",
"reference_product_id": "default-general-merchandise",
"reference_product_name": "Default GENERAL_MERCHANDISE Product",
"product_tax_code": "GENERAL_MERCHANDISE"
},
"tax_jurisdictions": [
{
"tax_rate": 0.0625,
"tax_due_decimal": 625,
"fee_amount": 0,
"rate_type": "GENERAL STATE SALES TAX",
"tax_authority_name": "Illinois",
"tax_authority_type": "",
"tax_type": "SALES",
"note": ""
},
{
"tax_rate": 0.03,
"tax_due_decimal": 300,
"fee_amount": 0,
"rate_type": "GENERAL COUNTY LOCAL SALES TAX",
"tax_authority_name": "Cook County",
"tax_authority_type": "",
"tax_type": "SALES",
"note": ""
},
{
"tax_rate": 0.0125,
"tax_due_decimal": 125,
"fee_amount": 0,
"rate_type": "GENERAL CITY LOCAL SALES TAX",
"tax_authority_name": "Chicago",
"tax_authority_type": "",
"tax_type": "SALES",
"note": ""
}
],
"tax_amount": 1050,
"amount_excluding_tax": 10000,
"amount_including_tax": 11050,
"quantity": 2
},
"... shipping line, tax_amount 105 on 1000 ..."
],
"total_tax_amount": 1155,
"tax_included_in_amount": false,
"total_amount_excluding_tax": 11000,
"total_amount_including_tax": 12155,
"expires_at": 1793125699,
"customer": {
"type": "CONSUMER"
},
"automatic_tax": "auto",
"address_resolution_status": "EXACT",
"address_used": {
"address_line_1": "233 S Wacker Dr",
"address_city": "Chicago",
"address_province": "IL",
"address_postal_code": "60606",
"address_country": "US"
},
"location_source": "address",
"resolution_precision": "STREET",
"effective_tax_rate": 0.105
}
{
"code": 400,
"type": "MISSING_FIELD",
"message": "Field 'order_details.automatic_tax' is required"
}
Quotes tax for a cart at checkout. The response is a Calculation object; use its
id to create a transaction once the customer pays.
New in 2026-11-01: every
tax_jurisdictions row has a note, and the response has an effective_tax_rate. The request is unchanged from 2026-03-01.Headers
string
required
Your API key, as
Bearer <key>.string
required
API version. Overrides your account’s default version for this request.
Body
object
required
Who is buying. At least one of
customer.address or customer.ip is required.object
object
IP address for location lookup when you don’t have a full address. See IP-based tax resolution.
string
ID of a customer you created in Numeral. Used for exemptions.
string
default:"CONSUMER"
CONSUMER or BUSINESS.object[]
boolean
default:"false"
Skip format and registry checks on
tax_ids.object
required
The cart.
string
required
ISO 4217 currency code. See supported currencies.
boolean
required
Whether line item amounts already include tax. Usually
false in North America.string
required
auto returns real rates where you’re registered. disabled always returns 0. Must be auto for US addresses.object[]
required
One entry per product. Each needs
reference_product_id or product_category.integer
required
Per-unit price in the currency’s smallest unit. Taxable base is
amount × quantity.integer
required
Quantity sold.
string
Tax category from the category list. Required if no
reference_product_id.string
Your product ID, as created in Numeral. Required if no
product_category.string
Used when
reference_product_id isn’t found in Numeral, instead of returning an error.string
Your line item ID, echoed back for record keeping.
object
integer
When the sale happened, Unix seconds. Rates and rules are evaluated as of this time. Defaults to now.
string
CONSUMER or BUSINESS. Used when customer.id isn’t found in Numeral, instead of returning an error.string
CONSUMER. Treat the customer as a consumer when tax ID validation fails, instead of returning a 400.object
String key-value pairs (values up to 255 characters), echoed back in the response.
Returns
A Calculation object. Errors are listed on the Calculations page.{
"testmode": true,
"id": "calc_1793039299123",
"object": "tax.calculation",
"customer_currency_code": "USD",
"line_items": [
{
"line_item_id": "li_1793039299101",
"product": {
"reference_line_item_id": "widget",
"reference_product_id": "default-general-merchandise",
"reference_product_name": "Default GENERAL_MERCHANDISE Product",
"product_tax_code": "GENERAL_MERCHANDISE"
},
"tax_jurisdictions": [
{
"tax_rate": 0.0625,
"tax_due_decimal": 625,
"fee_amount": 0,
"rate_type": "GENERAL STATE SALES TAX",
"tax_authority_name": "Illinois",
"tax_authority_type": "",
"tax_type": "SALES",
"note": ""
},
{
"tax_rate": 0.03,
"tax_due_decimal": 300,
"fee_amount": 0,
"rate_type": "GENERAL COUNTY LOCAL SALES TAX",
"tax_authority_name": "Cook County",
"tax_authority_type": "",
"tax_type": "SALES",
"note": ""
},
{
"tax_rate": 0.0125,
"tax_due_decimal": 125,
"fee_amount": 0,
"rate_type": "GENERAL CITY LOCAL SALES TAX",
"tax_authority_name": "Chicago",
"tax_authority_type": "",
"tax_type": "SALES",
"note": ""
}
],
"tax_amount": 1050,
"amount_excluding_tax": 10000,
"amount_including_tax": 11050,
"quantity": 2
},
"... shipping line, tax_amount 105 on 1000 ..."
],
"total_tax_amount": 1155,
"tax_included_in_amount": false,
"total_amount_excluding_tax": 11000,
"total_amount_including_tax": 12155,
"expires_at": 1793125699,
"customer": {
"type": "CONSUMER"
},
"automatic_tax": "auto",
"address_resolution_status": "EXACT",
"address_used": {
"address_line_1": "233 S Wacker Dr",
"address_city": "Chicago",
"address_province": "IL",
"address_postal_code": "60606",
"address_country": "US"
},
"location_source": "address",
"resolution_precision": "STREET",
"effective_tax_rate": 0.105
}
{
"code": 400,
"type": "MISSING_FIELD",
"message": "Field 'order_details.automatic_tax' is required"
}