KintsugiKintsugi
API reference / Estimate tax

Estimate tax

POST/v1/tax/estimate

The Estimate Tax API calculates the estimated tax for a specific transaction based on the provided details, including organization nexus, transaction details, customer details, and addresses. Optionally simulates nexus being met for tax calculation purposes. The simulate_nexus_met parameter is deprecated and will be removed in future releases.

Authorization

x-api-keystringRequired

Your secret API key. Include it with every request.

Query

This endpoint reads its data from the request body (see Body). It also accepts the optional query parameters below; append any combination to the endpoint as a query string.

/v1/tax/estimate?simulate_nexus_met=<simulate_nexus_met>
simulate_nexus_metboolean

Deprecated: Use simulate_active_registration in the request body instead.

Body

datestringRequired

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

external_idstringRequired

Unique identifier of this transaction in the source system.

currencyCurrencyEnumRequired

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

Available options:AEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBZDCADCDFCHFCLPCNYCOPCRCCUCCUPCVECZKDJFDKKDOPDZDEGPERNETBEURFJDFKPGBPGELGGPGHSGIPGMDGNFGTQGYDHKDHNLHRKHTGHUFIDRILSIMPINRIQDIRRISKJEPJMDJODJPYKESKGSKHRKMFKPWKRWKWDKYDKZTLAKLBPLKRLRDLSLLYDMADMDLMGAMKDMMKMNTMOPMRUMURMVRMWKMXNMYRMZNNADNGNNIONOKNPRNZDOMRPABPENPGKPHPPKRPLNPYGQARRONRSDRUBRWFSARSBDSCRSDGSEKSGDSHPSLLSOSSPLSRDSTNSVCSYPSZLTHBTJSTMTTNDTOPTRYTTDTVDTWDTZSUAHUGXUSDUYUUZSVEFVNDVUVWSTXAFXCDXDRXOFXPFYERZARZMWZWD
descriptionstring

An optional description of the transaction.

sourceSourceEnum

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

Available options:BIGCOMMERCEBESTBUYBUNNYCHARGEBEESHOPIFYSHOPLINEECWIDSTRIPEAMAZONTIKTOKCUSTOMUNKNOWNIMPORTZUORAAPIDECKQUICKBOOKSAPIAPPLE_APP_STOREGOOGLE_APP_STOREWALMARTPAYPALNETSUITEXEROMAXIORECURLYSALESFORCEETSYEBAYWIXSQUARESPACEWOOCOMMERCEMAGENTOMACYSBILLING_PLATFORMDEELRIPPLINGGUSTOFACEBOOKOTHERORDWAYINSTAGRAMPINTERESTWAYFAIRWISHPOSTARGETNEWEGGGROUPONGOOGLE_EXPRESSNOCNOCMERCADO_LIBREMODALYSTNORDSTROMFAIRESHOPWAREZOHOSAGE-INTACCTAIRWALLEXORBZENSKARMICROSOFT_DYNAMICS_365KICKSTARTERINTERNAL_ERPRILLETCAMPFIREKILL_BILLPROVISIONVERTEX_O_SERIESCHECKOUTCHAMPDUALENTRYODOOBILL_COMINTUIT_ENTERPRISE_SUITEACUMATICAPLENTYONE
marketplaceboolean

Indicates if the transaction involves a marketplace.

transaction_itemsTransactionItemEstimateBase[]Required

List of items involved in the transaction.

customerCustomerBasePublic

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

addressesobject[]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.

Response

datestringRequired

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

external_idstringRequired

Unique identifier of this transaction in the source system.

currencyCurrencyEnumRequired

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

Available options:AEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBZDCADCDFCHFCLPCNYCOPCRCCUCCUPCVECZKDJFDKKDOPDZDEGPERNETBEURFJDFKPGBPGELGGPGHSGIPGMDGNFGTQGYDHKDHNLHRKHTGHUFIDRILSIMPINRIQDIRRISKJEPJMDJODJPYKESKGSKHRKMFKPWKRWKWDKYDKZTLAKLBPLKRLRDLSLLYDMADMDLMGAMKDMMKMNTMOPMRUMURMVRMWKMXNMYRMZNNADNGNNIONOKNPRNZDOMRPABPENPGKPHPPKRPLNPYGQARRONRSDRUBRWFSARSBDSCRSDGSEKSGDSHPSLLSOSSPLSRDSTNSVCSYPSZLTHBTJSTMTTNDTOPTRYTTDTVDTWDTZSUAHUGXUSDUYUUZSVEFVNDVUVWSTXAFXCDXDRXOFXPFYERZARZMWZWD
descriptionstring

An optional description of the transaction.

sourceSourceEnum

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

Available options:BIGCOMMERCEBESTBUYBUNNYCHARGEBEESHOPIFYSHOPLINEECWIDSTRIPEAMAZONTIKTOKCUSTOMUNKNOWNIMPORTZUORAAPIDECKQUICKBOOKSAPIAPPLE_APP_STOREGOOGLE_APP_STOREWALMARTPAYPALNETSUITEXEROMAXIORECURLYSALESFORCEETSYEBAYWIXSQUARESPACEWOOCOMMERCEMAGENTOMACYSBILLING_PLATFORMDEELRIPPLINGGUSTOFACEBOOKOTHERORDWAYINSTAGRAMPINTERESTWAYFAIRWISHPOSTARGETNEWEGGGROUPONGOOGLE_EXPRESSNOCNOCMERCADO_LIBREMODALYSTNORDSTROMFAIRESHOPWAREZOHOSAGE-INTACCTAIRWALLEXORBZENSKARMICROSOFT_DYNAMICS_365KICKSTARTERINTERNAL_ERPRILLETCAMPFIREKILL_BILLPROVISIONVERTEX_O_SERIESCHECKOUTCHAMPDUALENTRYODOOBILL_COMINTUIT_ENTERPRISE_SUITEACUMATICAPLENTYONE
marketplaceboolean

Indicates if the transaction involves a marketplace.

transaction_itemsTransactionItemEstimateResponse[]Required
customerCustomerBase

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

addressesobject[]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. Optional per-address status is deprecated, accepted for backward compatibility, and ignored; estimation always validates from structured address fields.

total_tax_amount_calculatedstring

The total amount of tax determined for the transaction.

taxable_amountstring

The taxable amount for the transaction.

tax_rate_calculatedstring

The calculated tax rate for the transaction.

nexus_metboolean

Indicates if nexus was met for the transaction.Deprecated: Use has_active_registration instead.

has_active_registrationboolean

Indicates if there is an active registration for the transaction.

200

Successfully retrieved data

400

Invalid tax-estimation input

401

Authorization Error

404

Resource Not Found

422

Validation Error

500

Server Error

503

Address validation temporarily unavailable

cURL
POST /v1/tax/estimate?simulate_nexus_met=true
-H "x-api-key: ***"
{
"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
}
]
}
Example request
https://api.trykintsugi.com/v1/tax/estimate?simulate_nexus_met=true
Response
{
"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,
"is_tax_inclusive": 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
}