KintsugiKintsugi
API reference / Create transaction

Create transaction

POST/v1/transactions

Create a transaction. Set marketplace: true for reseller or marketplace orders where tax was remitted externally; gross sales still count toward nexus, but tax liability is excluded.

Authorization

x-api-keystringRequired

Your secret API key. Include it with every request.

Body

requires_exemptionExemptionRequired

Indicates if transaction requires tax exemption.

organization_idstringRequired

Unique identifier of the organization. This field is deprecated, and should no longer be used. The value is populated through the 'x-organization-id' header.

external_idstringRequired

External identifier of the transaction.

datestringRequired

Transaction date and time

shop_datestring

Transaction date in the shop's local timezone

shop_date_tzstring

Timezone of the shop

descriptionstring

Description of the transaction.

refund_statusTransactionRefundStatus

Status of refund, if applicable

Available options:FULLY_REFUNDEDPARTIALLY_REFUNDED
total_amountnumber | string

Total amount of the transaction.

customer_idstring

Unique identifier of the customer.

marketplaceboolean

Indicates if transaction is marketplace-based.

exemptTransactionExemptStatusEnum

Exemption status (e.g., NOT_EXEMPT)

Available options:NOT_EXEMPTPARTIALLY_EXEMPTFULLY_EXEMPTZERO_RATE_NOT_EXEMPT
exemptionsExemption[]

List of exemptions applied (if any).

related_tostring

Related transaction identifier.

secondary_external_idstring

Secondary External Identifier.

secondary_sourcestring

Secondary source information

external_friendly_idstring

Friendly identifier of the original item.

total_tax_amount_importednumber | string

Imported tax amount.

tax_rate_importednumber | string

Imported tax rate.

total_tax_amount_calculatednumber | string

Calculated tax amount.

tax_rate_calculatednumber | string

Calculated tax rate.

total_tax_liability_amountnumber | string

Total tax liability amount.

tax_liability_sourceTaxLiabilitySourceEnum

Source of tax liability.

Available options:CALCULATEDCOLLECTED
taxable_amountnumber | string

Taxable amount.

currencyCurrencyEnum

Currency code (ISO 4217, e.g., USD)

Available options:AEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBZDCADCDFCHFCLPCNYCOPCRCCUCCUPCVECZKDJFDKKDOPDZDEGPERNETBEURFJDFKPGBPGELGGPGHSGIPGMDGNFGTQGYDHKDHNLHRKHTGHUFIDRILSIMPINRIQDIRRISKJEPJMDJODJPYKESKGSKHRKMFKPWKRWKWDKYDKZTLAKLBPLKRLRDLSLLYDMADMDLMGAMKDMMKMNTMOPMRUMURMVRMWKMXNMYRMZNNADNGNNIONOKNPRNZDOMRPABPENPGKPHPPKRPLNPYGQARRONRSDRUBRWFSARSBDSCRSDGSEKSGDSHPSLLSOSSPLSRDSTNSVCSYPSZLTHBTJSTMTTNDTOPTRYTTDTVDTWDTZSUAHUGXUSDUYUUZSVEFVNDVUVWSTXAFXCDXDRXOFXPFYERZARZMWZWD
lockedboolean

Transaction lock status.

sourceSourceEnum

Source platform (e.g., STRIPE)

Available options:BIGCOMMERCEBESTBUYBUNNYCHARGEBEESHOPIFYSHOPLINEECWIDSTRIPEAMAZONTIKTOKCUSTOMUNKNOWNIMPORTZUORAAPIDECKQUICKBOOKSAPIAPPLE_APP_STOREGOOGLE_APP_STOREWALMARTPAYPALNETSUITEXEROMAXIORECURLYSALESFORCEETSYEBAYWIXSQUARESPACEWOOCOMMERCEMAGENTOMACYSBILLING_PLATFORMDEELRIPPLINGGUSTOFACEBOOKOTHERORDWAYINSTAGRAMPINTERESTWAYFAIRWISHPOSTARGETNEWEGGGROUPONGOOGLE_EXPRESSNOCNOCMERCADO_LIBREMODALYSTNORDSTROMFAIRESHOPWAREZOHOSAGE-INTACCTAIRWALLEXORBZENSKARMICROSOFT_DYNAMICS_365KICKSTARTERINTERNAL_ERPRILLETCAMPFIREKILL_BILLPROVISIONVERTEX_O_SERIESCHECKOUTCHAMPDUALENTRYODOOBILL_COMINTUIT_ENTERPRISE_SUITEACUMATICAPLENTYONE
connection_idstring

