POST

tax

estimate

Estimate Tax

curl --request POST \
  --url https://api.trykintsugi.com/v1/tax/estimate \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'x-organization-id: <api-key>' \
  --data '
{
  "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
    }
  ]
}
'

{
  "date": "2025-01-25T13:45:00Z",
  "external_id": "123456",
  "currency": "USD",
  "description": "Test transaction for tax calculation",
  "source": "OTHER",
  "marketplace": false,
  "addresses": [
    {
      "type": "SHIP_TO",
      "street_1": "456 Elm Street",
      "street_2": "Suite 202",
      "city": "Springfield",
      "county": "Greene",
      "state": "MO",
      "postal_code": "65806",
      "country": "US",
      "status": "VERIFIED"
    }
  ],
  "transaction_items": [
    {
      "external_id": "ITEM123",
      "date": "2025-01-25T14:00:00Z",
      "description": "A sample product",
      "external_product_id": "PROD001",
      "product_name": "Sample Product",
      "product_description": "This is a sample product for testing",
      "product_source": "OTHER",
      "product_subcategory": "GENERAL_CLOTHING",
      "product_category": "PHYSICAL",
      "quantity": "2",
      "amount": "250.00",
      "exempt": false,
      "tax_amount": "20.00",
      "taxable_amount": "500.00",
      "tax_rate": "0.08",
      "tax_items": [
        {
          "rate": "0.05",
          "name": "State Tax",
          "amount": "12.50",
          "exempt": false
        },
        {
          "rate": "0.03",
          "name": "County Tax",
          "amount": "7.50",
          "exempt": false
        }
      ]
    }
  ],
  "total_tax_amount_calculated": "20.00",
  "taxable_amount": "500.00",
  "tax_rate_calculated": "0.08",
  "nexus_met": true,
  "has_active_registration": true
}

Calculate Tax for a Transaction

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

Use the interactive playground below to test the tax estimation endpoint. The playground will automatically include the required authentication headers.

The playground prefills example values from the API schema. Modify the request body to test different scenarios like different addresses, product types, or customer exemptions.

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

The API returns detailed tax information:

total_tax_amount_calculated: Total tax amount for the transaction
taxable_amount: Amount subject to tax
tax_rate_calculated: Overall tax rate
nexus_met: Whether your organization has nexus in the destination jurisdiction
has_active_registration: Whether you have an active registration
transaction_items: Array with tax details for each item

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

Authorizations

X-API-KEY

string

header

required

x-organization-id

string

header

required

Query Parameters

simulate_nexus_met

boolean

deprecated

Deprecated: Use simulate_active_registration in the request body instead.

Body

application/json

Public request model for tax estimation API documentation. This model excludes internal fields like enriched_fields and total_amount that should not be exposed in API docs.

date

string<date-time>

required

The date of the transaction in ISO 8601 format (e.g., 2025-01-25T12:00:00Z).

external_id

string

required

Unique identifier of this transaction in the source system.

currency

enum<string>

required

The currency in which the transaction is conducted (e.g., USD, EUR).

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

BWP,

BYN,

BZD,

CAD,

CDF,

CHF,

CLP,

CNY,

COP,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GGP,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

IMP,

INR,

IQD,

IRR,

ISK,

JEP,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRU,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SLL,

SOS,

SPL,

SRD,

STN,

SVC,

SYP,

SZL,

THB,

TJS,

TMT,

TND,

TOP,

TRY,

TTD,

TVD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VEF,

VND,

VUV,

WST,

XAF,

XCD,

XDR,

XOF,

XPF,

YER,

ZAR,

ZMW,

ZWD

transaction_items

TransactionItemEstimateBase · object[]

required

List of items involved in the transaction.

Show child attributes

addresses

The address information for this transaction. · object[]

required

List of addresses related to the transaction. At least one BILL_TO or SHIP_TO address must be provided. The address will be validated during estimation, and the transaction may be rejected if the address does not pass validation. The SHIP_TO will be preferred to use for determining tax liability.

Show child attributes

description

string

An optional description of the transaction.

source

enum<string>

deprecated

While currently not used, it may be used in the future to determine taxability. The source of the transaction (e.g., OTHER).

