Estimate Tax

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
    }
  ]
}
'

import requests

url = "https://api.trykintsugi.com/v1/tax/estimate"

payload = {
    "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
        }
    ]
}
headers = {
    "X-API-KEY": "<api-key>",
    "x-organization-id": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-API-KEY': '<api-key>',
    'x-organization-id': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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
      }
    ]
  })
};

fetch('https://api.trykintsugi.com/v1/tax/estimate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
}

{
  "detail": "The request is missing a valid x-api-key."
}

{
  "detail": "Entered an incorrect URL."
}

{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "date"
      ],
      "msg": "Field required",
      "input": {
        "external_id": "123456",
        "total_amount": 1000,
        "currency": "USD",
        "description": "Transaction for tax estimation",
        "simulate_active_registration": true,
        "addresses": [
          {
            "type": "SHIP_TO",
            "street_1": "789 Elm Street",
            "city": "Springfield",
            "state": "MO",
            "postal_code": "65806",
            "country": "US"
          }
        ],
        "transaction_items": [
          {
            "amount": 1000,
            "date": "2025-01-26T10:15:00Z",
            "external_product_id": "PROD001",
            "product_description": "Sample product description",
            "product_name": "Sample Product",
            "product_source": "OTHER",
            "quantity": 2,
            "tax_amount": "",
            "tax_items": []
          }
        ]
      }
    }
  ]
}

{
  "detail": "An unexpected server error occurred."
}

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 TransactionCreate a transaction.

⌘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
    }
  ]
}
'

import requests

url = "https://api.trykintsugi.com/v1/tax/estimate"

payload = {
    "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
        }
    ]
}
headers = {
    "X-API-KEY": "<api-key>",
    "x-organization-id": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-API-KEY': '<api-key>',
    'x-organization-id': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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
      }
    ]
  })
};

fetch('https://api.trykintsugi.com/v1/tax/estimate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
}

{
  "detail": "The request is missing a valid x-api-key."
}

{
  "detail": "Entered an incorrect URL."
}

{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "date"
      ],
      "msg": "Field required",
      "input": {
        "external_id": "123456",
        "total_amount": 1000,
        "currency": "USD",
        "description": "Transaction for tax estimation",
        "simulate_active_registration": true,
        "addresses": [
          {
            "type": "SHIP_TO",
            "street_1": "789 Elm Street",
            "city": "Springfield",
            "state": "MO",
            "postal_code": "65806",
            "country": "US"
          }
        ],
        "transaction_items": [
          {
            "amount": 1000,
            "date": "2025-01-26T10:15:00Z",
            "external_product_id": "PROD001",
            "product_description": "Sample product description",
            "product_name": "Sample Product",
            "product_source": "OTHER",
            "quantity": 2,
            "tax_amount": "",
            "tax_items": []
          }
        ]
      }
    }
  ]
}

{
  "detail": "An unexpected server error occurred."
}

Tax Estimation

Transactions

Address Validation

Customers

Registrations

Products

Nexus

Filings

Exemptions

Authorizations

Query Parameters

Body

Response