Connection Identifier

filing_idstring

Filing identifier.

citystring

City of the transaction address.

countystring

County of the transaction address.

statestring

State of the transaction address.

countryCountryCodeEnum

Country code (ISO Alpha-2).

Available options:AFAXALDZASADAOAIAQAGARAMAWAUATAZBSBHBDBBBYBEBZBJBMBTBOBQBABWBVBRIOBNBGBFBICVKHCMCAKYCFTDCLCNCXCCCOKMCGCDCKCRHRCUCWCYCZDKDJDMDOECEGSVGQEREESZETFKFOFJFIFRGFPFTFGAGMGEDEGHGIGRGLGDGPGUGTGGGNGWGYHTHMVAHNHKHUISINIDIRIQIEIMILITCIJMJPJEJOKZKEKIKPKRKWKGLALVLBLSLRLYLILTLUMOMGMWMYMVMLMTMHMQMRMUYTMXFMMDMCMNMEMSMAMZMMNANRNPNLNCNZNINENGNUNFMKMPNOOMPKPWPSPAPGPYPEPHPNPLPTPRQARERORURWBLSHKNLCMFPMVCWSSMSTSASNRSSCSLSGSXSKSISBSOZAGSSSESLKSDSRSJSECHSYTWTJTZTHTLTGTKTOTTTNTRTMTCTVUGUAAEGBUSUMUYUZVUVEVNVGVIWFEHYEZMZWXKZZ_EU
postal_codestring

Postal code of the transaction.

tax_idstring

Tax ID associated with the transaction. DEPRECATED: This field is only populated for QuickBooks integrations and will be removed in a future version.

statusTransactionStatusEnum

Transaction status (e.g., COMMITTED)

Available options:PENDINGCOMMITTEDCANCELLEDFULLY_REFUNDEDPARTIALLY_REFUNDEDINVALIDARCHIVED
document_typeDocumentTypeEnum

Document type distinguishing invoices from sales orders.

Available options:INVOICESALES_ORDERCASH_SALECASH_REFUND
created_fromstring

Identifier of the invoice that created from a sales order.

addressesTransactionAddressPublic[]Required
transaction_itemsTransactionItemBuilder[]Required
customerCustomerBaseBase | TransactionImportCustomerRequired
typeTransactionTypeEnumRequired
Available options:SALEFULL_CREDIT_NOTEPARTIAL_CREDIT_NOTETAX_REFUNDTAX_COLLECTIONARCHIVE

Response

requires_exemptionExemptionRequired

Indicates if transaction requires tax exemption.

organization_idstringRequired

Unique identifier of the organization. This field is deprecated, and should no longer be used. The value is populated through the 'x-organization-id' header.

external_idstringRequired

External identifier of the transaction.

datestringRequired

Transaction date and time

shop_datestring

Transaction date in the shop's local timezone

shop_date_tzstring

Timezone of the shop

descriptionstring

Description of the transaction.

refund_statusTransactionRefundStatus

Status of refund, if applicable

Available options:FULLY_REFUNDEDPARTIALLY_REFUNDED
total_amountstring

Total amount of the transaction.

customer_idstring

Unique identifier of the customer.

marketplaceboolean

Indicates if transaction is marketplace-based.

exemptTransactionExemptStatusEnum

Exemption status (e.g., NOT_EXEMPT)

Available options:NOT_EXEMPTPARTIALLY_EXEMPTFULLY_EXEMPTZERO_RATE_NOT_EXEMPT
exemptionsExemption[]

List of exemptions applied (if any).

related_tostring

Related transaction identifier.

secondary_external_idstring

Secondary External Identifier.

secondary_sourcestring

Secondary source information

external_friendly_idstring

Friendly identifier of the original item.

total_tax_amount_importedstring

Imported tax amount.

tax_rate_importedstring

Imported tax rate.

total_tax_amount_calculatedstring

Calculated tax amount.

tax_rate_calculatedstring

Calculated tax rate.

total_tax_liability_amountstring

Total tax liability amount.

tax_liability_sourceTaxLiabilitySourceEnum