Available options:

BIGCOMMERCE,

BESTBUY,

BUNNY,

CHARGEBEE,

SHOPIFY,

STRIPE,

AMAZON,

TIKTOK,

CUSTOM,

UNKNOWN,

IMPORT,

ZUORA,

APIDECK,

QUICKBOOKS,

API,

APPLE_APP_STORE,

GOOGLE_APP_STORE,

WALMART,

PAYPAL,

NETSUITE,

XERO,

MAXIO,

RECURLY,

SALESFORCE,

ETSY,

EBAY,

WIX,

SQUARESPACE,

WOOCOMMERCE,

MAGENTO,

BILLING_PLATFORM,

DEEL,

RIPPLING,

GUSTO,

FACEBOOK,

OTHER,

ORDWAY,

INSTAGRAM,

PINTEREST,

WAYFAIR,

WISH,

POS,

TARGET,

NEWEGG,

GROUPON,

GOOGLE_EXPRESS,

NOCNOC,

MERCADO_LIBRE,

MODALYST,

NORDSTROM,

FAIRE,

SHOPWARE,

ZOHO,

SAGE-INTACCT,

AIRWALLEX,

ORB,

ZENSKAR,

MICROSOFT_DYNAMICS_365,

KICKSTARTER,

INTERNAL_ERP

marketplace

boolean

default:false

Indicates if the transaction involves a marketplace.

customer

The customer who placed the transaction. · object

Details about the customer. If the customer is not found, it will be ignored.

Show child attributes

Response

Successfully retrieved data

items

TransactionEstimateResponse · object[]

required

Show child attributes

total

integer

required

Required range: x >= 0

page

integer

required

Required range: x >= 1

size

integer

required

Required range: x >= 1

pages

integer

required

Required range: x >= 0

Create a ProductInteractive playground to create products using the Kintsugi API

⌘I

Estimate Tax

curl --request POST \
  --url https://api.trykintsugi.com/v1/tax/estimate \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'x-organization-id: <api-key>' \
  --data '
{
  "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
    }
  ]
}
'

{
  "date": "2025-01-25T13:45:00Z",
  "external_id": "123456",
  "currency": "USD",
  "description": "Test transaction for tax calculation",
  "source": "OTHER",
  "marketplace": false,
  "addresses": [
    {
      "type": "SHIP_TO",
      "street_1": "456 Elm Street",
      "street_2": "Suite 202",
      "city": "Springfield",
      "county": "Greene",
      "state": "MO",
      "postal_code": "65806",
      "country": "US",
      "status": "VERIFIED"
    }
  ],
  "transaction_items": [
    {
      "external_id": "ITEM123",
      "date": "2025-01-25T14:00:00Z",
      "description": "A sample product",
      "external_product_id": "PROD001",
      "product_name": "Sample Product",
      "product_description": "This is a sample product for testing",
      "product_source": "OTHER",
      "product_subcategory": "GENERAL_CLOTHING",
      "product_category": "PHYSICAL",
      "quantity": "2",
      "amount": "250.00",
      "exempt": false,
      "tax_amount": "20.00",
      "taxable_amount": "500.00",
      "tax_rate": "0.08",
      "tax_items": [
        {
          "rate": "0.05",
          "name": "State Tax",
          "amount": "12.50",
          "exempt": false
        },
        {
          "rate": "0.03",
          "name": "County Tax",
          "amount": "7.50",
          "exempt": false
        }
      ]
    }
  ],
  "total_tax_amount_calculated": "20.00",
  "taxable_amount": "500.00",
  "tax_rate_calculated": "0.08",
  "nexus_met": true,
  "has_active_registration": true
}

​Calculate Tax for a Transaction

​Overview

​When to Use

​Authentication

​Try It Out

​Common Use Cases

​Basic Tax Calculation

​With Customer Information

​Response Fields

​Next Steps

​Related Resources

Authorizations

Query Parameters

Body

Response

Calculate Tax for a Transaction

Overview

When to Use

Authentication

Try It Out

Common Use Cases

Basic Tax Calculation

With Customer Information

Response Fields

Next Steps

Related Resources