FlintflintDocs

Credit notes

A credit note corrects an invoice you already issued, without moving money. Each note belongs to one invoice, credits specific lines from that invoice's frozen snapshot, and carries the discount and tax share of every line it touches. Money that was already collected comes back through a refund instead.

A note starts as a draft you can edit freely. Issuing it assigns credit_note_number, freezes the lines, and renders the PDF. Issuing does not change the invoice. Allocating credit against the balance does: it reduces outstanding_money and can close the invoice as credited. Allocations are append-only: reversing one leaves the original in place with reversed_at set and reopens the balance.

Allocation is the one credit-note call that requires an Idempotency-Key, and the key stays on the allocation as its identity. Allocate and reverse return the allocation, the credit note, and the recomputed invoice together; every other endpoint here returns the single resource.

See the Credit notes guide for an end-to-end walkthrough, and Invoicing for the invoice underneath.

Endpoints

The Credit note object#

Every field on a credit note, as returned by retrieve and carried by the endpoints below.

Attributes
created_atstringrequired

RFC3339 timestamp.

credit_note_idstringrequired
credit_note_linesarray of objectrequired
credit_note_numberstring

Assigned at issue and stable from then on. Absent while the credit note is a draft.

external_reference_idstring

Caller-owned identifier for this resource in an external system.

invoice_idstringrequired
issued_atstring

RFC3339 timestamp.

memostring

Free text shown on the credit note, up to 4096 characters.

merchant_idstringrequired
reasonenumrequired

Why the invoice is being corrected. Shown on the credit note document.

returned_goodsorder_adjustmentbilling_errorgoodwillother
statusenumrequired

draft while the credit note is editable, issued once it is numbered and frozen, void once retired.

draftissuedvoid
total_moneyobjectrequired

The face value of the credit note, the sum of its lines.

unallocated_moneyobjectrequired

Credit still available to allocate. Equals total_money at issue, falls as credit is applied, and rises again when an allocation is reversed.

updated_atstringrequired

RFC3339 timestamp.

versionintegerrequired

Current credit note version. Send this as expected_version when updating the draft.

voided_atstring

RFC3339 timestamp.

List credit notes#

GET/v1/credit-notesRequires scope: commerce.credit_notes.read or commerce.credit_notes.write

Returns credit notes for the authenticated merchant, newest first. Filter by invoice_id to see everything credited against one invoice.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Page token.

invoice_idstring

Filter by invoice.

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

querystring

Search across credit note ID, credit note number, memo, and external reference ID.

statusenum

Filter by status.

draftissuedvoid
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_CREDIT_NOTE_STATUSINVALID_PAGE_TOKENINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/credit-notes \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create credit note#

POST/v1/credit-notesIdempotentRequires scope: commerce.credit_notes.write

Creates a draft credit note against an invoice that has been issued and not voided. Include credit_note_lines for initial corrections or omit them for an empty draft. The draft uses the invoice currency and receives a credit note number when issued.

Request body
credit_note_linesarray of object

Initial draft corrections. Omit or send [] to create an empty draft. Null is not accepted.

external_reference_idstring

Caller-owned identifier for this resource in an external system.

invoice_idstringrequired

The invoice to correct. It has to be past draft and not voided.

memostring
reasonenumrequired
returned_goodsorder_adjustmentbilling_errorgoodwillother
Response · 201
dataobjectrequired

A correction against an issued invoice. Credit notes reduce what is owed; refunds return what was already collected.

metaobject
request_idstring

Error codes

AUTH_REQUIREDIDEMPOTENCY_KEY_IN_PROGRESSIDEMPOTENCY_KEY_REUSEDINSUFFICIENT_SCOPEINVALID_CREDIT_NOTE_MEMOINVALID_CREDIT_NOTE_REASONINVALID_REQUESTINVOICE_NOT_CREDITABLERATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/credit-notes \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "invoice_id": "",
    "reason": "returned_goods"
  }'

Get credit note#

GET/v1/credit-notes/{credit_note_id}Requires scope: commerce.credit_notes.read or commerce.credit_notes.write

Returns one credit note with its lines, total, and the credit still available to allocate.

Path parameters
credit_note_idstringrequired

Flint credit note ID.

Response · 200
dataobjectrequired

A correction against an issued invoice. Credit notes reduce what is owed; refunds return what was already collected.

metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/credit-notes/{credit_note_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update credit note#

PATCH/v1/credit-notes/{credit_note_id}IdempotentRequires scope: commerce.credit_notes.write

Updates draft credit note fields and corrections atomically. Omitted fields are unchanged, a null memo clears it, and credit_note_lines requires expected_version. Issued and void credit notes are frozen.

Path parameters
credit_note_idstringrequired

Flint credit note ID.

Request body
credit_note_linesarray of object

Replaces all draft corrections atomically with other edits. Include credit_note_line_id to retain a line, omit it to create a line, and omit a member to remove it. Send [] to clear the draft. Null is not accepted.

expected_versioninteger

Credit note version last read. Required when credit_note_lines is present.

external_reference_idstring

Caller-owned identifier for this resource in an external system.

memostring or null
reasonenum
returned_goodsorder_adjustmentbilling_errorgoodwillother
Response · 200
dataobjectrequired

A correction against an issued invoice. Credit notes reduce what is owed; refunds return what was already collected.

metaobject
request_idstring

Error codes

AUTH_REQUIREDCREDIT_NOTE_CHANGEDCREDIT_NOTE_NOT_DRAFTEMPTY_UPDATEIDEMPOTENCY_KEY_IN_PROGRESSIDEMPOTENCY_KEY_REUSEDINSUFFICIENT_SCOPEINVALID_CREDIT_NOTE_MEMOINVALID_CREDIT_NOTE_REASONINVALID_EXPECTED_VERSIONINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/credit-notes/{credit_note_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "credit_note_lines": [
      {
        "correction": {
          "type": {}
        },
        "invoice_line_item_id": ""
      }
    ],
    "expected_version": 0,
    "external_reference_id": "",
    "memo": "",
    "reason": "returned_goods"
  }'

List credit note allocations#

GET/v1/credit-notes/{credit_note_id}/allocationsRequires scope: commerce.credit_notes.read or commerce.credit_notes.write

Returns every allocation made from a credit note, including reversed ones. Filter by idempotency_key to find the allocation a given request produced.

Path parameters
credit_note_idstringrequired

Flint credit note ID.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Page token.

idempotency_keystring

Filter by caller key.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_PAGE_TOKENINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/credit-notes/{credit_note_id}/allocations \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Allocate credit note#

POST/v1/credit-notes/{credit_note_id}/allocationsIdempotentRequires scope: commerce.credit_notes.write

Applies credit from an issued credit note to its invoice, reducing outstanding_money. The amount cannot exceed the credit note's unallocated_money or the invoice's outstanding balance. Closing the balance with credit sets the invoice to credited. Returns the allocation, the credit note, and the recomputed invoice together. An Idempotency-Key is required and becomes the allocation's identity.

Path parameters
credit_note_idstringrequired

Flint credit note ID.

Request body
amount_moneyobjectrequired

Credit to apply, no more than the credit note's unallocated_money or the invoice's outstanding balance.

expected_versioninteger
Response · 201
dataobjectrequired

The allocation, the credit note with its new unallocated_money, and the recomputed invoice.

metaobject
request_idstring

Error codes

AUTH_REQUIREDCREDIT_NOTE_ALLOCATION_EXCEEDS_BALANCECREDIT_NOTE_CHANGEDCREDIT_NOTE_NOT_ISSUEDCURRENCY_MISMATCHIDEMPOTENCY_KEY_IN_PROGRESSIDEMPOTENCY_KEY_REQUIREDIDEMPOTENCY_KEY_REUSEDINSUFFICIENT_SCOPEINVALID_AMOUNTINVALID_CURRENCYINVALID_EXPECTED_VERSIONINVALID_REQUESTINVOICE_PAYMENT_RESOLVINGRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/credit-notes/{credit_note_id}/allocations \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "amount_money": {
      "amount": 0,
      "currency": "USD"
    }
  }'

Get credit note allocation#

GET/v1/credit-notes/{credit_note_id}/allocations/{credit_note_allocation_id}Requires scope: commerce.credit_notes.read or commerce.credit_notes.write

Returns one allocation. A non-null reversed_at means the credit was returned to the credit note and the invoice balance reopened.

Path parameters
credit_note_idstringrequired

Flint credit note ID.

credit_note_allocation_idstringrequired

Flint credit note allocation ID.

Response · 200
dataobjectrequired