Source of tax liability.

Available options:CALCULATEDCOLLECTED
taxable_amountstring

Taxable amount.

currencyCurrencyEnum

Currency code (ISO 4217, e.g., USD)

Available options:AEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBZDCADCDFCHFCLPCNYCOPCRCCUCCUPCVECZKDJFDKKDOPDZDEGPERNETBEURFJDFKPGBPGELGGPGHSGIPGMDGNFGTQGYDHKDHNLHRKHTGHUFIDRILSIMPINRIQDIRRISKJEPJMDJODJPYKESKGSKHRKMFKPWKRWKWDKYDKZTLAKLBPLKRLRDLSLLYDMADMDLMGAMKDMMKMNTMOPMRUMURMVRMWKMXNMYRMZNNADNGNNIONOKNPRNZDOMRPABPENPGKPHPPKRPLNPYGQARRONRSDRUBRWFSARSBDSCRSDGSEKSGDSHPSLLSOSSPLSRDSTNSVCSYPSZLTHBTJSTMTTNDTOPTRYTTDTVDTWDTZSUAHUGXUSDUYUUZSVEFVNDVUVWSTXAFXCDXDRXOFXPFYERZARZMWZWD
lockedboolean

Transaction lock status.

sourceSourceEnum

Source platform (e.g., STRIPE)

Available options:BIGCOMMERCEBESTBUYBUNNYCHARGEBEESHOPIFYSHOPLINEECWIDSTRIPEAMAZONTIKTOKCUSTOMUNKNOWNIMPORTZUORAAPIDECKQUICKBOOKSAPIAPPLE_APP_STOREGOOGLE_APP_STOREWALMARTPAYPALNETSUITEXEROMAXIORECURLYSALESFORCEETSYEBAYWIXSQUARESPACEWOOCOMMERCEMAGENTOMACYSBILLING_PLATFORMDEELRIPPLINGGUSTOFACEBOOKOTHERORDWAYINSTAGRAMPINTERESTWAYFAIRWISHPOSTARGETNEWEGGGROUPONGOOGLE_EXPRESSNOCNOCMERCADO_LIBREMODALYSTNORDSTROMFAIRESHOPWAREZOHOSAGE-INTACCTAIRWALLEXORBZENSKARMICROSOFT_DYNAMICS_365KICKSTARTERINTERNAL_ERPRILLETCAMPFIREKILL_BILLPROVISIONVERTEX_O_SERIESCHECKOUTCHAMPDUALENTRYODOOBILL_COMINTUIT_ENTERPRISE_SUITEACUMATICAPLENTYONE
connection_idstring

Connection Identifier

filing_idstring

Filing identifier.

citystring

City of the transaction address.

countystring

County of the transaction address.

statestring

State of the transaction address.

countryCountryCodeEnum

Country code (ISO Alpha-2).

Available options:AFAXALDZASADAOAIAQAGARAMAWAUATAZBSBHBDBBBYBEBZBJBMBTBOBQBABWBVBRIOBNBGBFBICVKHCMCAKYCFTDCLCNCXCCCOKMCGCDCKCRHRCUCWCYCZDKDJDMDOECEGSVGQEREESZETFKFOFJFIFRGFPFTFGAGMGEDEGHGIGRGLGDGPGUGTGGGNGWGYHTHMVAHNHKHUISINIDIRIQIEIMILITCIJMJPJEJOKZKEKIKPKRKWKGLALVLBLSLRLYLILTLUMOMGMWMYMVMLMTMHMQMRMUYTMXFMMDMCMNMEMSMAMZMMNANRNPNLNCNZNINENGNUNFMKMPNOOMPKPWPSPAPGPYPEPHPNPLPTPRQARERORURWBLSHKNLCMFPMVCWSSMSTSASNRSSCSLSGSXSKSISBSOZAGSSSESLKSDSRSJSECHSYTWTJTZTHTLTGTKTOTTTNTRTMTCTVUGUAAEGBUSUMUYUZVUVEVNVGVIWFEHYEZMZWXKZZ_EU
postal_codestring

Postal code of the transaction.

tax_idstring

Tax ID associated with the transaction. DEPRECATED: This field is only populated for QuickBooks integrations and will be removed in a future version.

statusTransactionStatusEnum

Transaction status (e.g., COMMITTED)

