KintsugiKintsugi
API reference / Create transaction

Create transaction

POST/v1/transactions

Create a transaction.

Authorization

x-api-keystringRequired

Your secret API key. Include it with every request.

x-organization-idstringRequired

Identifies the organization this request acts on.

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

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

Imported tax amount.

tax_rate_importednumber

Imported tax rate.

total_tax_amount_calculatednumber

Calculated tax amount.

tax_rate_calculatednumber

Calculated tax rate.

total_tax_liability_amountnumber

Total tax liability amount.

tax_liability_sourceTaxLiabilitySourceEnum

Source of tax liability.

Available options:CALCULATEDCOLLECTED
taxable_amountnumber

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:BIGCOMMERCEBESTBUYBUNNYCHARGEBEESHOPIFYSTRIPEAMAZONTIKTOKCUSTOMUNKNOWNIMPORTZUORAAPIDECKQUICKBOOKSAPIAPPLE_APP_STOREGOOGLE_APP_STOREWALMARTPAYPALNETSUITEXEROMAXIORECURLYSALESFORCEETSYEBAYWIXSQUARESPACEWOOCOMMERCEMAGENTOBILLING_PLATFORMDEELRIPPLINGGUSTOFACEBOOKOTHERORDWAYINSTAGRAMPINTERESTWAYFAIRWISHPOSTARGETNEWEGGGROUPONGOOGLE_EXPRESSNOCNOCMERCADO_LIBREMODALYSTNORDSTROMFAIRESHOPWAREZOHOSAGE-INTACCTAIRWALLEXORBZENSKARMICROSOFT_DYNAMICS_365KICKSTARTERINTERNAL_ERP
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
addressesTransactionAddressPublic[]Required
transaction_itemsTransactionItemBuilder[]Required
customerCustomerBaseBaseRequired
typeTransactionTypeEnumRequired
Available options:SALEFULL_CREDIT_NOTEPARTIAL_CREDIT_NOTETAX_REFUNDARCHIVE

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:BIGCOMMERCEBESTBUYBUNNYCHARGEBEESHOPIFYSTRIPEAMAZONTIKTOKCUSTOMUNKNOWNIMPORTZUORAAPIDECKQUICKBOOKSAPIAPPLE_APP_STOREGOOGLE_APP_STOREWALMARTPAYPALNETSUITEXEROMAXIORECURLYSALESFORCEETSYEBAYWIXSQUARESPACEWOOCOMMERCEMAGENTOBILLING_PLATFORMDEELRIPPLINGGUSTOFACEBOOKOTHERORDWAYINSTAGRAMPINTERESTWAYFAIRWISHPOSTARGETNEWEGGGROUPONGOOGLE_EXPRESSNOCNOCMERCADO_LIBREMODALYSTNORDSTROMFAIRESHOPWAREZOHOSAGE-INTACCTAIRWALLEXORBZENSKARMICROSOFT_DYNAMICS_365KICKSTARTERINTERNAL_ERP
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
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_CALCULATION
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.

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_REFUNDARCHIVE
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: ***"
-H "x-organization-id: ***"
{
"organization_id": "orgn_YourOrgIdHere",
"external_id": "YourUniqueOrder123",
"date": "2024-01-15T14:30:00Z",
"type": "SALE",
"currency": "USD",
"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"
}
]