Create a transaction

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.

Your stable identifier for the transaction. Re-sending the same one updates the existing transaction rather than creating a second.

When the transaction occurred. This drives which filing period it lands in, so send the real transaction time, not the time of the call.

Kind of transaction. SALE records a sale; FULL_CREDIT_NOTE or PARTIAL_CREDIT_NOTE with originalTransactionId reverses a committed sale. The stored type is derived from the amount credited, so it can differ from the one you send.

The committed sale being reversed. Required when type is a credit-note type and must be omitted for a SALE. The credit note inherits the original's customer, addresses and source, so send only the lines to credit in items.

ISO-4217 currency of every amount sent.

Total transaction amount.

Addresses for the transaction. Jurisdiction is resolved from these, so an incomplete address means tax cannot be calculated accurately.

Line items on the transaction.

Customer the transaction is attributed to. Omit it for a sale with no customer identity, such as a marketplace or point-of-sale transaction: the transaction is then attributed to the organization's shared unattributed-sales customer, and the response's customerId points at it.

Free-text description of the transaction.

True for reseller or marketplace orders where tax was remitted by someone else. Gross sales still count toward nexus, but tax liability is excluded.

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.

Settlement state. Only COMMITTED counts toward filed liability; PENDING may still change.

Whether the organization made the sale or made the purchase. Both are returned, so filter on this if you only want one side.

Kintsugi 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.

Transaction description; an empty string when the source sent none.

ISO-4217 currency every unconverted amount on this transaction is in.

Total 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.

Which figure backs totalTaxLiabilityAmount: CALCULATED for the tax Kintsugi calculated, COLLECTED for the tax the source reported it already collected.

Validation status of the transaction's addresses.

Currency the converted amounts are expressed in, or null when no conversion applied.

Rate 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.