# Calculate Tax for a Transaction (2026-07-21)

> Interactive walkthrough to calculate tax using the Kintsugi API

Source: https://docs.trykintsugi.com/docs/2026-07-21/recipes/calculate-tax

## Overview

The Tax Estimation API calculates the tax due on a transaction before you record it, using your registrations, product taxability, customer exemptions and the addresses on the transaction. Nothing is stored and the estimate cannot be retrieved afterwards, so send the same request again whenever you need to price it again. That makes it a natural fit for checkout flows and for testing tax calculations.

## When to Use

Shopping cart pages: Calculate tax when customers review their order

Checkout flows: After address entry but before payment processing

Subscription billing: Calculate tax for recurring charges

Quote generation: Provide tax estimates to customers

## Authentication

This endpoint takes one credential header:

Api-Key: Your API key

The estimate is computed for exactly one organization. If your key can reach more than one organization, send an Organization-Id, Connection-Id or Entity-Id header to choose it.

Api-Version: 2026-07-21 is optional. A request without it runs against 2026-07-21.

## Try It Out

API Lab Simulated

Run all Reset Share Copy cURL Postman

Runs in a simulated sandbox. Responses are generated from the API schema so you can explore each call safely; they never reach the live API, so the values are illustrative.

1 Estimate tax on a transaction

POST /tax-estimations

Edit the addresses or line items to shape the request. Because this lab is simulated, the returned figures are illustrative rather than live jurisdiction rates.

{

"externalId": "txn-1001",

"date": "2026-07-28T12:00:00Z",

"currency": "USD",

"addresses": [

{

"type": "BILL_TO",

"street1": "123 Main St",

"city": "Austin",

"state": "TX",

"postalCode": "78701",

"country": "US"

}

],

"transactionItems": [

{

"externalId": "item-1",

"externalProductId": "sku-1001",

"productName": "Widget",

"quantity": "2",

"amount": "100.00"

}

]

}

{
"externalId": "txn-1001",
"date": "2026-07-28T12:00:00Z",
"currency": "USD",
"addresses": [
{
"type": "BILL_TO",
"street1": "123 Main St",
"city": "Austin",
"state": "TX",
"postalCode": "78701",
"country": "US"
}
],
"transactionItems": [
{
"externalId": "item-1",
"externalProductId": "sku-1001",
"productName": "Widget",
"quantity": "2",
"amount": "100.00"
}
]
}

Run

## Required Fields

externalId: Your identifier for the transaction, echoed on the response

date: When the transaction takes place; the rates in force on this date are applied

currency: ISO 4217 currency of every amount on the request (for example, USD)

addresses: The addresses on the transaction, each with a type. Supply at least a SHIP_TO or BILL_TO; tax is sourced to the SHIP_TO address when one is supplied, otherwise BILL_TO

transactionItems: At least one line, each with an externalId and an amount

Each line names either an externalProductId you have already created or a productCategory and productSubcategory pair, not both.

Tax is only due where an active registration covers the destination. When hasActiveRegistration is false, every amount comes back as zero. Set simulateActiveRegistration to true to see what the transaction would be taxed at if you were registered there.

## Common Use Cases

Basic Tax Calculation

Calculate tax for a simple transaction with one address:

{
"externalId": "txn-1001",
"date": "2026-07-28T12:00:00Z",
"currency": "USD",
"addresses": [
{
"type": "BILL_TO",
"street1": "123 Main St",
"city": "Austin",
"state": "TX",
"postalCode": "78701",
"country": "US"
}
],
"transactionItems": [
{
"externalId": "item-1",
"externalProductId": "sku-1001",
"productName": "Widget",
"quantity": "2",
"amount": "100.00"
}
]
}

With Customer Information

Include the buyer so their exemptions apply. When the customer's externalId matches a customer Kintsugi already holds, that customer's exemptions and tax registrations are applied to the estimate:

{
"externalId": "txn-1001",
"date": "2026-07-28T12:00:00Z",
"currency": "USD",
"customer": {
"externalId": "cust-1001",
"name": "Acme Corp",
"email": "jane.doe@example.com"
},
"addresses": [
{
"type": "BILL_TO",
"street1": "123 Main St",
"city": "Austin",
"state": "TX",
"postalCode": "78701",
"country": "US"
}
],
"transactionItems": [
{
"externalId": "item-1",
"externalProductId": "sku-1001",
"productName": "Widget",
"quantity": "2",
"amount": "100.00"
}
]
}

## Response Fields

totalTaxAmount: Total tax due on the transaction

taxableAmount: Total across all lines that tax was charged on

taxRate: Combined effective rate across the transaction, as a fraction of the taxable amount

hasActiveRegistration: Whether an active registration covers the destination jurisdiction; when false, no tax is due and every amount is zero

## Next Steps

Create a Transaction - Record the transaction after payment

Sales Tax Calculations Guide - Learn more about tax calculation

Getting Started - Set up your integration

## Related Resources

Tax Estimation API Reference

Sales Tax for Developers

Support

---

Index of every page: https://docs.trykintsugi.com/llms.txt