- API
- Invoices
- Refunds
Refund a credit note on a paid invoice#
A credit note can now return money. Until this release a note could only be allocated against an outstanding balance, so a correction to a paid invoice meant a credit note for the paperwork and a separate refund against the order. Now the note creates the refund, and the refund stays linked to it.
To issue a draft and refund it in one call, add refund to POST /v1/credit-notes/{credit_note_id}/issue. The response keeps the credit note at data and adds the refund at data.refund. For a note that is already issued, call POST /v1/credit-notes/{credit_note_id}/refunds, which returns the Refund resource. Both accept amount_money, reason, and reason_message. Leave amount_money out to refund all available credit. The money goes back to the original payment methods; payments you recorded manually are not eligible.
Both calls require a caller-chosen Idempotency-Key, and both need commerce.credit_notes.write and commerce.refunds.write. Flint keeps the key for the life of the refund. To recover a response you lost, call GET /v1/credit-notes/{credit_note_id}/refunds?idempotency_key=..., which needs both read scopes.
Credit notes carry two new fields. pending_refund_money reserves credit while a refund is unresolved, and refunded_money records what succeeded. Both reduce unallocated_money, and a failed or canceled refund releases its amount. Refunds created this way carry credit_note_id and invoice_id, and they fire the existing refund.* events. The invoice stays paid, with refund_status and refunded_money tracking the refund as before.
A credit note cannot be voided while a refund on it is pending or after one succeeds; the call returns CREDIT_NOTE_HAS_ALLOCATIONS. A refund larger than the available credit returns CREDIT_NOTE_REFUND_EXCEEDS_BALANCE, and an ineligible invoice or note returns CREDIT_NOTE_REFUND_INVALID.
These changes are additive. See Refund a paid invoice for the walkthrough.