KintsugiKintsugi
API Lab

Calculate Tax for a Transaction

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 LabSimulated
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.
1Estimate 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.

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

Related Resources