Tax Estimation
Transactions
Address Validation
Customers
Registrations
Products
Nexus
Filings
Organizations
Organization Management
- POSTCreate Api Key
- GETGet Api Keys
- DELDelete Api Key
- PUTCreate Update Business Address
- PUTCreate Update Business Contact
- PUTCreate Update Business Details
- PUTCreate Update Business Information
- PUTCreate Update Business Owners
- GETGet Bank Details
- PUTCreate Update Bank Details
- GETGet Organization Details
- GETGet Organization Details Auto File Auto Register
- PUTUpdate Organization Details Auto File Auto Register
- POSTUpdate Organization Settings
- GETGet Organization Settings
Estimate Tax
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.
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
}
]
}
'{
"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
}Query Parameters
Deprecated: Use simulate_active_registration in the request body instead.
Body
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.
The date of the transaction in ISO 8601 format (e.g., 2025-01-25T12:00:00Z).
Unique identifier of this transaction in the source system.
The currency in which the transaction is conducted (e.g., USD, EUR).
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 List of items involved in the transaction.
Show child attributes
Show child attributes
The date of the transaction item.
The total amount of the item.
A unique identifier for the transaction item.
A description of the item.
External product identifier. If not found and product_subcategory and product_category are not provided, an error occurs.
Name of the product. Used if creating a new product.
Description of the product. Used if creating a new product.
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 Subcategory of the product. Required if product_category is used in place of external_product_id.
Category of the product. Required if product_subcategory is used in place of external_product_id.
Defaults to 1.0. The quantity of the item.
Defaults to false. Indicates whether the item is exempt from tax.
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
Show child attributes
Type of the address. Must be either SHIP_TO or BILL_TO.
SHIP_TO, BILL_TO State or province of the address.
Postal code of the address.
Country of the address.
Phone number associated with the customer.
Primary street address of the customer.
Additional street address details, such as an apartment or suite number.
City where the customer resides.
County or district of the customer.
Complete address string of the customer, which can be used as an alternative to individual fields.
Status of the address. Deprecated and ignored.
An optional description of the transaction.
While currently not used, it may be used in the future to determine taxability. The source of the transaction (e.g., OTHER).
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 Indicates if the transaction involves a marketplace.
Details about the customer. If the customer is not found, it will be ignored.
Show child attributes
Show child attributes
Phone number associated with the address.
Primary street address.
Additional street address details, such as an apartment or suite number.
City where the customer resides.
County or district of the customer.
State or province of the customer.
ZIP or Postal code of the customer.
Country code in ISO 3166-1 alpha-2 format
AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, CI, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, XK, ZZ_EU Complete address string of the customer, which can be used as an alternative to individual fields.
Name of the customer.
A unique identifier for the customer.
Status of the customer (e.g., ACTIVE, INACTIVE).
ACTIVE, ARCHIVED Email address of the customer.
Address status of the customer. Defaults to UNVERIFIED.
UNVERIFIED, INVALID, PARTIALLY_VERIFIED, VERIFIED, UNVERIFIABLE, BLANK Source of the customer information (e.g., BIGCOMMERCE, STRIPE, etc.).
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 Unique identifier of the connection related to the customer.
Response
Successfully retrieved data
Show child attributes
Show child attributes
The date of the transaction in ISO 8601 format (e.g., 2025-01-25T12:00:00Z).
Unique identifier of this transaction in the source system.
The currency in which the transaction is conducted (e.g., USD, EUR).
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 Show child attributes
Show child attributes
The date of the transaction item.
The total amount of the item.
A unique identifier for the transaction item.
A description of the item.
External product identifier. If not found and product_subcategory and product_category are not provided, an error occurs.
Name of the product. Used if creating a new product.
Description of the product. Used if creating a new product.
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 Subcategory of the product. Required if product_category is used in place of external_product_id.
Category of the product. Required if product_subcategory is used in place of external_product_id.
Defaults to 1.0. The quantity of the item.
Indicates whether the transaction item is exempt from tax.
The total tax amount for the transaction item.
The taxable amount for the transaction item.
The tax rate applied to the transaction item.
Reason for exemption, if applicable.
PRODUCT, TRANSACTION, CUSTOMER, REGION, REVERSE_CHARGE, ZERO_RATE_TAX, HIGH_VALUE_PHYSICAL_GOODS, EXPORT, ZERO_VALUE_ITEM, NO_RULE_FOUND, IMPORTED List of tax items applied to the transaction item.
Show child attributes
Show child attributes
We use this to understand the response from get_tax_items
NO_RULE_FOUND, RULE_FOUND_TAXABLE, RULE_FOUND_NOT_TAXABLE, PRODUCT_EXEMPT, FROM_IMPORT 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. Deprecated: Use of address.status in estimate api is ignored and will be removed in the future status will be considered UNVERIFIED by default and always validated
Show child attributes
Show child attributes
Type of the address. Must be either SHIP_TO or BILL_TO.
SHIP_TO, BILL_TO State or province of the address.
Postal code of the address.
Country of the address.
Phone number associated with the customer.
Primary street address of the customer.
Additional street address details, such as an apartment or suite number.
City where the customer resides.
County or district of the customer.
Complete address string of the customer, which can be used as an alternative to individual fields.
Status of the address. Deprecated and ignored.
Additional enriched fields related to the address.
An optional description of the transaction.
While currently not used, it may be used in the future to determine taxability. The source of the transaction (e.g., OTHER).
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 Indicates if the transaction involves a marketplace.
Details about the customer. If the customer is not found, it will be ignored.
Show child attributes
Show child attributes
Phone number associated with the address.
Primary street address.
Additional street address details, such as an apartment or suite number.
City where the customer resides.
County or district of the customer.
State or province of the customer.
ZIP or Postal code of the customer.
Country code in ISO 3166-1 alpha-2 format
AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, CI, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, XK, ZZ_EU Complete address string of the customer, which can be used as an alternative to individual fields.
Name of the customer.
A unique identifier for the customer.
Status of the customer (e.g., ACTIVE, INACTIVE).
ACTIVE, ARCHIVED Email address of the customer.
Address status of the customer. Defaults to UNVERIFIED.
UNVERIFIED, INVALID, PARTIALLY_VERIFIED, VERIFIED, UNVERIFIABLE, BLANK Source of the customer information (e.g., BIGCOMMERCE, STRIPE, etc.).
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 Unique identifier of the connection related to the customer.
The total amount of tax determined for the transaction.
The taxable amount for the transaction.
The calculated tax rate for the transaction.
Indicates if nexus was met for the transaction.Deprecated: Use has_active_registration instead.
Indicates if there is an active registration for the transaction.
x >= 0x >= 1x >= 1x >= 0curl --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
}
]
}
'{
"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
}