Update a transaction's addresses
Edit one or more of a transaction's addresses without touching its line items. Each address is upserted by its type (or id); a type you omit is left unchanged. Editing an address resets its validation, so addressStatus returns to UNVERIFIED and the address is re-verified on the next processing pass. Returns the updated transaction. Editing a transaction you do not own answers 404, identical to one that does not exist.
Authorization
Headers
Release date, as YYYY-MM-DD. Defaults to 2026-07-21.
Target organization id (Organization-Id selector).
Target connection id; resolves to its organization.
Platform entity id; resolves to a connection's organization.
Optional source to disambiguate an Entity-Id.
Path parameters
The unique identifier of the transaction to edit.
Body
Addresses to update on the transaction. Each is upserted by type (or id); a type you omit is left unchanged, and line items are never touched. Editing an address resets its validation, so it is re-verified on the next processing pass.
Response
Kintsugi's unique identifier for the transaction.
Organization the transaction belongs to. Present on every row because a portfolio-wide list spans organizations.
Your stable identifier for the transaction.
Human-readable identifier from the source, such as an invoice number; an empty string when the source has only an externalId.
When the transaction occurred. This drives filing-period assignment.
Document shape of the transaction. Credit-note and tax-refund types reverse or adjust prior sales.
SALEFULL_CREDIT_NOTEPARTIAL_CREDIT_NOTETAX_REFUNDTAX_COLLECTIONSettlement state. Only COMMITTED counts toward filed liability; PENDING may still change.
PENDINGCOMMITTEDCANCELLEDFULLY_REFUNDEDPARTIALLY_REFUNDEDINVALIDWhether the organization made the sale or made the purchase. Both are returned, so filter on this if you only want one side.
SALEPURCHASEKintsugi customer this transaction is attributed to. A sale with no customer identity (marketplace, point-of-sale) is attributed to the organization's shared unattributed-sales customer, which reads back with a null externalId. Check that before treating one customerId as one buyer.
Name of the customer this transaction is attributed to, or null when it has no customer or the customer has no name.
Connection that synced this transaction, if any.
Origin system of the transaction. Sources outside the public set are reported as OTHER.
ACUMATICAAIRWALLEXAMAZONAPIAPPLE_APP_STOREBESTBUYBIGCOMMERCEBILL_COMBUNNYCAMPFIRECHARGEBEECHECKOUTCHAMPDEELDUALENTRYEBAYECWIDETSYFACEBOOKFAIREFRESHBOOKSGOOGLE_APP_STOREGOOGLE_EXPRESSGROUPONGUSTOHYPERLINEINSTAGRAMINTUIT_ENTERPRISE_SUITEKICKSTARTERKILL_BILLMACYSMAGENTOMAXIOMERCADO_LIBREMICROSOFT_DYNAMICS_365MODALYSTNETSUITENEWEGGNOCNOCNORDSTROMODOOOPENMETERORBORDWAYOTHERPAYPALPINTERESTPLENTYONEQUICKBOOKSRECURLYRILLETRIPPLINGSAGE-INTACCTSALESFORCESHOPIFYSHOPLINESHOPWARESQUARESPACESTRIPETARGETTIKTOKVERTEX_O_SERIESWALMARTWAYFAIRWISHWIXWOOCOMMERCEXEROZENSKARZOHOZUORATransaction description; an empty string when the source sent none.
ISO-4217 currency every unconverted amount on this transaction is in.
AEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBZDCADCDFCHFCLPCNYCOPCRCCUCCUPCVECZKDJFDKKDOPDZDEGPERNETBEURFJDFKPGBPGELGGPGHSGIPGMDGNFGTQGYDHKDHNLHRKHTGHUFIDRILSIMPINRIQDIRRISKJEPJMDJODJPYKESKGSKHRKMFKPWKRWKWDKYDKZTLAKLBPLKRLRDLSLLYDMADMDLMGAMKDMMKMNTMOPMRUMURMVRMWKMXNMYRMZNNADNGNNIONOKNPRNZDOMRPABPENPGKPHPPKRPLNPYGQARRONRSDRUBRWFSARSBDSCRSDGSEKSGDSHPSLLSOSSPLSRDSTNSVCSYPSZLTHBTJSTMTTNDTOPTRYTTDTVDTWDTZSUAHUGXUSDUYUUZSVEFVNDVUVWSTXAFXCDXDRXOFXPFYERZARZMWZWDTotal transaction amount.
Portion of the total that tax was assessed on.
Total tax the source system reported.
Total tax Kintsugi calculated.
Total tax the organization is liable for. On a SALE it is either the imported or the calculated total, depending on the liability source. On a PURCHASE it is the sum of each line's net use tax, so it does not equal either total.
Total discount applied across the transaction's lines; 0.00 when there is none.
totalAmount plus totalTaxLiabilityAmount: what the transaction totals once the organization's tax liability is added.
Whether any line on this transaction was treated as exempt. Derived from the line items, so it can never disagree with them.
Whether the transaction is locked for editing. A locked transaction backs a submitted return and cannot be amended or archived.
True for marketplace or reseller orders where the marketplace remitted tax on the seller's behalf. null when the source did not report it.
Calendar day the transaction occurred in the shop's timezone (YYYY-MM-DD), or null when the source did not report one. Distinct from date, which is the UTC timestamp.
How far the transaction has progressed through processing (address resolution, exemption, nexus, tax calculation). PROCESSED means tax calculation has completed.
ADDRESS_DONEDEFERRED_FROM_FILINGEXCLUDED_IN_CALCULATIONEXEMPT_DONENEEDS_REFETCHNEXUS_DONEPROCESSEDQUEUEDWhich figure backs totalTaxLiabilityAmount: CALCULATED for the tax Kintsugi calculated, COLLECTED for the tax the source reported it already collected.
CALCULATEDCOLLECTEDValidation status of the transaction's addresses.
UNVERIFIEDINVALIDPARTIALLY_VERIFIEDVERIFIEDUNVERIFIABLEBLANKCurrency the converted amounts are expressed in, or null when no conversion applied.
AEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBZDCADCDFCHFCLPCNYCOPCRCCUCCUPCVECZKDJFDKKDOPDZDEGPERNETBEURFJDFKPGBPGELGGPGHSGIPGMDGNFGTQGYDHKDHNLHRKHTGHUFIDRILSIMPINRIQDIRRISKJEPJMDJODJPYKESKGSKHRKMFKPWKRWKWDKYDKZTLAKLBPLKRLRDLSLLYDMADMDLMGAMKDMMKMNTMOPMRUMURMVRMWKMXNMYRMZNNADNGNNIONOKNPRNZDOMRPABPENPGKPHPPKRPLNPYGQARRONRSDRUBRWFSARSBDSCRSDGSEKSGDSHPSLLSOSSPLSRDSTNSVCSYPSZLTHBTJSTMTTNDTOPTRYTTDTVDTWDTZSUAHUGXUSDUYUUZSVEFVNDVUVWSTXAFXCDXDRXOFXPFYERZARZMWZWDRate used to convert into destinationCurrency. Not a fraction: a rate into a currency quoted in thousands per unit is a large number. null when no conversion applied, and also when the transaction is already in destinationCurrency, where the converted amounts equal their originals.
totalAmount in the destination currency, or null when no conversion applied. Never 0 to mean unconverted: check for null.
totalTaxLiabilityAmount in the destination currency, or null when no conversion applied. Never 0 to mean unconverted: a zero here is a real converted liability of zero, so check for null.
totalDiscount in the destination currency, or null when no conversion applied.
finalTotalAmount in the destination currency, or null when no conversion applied.
When Kintsugi first recorded this transaction.
When Kintsugi last modified this transaction, or null if it has not been modified since it was recorded.
Addresses on the transaction, used to resolve jurisdiction.
Line items on the transaction.
Successful Response
The request was invalid.
Authentication failed or was missing.
The credential is not permitted for this request.
The requested resource was not found.
The request conflicts with existing state.
The request failed validation.