Available options:PENDINGCOMMITTEDCANCELLEDFULLY_REFUNDEDPARTIALLY_REFUNDEDINVALIDARCHIVED
document_typeDocumentTypeEnum

Document type distinguishing invoices from sales orders.

Available options:INVOICESALES_ORDERCASH_SALECASH_REFUND
created_fromstring

Identifier of the invoice that created from a sales order.

address_statusAddressStatus

Address verification status (e.g., VERIFIED).

Available options:UNVERIFIEDINVALIDPARTIALLY_VERIFIEDVERIFIEDUNVERIFIABLEBLANK
processing_statusProcessingStatusEnum

Status of processing (e.g., ADDRESS_DONE)

Available options:NEWUPDATEDQUEUEDADDRESS_DONEEXEMPT_DONENEXUS_DONEPROCESSEDFILING_STARTEDFILING_DONELOCKEDPENDINGARCHIVEDNEEDS_REFETCHEXCLUDED_IN_CALCULATIONDEFERRED_FROM_FILING
is_duplicateboolean
destination_currencyCurrencyEnum

Destination currency code (ISO 4217, e.g., USD)

Available options:AEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBZDCADCDFCHFCLPCNYCOPCRCCUCCUPCVECZKDJFDKKDOPDZDEGPERNETBEURFJDFKPGBPGELGGPGHSGIPGMDGNFGTQGYDHKDHNLHRKHTGHUFIDRILSIMPINRIQDIRRISKJEPJMDJODJPYKESKGSKHRKMFKPWKRWKWDKYDKZTLAKLBPLKRLRDLSLLYDMADMDLMGAMKDMMKMNTMOPMRUMURMVRMWKMXNMYRMZNNADNGNNIONOKNPRNZDOMRPABPENPGKPHPPKRPLNPYGQARRONRSDRUBRWFSARSBDSCRSDGSEKSGDSHPSLLSOSSPLSRDSTNSVCSYPSZLTHBTJSTMTTNDTOPTRYTTDTVDTWDTZSUAHUGXUSDUYUUZSVEFVNDVUVWSTXAFXCDXDRXOFXPFYERZARZMWZWD
converted_total_amountstring

Converted total amount.

converted_total_tax_amount_importedstring

Converted imported tax amount.

converted_total_tax_amount_calculatedstring

Converted calculated tax amount.

conversion_ratestring

Currency conversion rate.

converted_taxable_amountstring

Converted taxable amount.

converted_total_discountstring

Converted total discount amount.

converted_subtotalstring

Converted subtotal amount.

converted_total_tax_liability_amountstring

Converted total tax liability amount.

idstringRequired

The unique transaction identifier.

store_namestring

Display name of the store when the organization has multiple stores for a source.

is_deferred_transactionboolean

Whether this transaction was deferred (rolled over) from a prior filing period.

directionTransactionDirectionEnum
Available options:SALEPURCHASE
addressesTransactionAddressRead-Output[]Required

List of addresses associated.

transaction_itemsTransactionItemRead[]Required

List of items in the transaction.

customerCustomerRead

Customer information associated with the transaction.

typeTransactionTypeEnumRequired

The type of transaction (e.g., SALE, REFUND, PARTIAL_CREDIT_NOTE).

Available options:SALEFULL_CREDIT_NOTEPARTIAL_CREDIT_NOTETAX_REFUNDTAX_COLLECTIONARCHIVE
total_discountstring

Total amount of all discounts applied to the transaction.

subtotalstring

Subtotal amount before any discounts are applied.

final_total_amountstring

Final total amount including tax liability.

converted_final_total_amountstring

Converted final total amount including tax liability.

202

Successfully created transaction

400

Bad Request - Invalid input or business rule violation

401

Unauthorized - Authentication failed

422

Validation error - Request data failed validation

500

Internal server error

