flintDocs

Credit notes

A credit note documents a correction to an issued invoice. Each note belongs to one invoice and preserves the discount and tax share of its frozen lines. Allocate its credit against an outstanding balance, or create a linked refund on a paid invoice.

A note starts as a draft you can edit freely. Issuing it assigns credit_note_number, freezes the lines, and renders the PDF. Issuing without refund does not move money. 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 and refund creation require a caller-chosen Idempotency-Key. Issue also requires it when refund is provided. Refund command identities are retained for the lifetime of their financial effects. Use the credit-note refunds list with idempotency_key to recover a lost response.

A refund can cover all or part of the available credit. pending_refund_money reserves unresolved amounts; refunded_money records successful amounts. Both reduce unallocated_money. Refunds leave the invoice paid and preserve the issued document. Issue returns the credit note at data with an optional data.refund; refund creation returns the Refund resource at data.

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

The Credit note object#

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

Attributes

buyer_tax_identityobject or null

Identity frozen on the source invoice at issue. Later profile edits do not change this document.

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.

latest_refund_statusenum
  • pending
  • in_transit
  • succeeded
  • failed
  • requires_action
  • canceled
  • partially_succeeded
memostring

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

merchant_idstringRequired
pending_refund_moneyobjectRequired

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

reasonenumRequired

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

  • returned_goods
  • order_adjustment
  • billing_error
  • goodwill
  • other
refunded_moneyobjectRequired

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

seller_tax_identityobject or null

Identity frozen on the source invoice at issue. Later profile edits do not change this document.

statusenumRequired

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

  • draft
  • issued
  • void
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-notes

Requires 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. Text fields match any part of the value, and %, _ and \ are ordinary characters, not wildcards. IDs match from the start and need the type prefix, such as ord_01.

statusenum

Filter by status.

  • draft
  • issued
  • void

Response · 200

dataarray of objectRequired
metaobject
next_page_tokenstring
request_idstring
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-notesIdempotent

Requires 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_goods
  • order_adjustment
  • billing_error
  • goodwill
  • other

Response · 201

dataobjectRequired

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

metaobject
request_idstring
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
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}Idempotent

Requires 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_goods
  • order_adjustment
  • billing_error
  • goodwill
  • other

Response · 200

dataobjectRequired

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

metaobject
request_idstring
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}/allocations

Requires 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
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}/allocationsIdempotent

Requires 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
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
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}/reverseIdempotent

Requires 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
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}/issueIdempotent

Requires scope commerce.credit_notes.write

Issues a draft credit note and freezes its PDF. Optionally provide refund to initiate a linked refund on a paid invoice. With refund, Idempotency-Key is required and retained for the lifetime of the refund command, scoped to merchant, environment, credit note, and key. Reuse the key with the identical request to recover the original result. Use the credit note refunds list filtered by idempotency_key after a lost response. A pending refund is accepted, not completed. Without refund, issuance does not move money.

Path parameters

credit_note_idstringRequired

Flint credit note ID.

Request body

expected_versioninteger
refundobject

Response · 200

dataobjectRequired
metaobject
request_idstring
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,
    "refund": {
      "reason": "duplicate"
    }
  }'

Download credit note PDF#

GET/v1/credit-notes/{credit_note_id}/pdf

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

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

List credit note refunds#

GET/v1/credit-notes/{credit_note_id}/refunds

Requires scopes commerce.credit_notes.read and commerce.credit_notes.write and commerce.refunds.read and commerce.refunds.write

Lists linked refunds, including failed attempts, newest first. Filter by idempotency_key to recover a refund after a lost response.

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
curl https://api.withflintpay.com/v1/credit-notes/{credit_note_id}/refunds \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Refund credit note#

POST/v1/credit-notes/{credit_note_id}/refundsIdempotent

Requires scopes commerce.credit_notes.write and commerce.refunds.write

Creates a refund against an issued credit note on a paid invoice. Omit amount_money to refund all available credit. Refunds use the source invoice's original payments and do not reopen its balance. Idempotency-Key is required and retained for the lifetime of the refund command, scoped to merchant, environment, credit note, and key. Reusing it with another request conflicts. Recover a lost response by listing this note's refunds with idempotency_key. A failed remainder can be requested with a new key after its outcome is definitive.

Path parameters

credit_note_idstringRequired

Flint credit note ID.

Request body

amount_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

expected_versioninteger
reasonenumRequired
  • duplicate
  • fraudulent
  • requested_by_customer
  • defective_product
  • wrong_item_shipped
  • never_received
  • not_as_described
  • arrived_too_late
  • customer_changed_mind
  • better_price_found
  • accidental_order
  • other
reason_messagestring

Response · 201

dataobjectRequired
metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/credit-notes/{credit_note_id}/refunds \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "reason": "duplicate"
  }'

Void credit note#

POST/v1/credit-notes/{credit_note_id}/voidIdempotent

Requires 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
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
  }'

Was this helpful?