Update a credit note
Update an existing credit note (a transaction whose type is FULL_CREDIT_NOTE or PARTIAL_CREDIT_NOTE). A true partial update: every field — externalId, date, totalAmount, currency, description, marketplace, status and items — is optional, and one you omit keeps the credit note's current stored value rather than being reset to a default. Send status as CANCELLED to reverse the credit note without deleting it; omitted, it stays whatever it already is (it does NOT default to COMMITTED). Calling this on a transaction that is not a credit note answers 400; on one already CANCELLED also answers 400. A locked or already-filed credit note answers 409. Updating a credit note you do not own answers 404, identical to one that does not exist. PUT /transactions/{transactionId} amends an ordinary transaction; it does not accept a credit note.
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 credit note to update.
Body
Your stable identifier for the credit note. Omit to keep the stored one.
When the credit note was issued. Omit to keep the stored date.
Lifecycle state of the credit note. Send CANCELLED to reverse it without deleting it; amounts and lines are otherwise unaffected. Omit to keep the current status — it does NOT default to COMMITTED.
PENDINGCOMMITTEDCANCELLEDISO-4217 currency of every amount sent. Omit to keep the stored currency.
AEDAFNALLAMDANGAOAARSAUDAWGAZNBAMBBDBDTBGNBHDBIFBMDBNDBOBBRLBSDBTNBWPBYNBZDCADCDFCHFCLPCNYCOPCRCCUCCUPCVECZKDJFDKKDOPDZDEGPERNETBEURFJDFKPGBPGELGGPGHSGIPGMDGNFGTQGYDHKDHNLHRKHTGHUFIDRILSIMPINRIQDIRRISKJEPJMDJODJPYKESKGSKHRKMFKPWKRWKWDKYDKZTLAKLBPLKRLRDLSLLYDMADMDLMGAMKDMMKMNTMOPMRUMURMVRMWKMXNMYRMZNNADNGNNIONOKNPRNZDOMRPABPENPGKPHPPKRPLNPYGQARRONRSDRUBRWFSARSBDSCRSDGSEKSGDSHPSLLSOSSPLSRDSTNSVCSYPSZLTHBTJSTMTTNDTOPTRYTTDTVDTWDTZSUAHUGXUSDUYUUZSVEFVNDVUVWSTXAFXCDXDRXOFXPFYERZARZMWZWDTotal credit note amount. Omit to keep the stored amount — there is no default of 0.00.
Free-text description of the credit note. Omit to keep the stored description.
True for a marketplace or reseller credit note. Omit to keep the credit note's current marketplace flag.
Lines to credit. Each must carry the externalId of the original sale's line it reverses, exactly like the credit-note create. Omit to keep the credit note's stored lines.
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.