# Calculate Tax for a Transaction

> Interactive walkthrough to calculate tax using the Kintsugi API

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

## Overview

The Tax Estimation API calculates the estimated tax for a transaction based on your organization's nexus status, product taxability, customer exemptions, and shipping addresses. This endpoint is idempotent and doesn't create permanent transaction records, making it perfect for testing tax calculations during checkout flows.

## 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 requires two headers:

x-api-key: Your API key

x-organization-id: Your organization ID

Both headers are required for authentication. You can find your API key and organization ID in your Kintsugi dashboard.

## 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

POST /v1/tax/estimate

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

{

"date": "2025-01-23T13:01:29.949Z",

"external_id": "txn_12345",

"currency": "USD",

"addresses": [

{

"type": "SHIP_TO",

"street_1": "789 Pine St",

"city": "Austin",

"state": "TX",

"postal_code": "78701",

"country": "US"

}

],

"transaction_items": [

{

"external_id": "item_A",

"date": "2024-10-28T10:00:00Z",

"external_product_id": "prod_abc",

"quantity": 2,

"amount": 100

},

{

"external_id": "item_B",

"date": "2024-10-28T10:00:00Z",

"external_product_id": "prod_xyz",

"quantity": 1,

"amount": 75.5,

"is_tax_inclusive": false

}

]

}

{
"date": "2025-01-23T13:01:29.949Z",
"external_id": "txn_12345",
"currency": "USD",
"addresses": [
{
"type": "SHIP_TO",
"street_1": "789 Pine St",
"city": "Austin",
"state": "TX",
"postal_code": "78701",
"country": "US"
}
],
"transaction_items": [
{
"external_id": "item_A",
"date": "2024-10-28T10:00:00Z",
"external_product_id": "prod_abc",
"quantity": 2,
"amount": 100
},
{
"external_id": "item_B",
"date": "2024-10-28T10:00:00Z",
"external_product_id": "prod_xyz",
"quantity": 1,
"amount": 75.5,
"is_tax_inclusive": false
}
]
}

Run

## Required Fields

date: Transaction date in ISO 8601 format

external_id: Your unique identifier for the transaction

currency: Three-letter currency code (for example, USD)

addresses: One or more addresses; the ship-to address determines the tax jurisdiction

transaction_items: The line items to price, each with an amount

## Common Use Cases

Basic Tax Calculation

Calculate tax for a simple transaction with a shipping address:

{
"date": "2024-01-15T10:00:00Z",
"external_id": "order-123",
"currency": "USD",
"source": "API",
"transaction_items": [
{
"external_id": "item-1",
"external_product_id": "product-123",
"product_name": "Example Product",
"quantity": "1.0",
"amount": 100.00
}
],
"addresses": [
{
"type": "SHIP_TO",
"street_1": "123 Main St",
"city": "Seattle",
"state": "WA",
"postal_code": "98101",
"country": "US"
}
]
}

With Customer Information

Include customer details to check for exemptions:

{
"date": "2024-01-15T10:00:00Z",
"external_id": "order-123",
"currency": "USD",
"source": "API",
"customer": {
"name": "John Doe",
"email": "john@example.com",
"street_1": "123 Main St",
"city": "Seattle",
"state": "WA",
"postal_code": "98101",
"country": "US"
},
"transaction_items": [
{
"external_id": "item-1",
"external_product_id": "product-123",
"product_name": "Example Product",
"quantity": "1.0",
"amount": 100.00
}
],
"addresses": [
{
"type": "SHIP_TO",
"street_1": "123 Main St",
"city": "Seattle",
"state": "WA",
"postal_code": "98101",
"country": "US"
}
]
}

## Response Fields

total_tax_amount_calculated: Total tax calculated for the transaction

taxable_amount: Amount subject to tax

tax_rate_calculated: Overall tax rate applied

nexus_met: Whether your organization has nexus in the destination jurisdiction

has_active_registration: Whether you have an active registration there

## 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