cURL
POST /v1/transactions
-H "x-api-key: ***"
{
"organization_id": "orgn_YourOrgIdHere",
"external_id": "YourUniqueOrder123",
"date": "2024-01-15T14:30:00Z",
"type": "SALE",
"currency": "USD",
"marketplace": true,
"customer": {
"organization_id": "orgn_YourOrgIdHere",
"external_id": "Cust456",
"name": "John Doe"
},
"addresses": [
{
"type": "SHIP_TO",
"country": "US",
"state": "CA",
"city": "San Francisco",
"postal_code": "94107",
"street_1": "123 Main St"
}
],
"transaction_items": [
{
"organization_id": "orgn_YourOrgIdHere",
"date": "2024-01-15T14:30:00Z",
"external_product_id": "SKU-ABC",
"product": "Example Widget",
"quantity": 2,
"amount": 50
}
],
"source": "API"
}
Response
[
{
"organization_id": "orgn_YOURORGID",
"external_id": "tran_YOURTRANSACTIONID",
"date": "2024-01-15T14:30:00",
"status": "COMMITTED",
"description": "Order with one taxable book and one exempt service",
"processing_status": "QUEUED",
"total_amount": "200.00",
"customer_id": "cust_afXm2qPEycF83",
"marketplace": false,
"exempt": "FULLY_EXEMPT",
"exemptions": [
{
"updated_at": "2025-05-22T14:48:46.056060",
"start_date": "2025-01-23",
"transaction_id": "tran_nc5Q4hLi97NRD",
"reseller": true,
"status": "ACTIVE",
"created_at": "2025-05-22T14:48:46.193109",
"exemption_type": "transaction",
"customer_id": "cust_afXm2qPEycF83",
"id": "exmp_xfLpDHxxX4Cxv",
"organization_id": "orgn_UT7zEcgwt4Fhk"
}
],
"total_tax_amount_imported": "6.00",
"tax_rate_imported": "0.030000000",
"total_tax_amount_calculated": "0.00",
"tax_rate_calculated": "0E-9",
"total_tax_liability_amount": "6.00",
"tax_liability_source": "COLLECTED",
"taxable_amount": "200.00",
"currency": "USD",
"locked": false,
"source": "API",
"address_status": "UNVERIFIED",
"id": "tran_g9WJFTdFjLzDv",
"addresses": [
{
"street_1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94107",
"country": "US",
"type": "SHIP_TO",
"status": "UNVERIFIED",
"id": "addr_tWqfSwDZK7aSt",
"transaction_id": "tran_g9WJFTdFjLzDv"
}
],
"transaction_items": [
{
"external_id": "LI_BOOK_TAXABLE_001",
"organization_id": "orgn_YOURORGID",
"date": "2025-01-24T11:00:00",
"external_product_id": "PROD_BOOK_SCIFI_HC",
"product": "Sci-Fi Hardcover Novel",
"product_id": "prod_AKczKRGnAe3d3",
"quantity": "1",
"amount": "100.00",
"tax_amount_imported": "6.00",
"tax_rate_imported": "0.060000000",
"tax_amount_calculated": "0.00",
"tax_rate_calculated": "0E-9",
"taxable_amount": "100.00",
"exempt": false,
"id": "txim_c63o27oiEhLuA",
"tax_items": [
{
"rule_id": "0000",
"rate": "0.060000000",
"amount": "6.00",
"name": "PA State Sales Tax",
"type": "IMPORTED",
"jurisdiction_type": "STATE",
"jurisdiction_name": "PA"
}
],
"total_discount": "0.00",
"subtotal": "100.00"
},
{
"external_id": "LI_SERVICE_EXEMPT_002",
"organization_id": "orgn_YOURORGID",
"date": "2025-01-24T11:00:00",
"external_product_id": "PROD_DIGITAL_SERVICE_EX",
"product": "Digital Marketing Service (Non-Taxable in PA)",
"product_id": "prod_zz2RshS8uweRe",
"quantity": "1",
"amount": "100.00",
"tax_amount_imported": "0.00",
"tax_rate_imported": "0E-9",
"tax_amount_calculated": "0.00",
"tax_rate_calculated": "0E-9",
"taxable_amount": "100.00",
"tax_exemption": "PRODUCT",
"exempt": false,
"id": "txim_eqwAKmiDpgf2m",
"tax_items": [],
"total_discount": "0.00",
"subtotal": "100.00"
}
],
"customer": {
"name": "John Doe",
"external_id": "Cust456",
"status": "ACTIVE",
"email": "buyer@example.com",
"address_status": "UNVERIFIED",
"id": "cust_afXm2qPEycF83",
"organization_id": "orgn_YOURORGID"
},
"type": "SALE",
"total_discount": "0.00",
"subtotal": "200.00"
}
]