4. Handling Refund Transactions

Refunds change what you owe, so they need to reach Kintsugi as deliberately as the sales they reverse. A credit note records a refund against the original transaction, keeping your filings anchored to net sales rather than gross. This guide covers when to create credit notes, how to shape them, and how full and partial refunds behave.

Understanding Credit Notes

A credit note in Kintsugi represents a refund, return, or adjustment against an original sale. Each credit note:

• Is created against the original transaction, which you name with originalTransactionId
• Carries the amount being credited on totalAmount and on each line item
• Updates the original transaction's refund status
• Offsets the original sale in compliance calculations

The outcome is filings that reflect what you actually kept.

When to Create Credit Notes

Create a credit note whenever you refund, accept a return, or adjust a completed sale:

• Product returns: The customer sends items back
• Service cancellations: The customer cancels and is refunded
• Billing adjustments: You correct an overcharge or an error
• Partial refunds: You refund specific line items rather than the whole order

Creating Credit Notes

Create credit notes with POST /transactions. originalTransactionId is the original transaction's Kintsugi transaction ID, not your externalId.

The credit note inherits the original transaction's customer, addresses, and source, so you send only the lines to credit. A credit note created through the API takes effect immediately: it is stored as COMMITTED, and the original sale's refund status is reconciled in the same request. Like any create on this endpoint, it answers 202 Accepted.

Required Fields

• type: FULL_CREDIT_NOTE or PARTIAL_CREDIT_NOTE
• originalTransactionId: The Kintsugi ID of the sale being reversed
• externalId: Your unique identifier for the credit note (for example, "cn-1")
• date: Credit note date, normally the refund date, as an RFC 3339 timestamp
• currency: ISO 4217 currency code, for example USD
• items: The line items being credited. At least one is required

Optional Fields

• totalAmount: The amount being credited. Defaults to "0.00", so send the real figure
• description: The reason for the refund, which is worth sending on every credit note
• marketplace: Inherited from the original sale when you omit it

Credit Note Line Items

Each item reverses one line of the original sale and needs:

• externalId (required): The externalId of the original line being reversed. Each original line can appear only once per credit note
• externalProductId (required): The same product identifier used on the original line
• date (required): Item date
• taxableAmount (required): The portion being credited that is subject to tax, so a partial reversal credits the taxable amount actually being reversed
• quantity: Units being credited
• amount: Value being credited for that line

Re-sending the same credit note externalId against the same original sale returns the stored credit note rather than an error, so a retried request is safe. The same externalId against a different original sale returns 409.

Credit Note Workflow

You never edit the original sale. You attach a credit note to it, and Kintsugi adjusts your liability from there.

Full Versus Partial Refunds

Kintsugi reads the amounts and classifies the refund for you.

Full Refunds

When the credit note covers the full original amount, Kintsugi records:

• Credit note type: "FULL_CREDIT_NOTE"
• Original transaction refund status FULLY_REFUNDED

The original sale is fully offset for compliance purposes.

Partial Refunds

When the credit note covers less than the original amount, Kintsugi records:

• Credit note type: "PARTIAL_CREDIT_NOTE"
• Original transaction refund status PARTIALLY_REFUNDED

The sale is reduced, not erased. You can add further partial credit notes against the same transaction while creditable balance remains.

Matching the Original Transaction

Credit note line items should mirror the sale they reverse:

• Use the same line externalId and externalProductId values. A product that is not on the original transaction is rejected with 400
• Keep credited quantities at or below the original quantities
• Keep credited amounts at or below the original amounts

That discipline gives you clean reporting on which products were returned, and an audit trail that holds up under review.

Credit Note Statuses

Credit notes use these status values:

• COMMITTED: Refund complete and included in compliance calculations. Every credit note created through the API starts here
• PENDING: Refund not yet finalized. A pending credit note does not count toward the credited total
• CANCELLED: Credit note reversed without being deleted

Updating Credit Notes

