# 4. Handling Refund Transactions (2026-07-21)

> Create credit notes and refund records that properly track refunds for compliance and filing preparation

Source: https://docs.trykintsugi.com/docs/2026-07-21/api-guides/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.

Credit notes are transactions: In the Tenanted API there is no separate credit note endpoint. Create one with POST /transactions, setting type to FULL_CREDIT_NOTE or PARTIAL_CREDIT_NOTE and sending originalTransactionId. Kintsugi derives the stored type from the amount credited, so it can differ from the one you send.

## 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

Which sales can be credited: The original must be a sale whose status is PENDING, COMMITTED, or PARTIALLY_REFUNDED. A transaction that is not a sale, or a sale in any other state, such as CANCELLED, is rejected with 400. Reversing a transaction you do not own answers 404, the same as one that does not exist.

## 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

## Creating Credit Notes

The original lines need external IDs: A credit note can only reverse a line by its externalId. A line that does not match a line on the original sale is rejected with 400, so send externalId on every line when you sync the sale.

Either sign works: Send totalAmount and item amounts positive or negative as you prefer. Kintsugi stores credit note amounts as negative values, so the stored record is consistent either way. Quantities stay positive.

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.

1

Find the original transaction

GET /transactions?search=<externalId> Look it up by your own id

originalTransactionId takes Kintsugi's transaction id, not your externalId, so you need this unless you stored the id when you synced the sale.

2

Check the sale can be credited

It must be a sale whose status is PENDING, COMMITTED, or PARTIALLY_REFUNDED.

REJECTED → A transaction that is not a sale, or a sale in any other state such as CANCELLED, comes back 400. One you do not own answers 404, the same as one that does not exist.

3

Build the credit note

Match each line you are crediting to a line on the original sale by externalId, give each a taxableAmount, then total them.

CHECK Two independent caps apply, both against the remaining balance: the total against the sale's totalAmount plus its tax, and each line against its original line. An over-refund is rejected with 400, not trimmed to fit.

4

Create the credit note

## Creating Credit Notes

type originalTransactionId externalId date currency items

POST /transactions Answers 202 Accepted

Set type to FULL_CREDIT_NOTE or PARTIAL_CREDIT_NOTE. Non-2xx? Back off and retry on 5xx and 429; fix the payload on other 4xx. See Error Handling.

5

Refund recorded

The credit note is stored as COMMITTED, the original sale's refund status is reconciled in the same request, and the credit offsets the sale in compliance calculations.

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

The two values are derived differently: When a credit note is created, its type is decided by comparing that note's totalAmount against the sale's. The sale's refund status is cumulative, comparing the total of every committed credit note against the sale's totalAmount. On a single full refund they agree; across several partial refunds they can differ, so use the refund status when you need the sale's overall position.

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.

Two caps apply, both against the remaining balance: Kintsugi checks the credit note total against what is still creditable on the sale, and separately checks each line against what is still creditable on the matching original line. Either one over is a 400, so an over-refund is rejected rather than trimmed to fit.

The transaction-level cap is the sale's totalAmount plus its tax, minus everything already credited by committed credit notes. The tax counted is the sale's imported tax when it has any, and the tax Kintsugi calculated otherwise.

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

Filed records lock: A locked or already-filed credit note answers 409 and can no longer be updated. Make corrections before the filing period closes.

## 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:

Find the original transaction

Create a credit note containing only the returned line item

Credit that item's share of the order

Kintsugi marks the original transaction PARTIALLY_REFUNDED

Full Order Refund

The entire order is refunded:

Find the original transaction

Create a credit note containing every line item

Credit the full original amount

Kintsugi marks the original transaction FULLY_REFUNDED

Multiple Partial Refunds

Refunds arrive over time:

Create a credit note for the first refund

Add further credit notes as later refunds are issued

Kintsugi tracks the cumulative credited total

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.

Worked example Bar shows the amount still refundable

Original transaction $100.00

Committed, nothing credited yet $100.00 remaining

CREDIT NOTE 1 Partial refund −$30.00

PARTIALLY_REFUNDED $70.00 remaining

CREDIT NOTE 2 Refunds the rest −$70.00

FULLY_REFUNDED $0.00 remaining

Two credit notes of $70.00 against a $100.00 sale is rejected, not clamped: the second comes back 400 and nothing is written. Check the remaining balance before every credit note, not just the first.

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.

PARTIALLY_REFUNDED

Committed credit notes total less than the sale's totalAmount. The sale can carry further credit notes while creditable balance remains.

FULLY_REFUNDED

Committed credit notes reach the sale's totalAmount.

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

Reading the refund status: The transaction response does not carry a refund status field. Find refunded sales by filtering GET /transactions with refundStatus=FULLY_REFUNDED,PARTIALLY_REFUNDED, and list the credit notes against one sale with List related transactions. The Tenanted API does not let you set a refund status directly.

## Next Steps

With refund handling in place:

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.

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

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

---

Index of every page: https://docs.trykintsugi.com/llms.txt