Create a transaction
curl --request POST \
--url https://api.numeralhq.com/tax/transactions \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--header 'X-API-Version: <x-api-version>' \
--data '
{
"calculation_id": "<string>",
"reference_order_id": "<string>",
"transaction_processed_at": 123,
"metadata": {}
}
'import requests
url = "https://api.numeralhq.com/tax/transactions"
payload = {
"calculation_id": "<string>",
"reference_order_id": "<string>",
"transaction_processed_at": 123,
"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({
calculation_id: '<string>',
reference_order_id: '<string>',
transaction_processed_at: 123,
metadata: {}
})
};
fetch('https://api.numeralhq.com/tax/transactions', 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/transactions",
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([
'calculation_id' => '<string>',
'reference_order_id' => '<string>',
'transaction_processed_at' => 123,
'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/transactions"
payload := strings.NewReader("{\n \"calculation_id\": \"<string>\",\n \"reference_order_id\": \"<string>\",\n \"transaction_processed_at\": 123,\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/transactions")
.header("Authorization", "<authorization>")
.header("X-API-Version", "<x-api-version>")
.header("Content-Type", "application/json")
.body("{\n \"calculation_id\": \"<string>\",\n \"reference_order_id\": \"<string>\",\n \"transaction_processed_at\": 123,\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.numeralhq.com/tax/transactions")
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 \"calculation_id\": \"<string>\",\n \"reference_order_id\": \"<string>\",\n \"transaction_processed_at\": 123,\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"testmode": true,
"id": "tr_1793039302001",
"object": "tax.transaction",
"calculation_id": "calc_1793039299123",
"filing_currency_code": "USD",
"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,
"type": "b2c"
},
"... shipping line ..."
],
"reference_order_id": "order-1001",
"transaction_processed_at": 1793039302
}
{
"code": 404,
"type": "CALCULATION_NOT_FOUND",
"message": "Unable to find calculation with ID: calc_does_not_exist in test environment."
}
Create a transaction
Record a completed sale from a calculation. Returns a Transaction object.
POST
/
tax
/
transactions
Create a transaction
curl --request POST \
--url https://api.numeralhq.com/tax/transactions \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--header 'X-API-Version: <x-api-version>' \
--data '
{
"calculation_id": "<string>",
"reference_order_id": "<string>",
"transaction_processed_at": 123,
"metadata": {}
}
'import requests
url = "https://api.numeralhq.com/tax/transactions"
payload = {
"calculation_id": "<string>",
"reference_order_id": "<string>",
"transaction_processed_at": 123,
"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({
calculation_id: '<string>',
reference_order_id: '<string>',
transaction_processed_at: 123,
metadata: {}
})
};
fetch('https://api.numeralhq.com/tax/transactions', 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/transactions",
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([
'calculation_id' => '<string>',
'reference_order_id' => '<string>',
'transaction_processed_at' => 123,
'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/transactions"
payload := strings.NewReader("{\n \"calculation_id\": \"<string>\",\n \"reference_order_id\": \"<string>\",\n \"transaction_processed_at\": 123,\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/transactions")
.header("Authorization", "<authorization>")
.header("X-API-Version", "<x-api-version>")
.header("Content-Type", "application/json")
.body("{\n \"calculation_id\": \"<string>\",\n \"reference_order_id\": \"<string>\",\n \"transaction_processed_at\": 123,\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.numeralhq.com/tax/transactions")
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 \"calculation_id\": \"<string>\",\n \"reference_order_id\": \"<string>\",\n \"transaction_processed_at\": 123,\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"testmode": true,
"id": "tr_1793039302001",
"object": "tax.transaction",
"calculation_id": "calc_1793039299123",
"filing_currency_code": "USD",
"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,
"type": "b2c"
},
"... shipping line ..."
],
"reference_order_id": "order-1001",
"transaction_processed_at": 1793039302
}
{
"code": 404,
"type": "CALCULATION_NOT_FOUND",
"message": "Unable to find calculation with ID: calc_does_not_exist in test environment."
}
Records a sale from a calculation. Create it after the customer pays and before the calculation expires (24 hours). The response is a Transaction object.
New in 2026-11-01: every
tax_jurisdictions row has a note. The transaction comes back in the shape of the X-API-Version you send now, whatever version the calculation was made on.Headers
string
required
Your API key, as
Bearer <key>.string
required
API version. Overrides your account’s default version for this request.
Body
string
required
The
id of the calculation to record.string
required
Your order ID. Must be unique across your transactions.
integer
When the sale was made, Unix seconds. Defaults to now.
object
String key-value pairs, echoed back in the response.
Returns
A Transaction object. Errors are listed on the Transactions page.{
"testmode": true,
"id": "tr_1793039302001",
"object": "tax.transaction",
"calculation_id": "calc_1793039299123",
"filing_currency_code": "USD",
"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,
"type": "b2c"
},
"... shipping line ..."
],
"reference_order_id": "order-1001",
"transaction_processed_at": 1793039302
}
{
"code": 404,
"type": "CALCULATION_NOT_FOUND",
"message": "Unable to find calculation with ID: calc_does_not_exist in test environment."
}