Update with PATCH /transactions/{transaction_id}, where transaction_id is the credit note's own Kintsugi ID. The original sale is taken from the credit note itself, so you do not send it. This is a true partial update: externalId, date, status, currency, totalAmount, description, marketplace, and items are all optional, and any you omit keep their stored values. Typical cases:

• Reversing a refund: Send status: "CANCELLED" to reverse the credit note without deleting it
• Amount corrections: Fixing an incorrect refund figure
• Item adjustments: Revising which lines were credited. Each item must carry the externalId of the original line it reverses, exactly as on create

status does not default to COMMITTED on an update; omitted, it stays what it is. Calling this on a transaction that is not a credit note returns 400, and so does updating a credit note that is already CANCELLED. PUT /transactions/{transaction_id} amends ordinary transactions and does not accept a credit note.

Best Practices

Creating Credit Notes

• Mirror the original: Same line IDs, same products, amounts that reconcile
• Validate before you post: Check the remaining creditable balance so the request is not rejected
• Use descriptive external IDs: Tie the credit note back to the sale, for example CN-\{original_id\}
• Always send a description: The refund reason is the first thing anyone asks about months later
• Send a taxable amount on every line: It is required, and it is what keeps a partial refund's tax correct

Finding Original Transactions

• Store Kintsugi transaction IDs: originalTransactionId needs the Kintsugi ID, so save it when you create the transaction
• Fall back to search: Without the Kintsugi ID, find the sale with GET /transactions?search=<externalId>
• Handle not-found cleanly: The original transaction must exist before a credit note can reference it

Error Handling

Common failures when creating credit notes:

• Original transaction not found: Confirm you are passing the Kintsugi transaction ID, not your externalId. A missing or foreign transaction returns 404
• Amount exceeds creditable balance: Subtract already-committed credit notes from the sale total plus its tax before you post, and check the line-level balances too
• Sale cannot be credited: The original must be a sale whose status is PENDING, COMMITTED, or PARTIALLY_REFUNDED
• Line does not match the original: Every item needs an externalId matching a line on the sale, listed once, with a taxableAmount
• Product mismatch: Reference the same products as the original line items
• Missing originalTransactionId: Required whenever type is a credit-note type, and rejected on a SALE

See the Error Handling guide for detailed strategies.

Refund Scenarios

Single Item Return

A customer returns one item from a multi-item order:

1. Find the original transaction
2. Create a credit note containing only the returned line item
3. Credit that item's share of the order
4. Kintsugi marks the original transaction PARTIALLY_REFUNDED

Full Order Refund

The entire order is refunded:

1. Find the original transaction
2. Create a credit note containing every line item
3. Credit the full original amount
4. Kintsugi marks the original transaction FULLY_REFUNDED

Multiple Partial Refunds

Refunds arrive over time:

1. Create a credit note for the first refund
2. Add further credit notes as later refunds are issued
3. Kintsugi tracks the cumulative credited total
4. The original stays PARTIALLY_REFUNDED until the credited total reaches the original amount

Refund Status Tracking

Credit notes are cumulative. Each one reduces the remaining balance, and the refund status follows the total. The worked example below assumes a sale with no tax; when the sale carries tax, the creditable balance includes it.

Refund Status on the Original

Kintsugi derives the sale's refund status from the credit notes committed against it. Until one is committed the sale has no refund status, and only committed credit notes count: a PENDING credit note neither consumes the balance nor moves the status.

Cancelling a credit note recomputes the sale's refund status from the committed credit notes that remain.

Next Steps

With refund handling in place:

1. Verify credit notes: Read them back with GET /transactions/{transaction_id}, list the credit notes against a sale with GET /transactions/{transaction_id}/related, and filter the transaction list with type=CREDIT_NOTE to review credit notes on their own. See the List transactions API reference.

2. Monitor refund status: Filter on refundStatus across your transactions so compliance figures stay accurate.

3. Plan for edge cases: Decide up front how you handle reversed refunds and refunds that span filing periods.

For endpoint-level detail, see:

• Create a transaction
• Update a credit note
• Get a transaction by id