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.

x-organization-idstringRequired

Identifies the organization this request acts on.

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:BIGCOMMERCEBESTBUYBUNNYCHARGEBEESHOPIFYSTRIPEAMAZONTIKTOKCUSTOMUNKNOWNIMPORTZUORAAPIDECKQUICKBOOKSAPIAPPLE_APP_STOREGOOGLE_APP_STOREWALMARTPAYPALNETSUITEXEROMAXIORECURLYSALESFORCEETSYEBAYWIXSQUARESPACEWOOCOMMERCEMAGENTOBILLING_PLATFORMDEELRIPPLINGGUSTOFACEBOOKOTHERORDWAYINSTAGRAMPINTERESTWAYFAIRWISHPOSTARGETNEWEGGGROUPONGOOGLE_EXPRESSNOCNOCMERCADO_LIBREMODALYSTNORDSTROMFAIRESHOPWAREZOHOSAGE-INTACCTAIRWALLEXORBZENSKARMICROSOFT_DYNAMICS_365KICKSTARTERINTERNAL_ERP
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

itemsTransactionEstimateResponse[]Required
totalintegerRequired
pageintegerRequired
sizeintegerRequired
pagesintegerRequired
200

Successfully retrieved data

401

Authorization Error

404

Resource Not Found

422

Validation Error

500

Server Error

cURL
POST /v1/tax/estimate?simulate_nexus_met=true
-H "x-api-key: ***"
-H "x-organization-id: ***"
{
"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
}
]
}
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,
"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
}