KintsugiKintsugi
API Lab

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

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

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

Related Resources