One application of credit to the invoice. Allocations are append-only: a reversal sets reversed_at rather than removing the row.

metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/credit-notes/{credit_note_id}/allocations/{credit_note_allocation_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Reverse credit note allocation#

POST/v1/credit-notes/{credit_note_id}/allocations/{credit_note_allocation_id}/reverseIdempotentRequires scope: commerce.credit_notes.write

Reverses an allocation and reopens that much of the invoice balance. The original allocation keeps its row and gains reversed_at, so the history stays append-only. Reversing the allocation that closed an invoice moves it from credited back to open or partially_paid.

Path parameters
credit_note_idstringrequired

Flint credit note ID.

credit_note_allocation_idstringrequired

Flint credit note allocation ID.

Request body
expected_versioninteger
Response · 200
dataobjectrequired

The allocation, the credit note with its new unallocated_money, and the recomputed invoice.

metaobject
request_idstring

Error codes

AUTH_REQUIREDCREDIT_NOTE_ALLOCATION_ALREADY_REVERSEDCREDIT_NOTE_CHANGEDIDEMPOTENCY_KEY_IN_PROGRESSIDEMPOTENCY_KEY_REUSEDINSUFFICIENT_SCOPEINVALID_EXPECTED_VERSIONINVALID_REQUESTINVOICE_PAYMENT_RESOLVINGRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/credit-notes/{credit_note_id}/allocations/{credit_note_allocation_id}/reverse \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 0
  }'

Issue credit note#

POST/v1/credit-notes/{credit_note_id}/issueIdempotentRequires scope: commerce.credit_notes.write

Issues a draft credit note. Assigns credit_note_number, freezes the lines, renders the PDF, and sets unallocated_money to the total. The over-credit check runs here rather than on line edits: across every issued credit note, an invoice line cannot be credited past its frozen value. Issuing does not change the invoice; allocating does.

Path parameters
credit_note_idstringrequired

Flint credit note ID.

Request body
expected_versioninteger
Response · 200
dataobjectrequired

A correction against an issued invoice. Credit notes reduce what is owed; refunds return what was already collected.

metaobject
request_idstring

Error codes

AUTH_REQUIREDCREDIT_NOTE_AMOUNT_EXCEEDS_CREDITABLECREDIT_NOTE_CHANGEDCREDIT_NOTE_ISSUE_IN_PROGRESSCREDIT_NOTE_NOT_DRAFTIDEMPOTENCY_KEY_IN_PROGRESSIDEMPOTENCY_KEY_REUSEDINSUFFICIENT_SCOPEINVALID_CREDIT_NOTE_LINEINVALID_EXPECTED_VERSIONINVALID_REQUESTINVOICE_NOT_CREDITABLERATE_LIMIT_EXCEEDEDREQUEST_TIMEOUTRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/credit-notes/{credit_note_id}/issue \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 0
  }'

Download credit note PDF#

GET/v1/credit-notes/{credit_note_id}/pdfRequires scope: commerce.credit_notes.read or commerce.credit_notes.write

Returns the credit note document as application/pdf rather than a JSON envelope. The PDF exists from issue onward and carries your branding, the credited lines, and the invoice it corrects.

Path parameters
credit_note_idstringrequired

Flint credit note ID.

Error codes

AUTH_REQUIREDCREDIT_NOTE_NOT_ISSUEDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/credit-notes/{credit_note_id}/pdf \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Void credit note#

POST/v1/credit-notes/{credit_note_id}/voidIdempotentRequires scope: commerce.credit_notes.write

Voids an issued credit note. Every allocation has to be reversed first. Void is terminal, and an invoice cannot be voided while an issued credit note stands against it.

Path parameters
credit_note_idstringrequired

Flint credit note ID.

Request body
expected_versioninteger
Response · 200
dataobjectrequired

A correction against an issued invoice. Credit notes reduce what is owed; refunds return what was already collected.

metaobject
request_idstring

Error codes

AUTH_REQUIREDCREDIT_NOTE_CHANGEDCREDIT_NOTE_HAS_ALLOCATIONSCREDIT_NOTE_NOT_ISSUEDIDEMPOTENCY_KEY_IN_PROGRESSIDEMPOTENCY_KEY_REUSEDINSUFFICIENT_SCOPEINVALID_EXPECTED_VERSIONINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/credit-notes/{credit_note_id}/void \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 0
  }'
Rate this doc