Skip to content
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.

Use a credit note when the invoice itself overstated what the buyer owes and you want a numbered document that records the correction. Other corrections have their own tools:

SituationUse
The invoice is still a draftEdit the invoice
Goods come back and you want receiving, restocking, and the refund handledA return. Returns and credit notes share each invoice line's remaining value.
Money goes back, but the invoice was rightA refund on the order

The Credit notes guide walks through each flow with full requests and responses.

Lifecycle#

You create a note against an invoice that has been issued and isn't void. The note starts as a draft and moves forward only.

Credit note statusStartFinal
  • draft on edit: lines, reason, and memo can change
  • draft moves to issued on issue
  • issued on allocate, reverse, or refund: the credit moves; the document doesn't change
  • issued moves to void on void
status on credit note
Final values do not change again
  • draft
    Editable. It has no credit_note_number, no PDF, and reserves no credit. Drafts can't be deleted or voided; to abandon one, leave it or empty it with PATCH and "line_items": [].
  • issued
    Numbered and frozen. Issuing assigns credit_note_number, stamps issued_at, copies the tax identities from the invoice, and renders the PDF. Lines and totals never change again; only the money fields move as you allocate or refund.
  • voidFinal
    Retired. Its corrections stop counting against the invoice lines, and available_money is 0. Reverse every allocation first. A note with a pending or succeeded refund can't be voided.

An issued note blocks voiding its invoice. Void the note before you void the invoice.

Where the credit goes#

Issuing a note on its own moves no money and leaves the invoice balance unchanged. The body of POST /v1/credit-notes/{credit_note_id}/issue decides what happens to the credit:

Issue bodyEffectInvoice status it needs
EmptyIssues the note onlyAny issued, non-void status
allocationIssues the note and applies credit to the balance. If the allocation is refused, the note stays a draft.open or partially_paid
refundIssues the note and refunds credit to the invoice's original payments. refund.reason is required.paid

allocation and refund can't be combined in one issue request (400 INVALID_REQUEST, param: allocation). Leave out their amount_money to use as much credit as fits: an allocation applies the smaller of the note's credit and the invoice's outstanding balance, and a refund refunds all of the note's available credit. The response returns the note at data.credit_note and the invoice after issue at data.invoice, plus data.credit_note_allocation or data.refund when you asked for one.

From a note that's already issued, POST /v1/credit-notes/{credit_note_id}/allocations applies credit and requires amount_money, and POST /v1/credit-notes/{credit_note_id}/refunds refunds it, with amount_money optional. The refund call returns the Refund at data.

cURL
curl -X POST https://api.withflintpay.com/v1/credit-notes/cn_01KF4B2C6D8E0F2G4H6J8K0M2N/issue \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: issue-cn-inv-1042-1" \
  -d '{"expected_version": 1, "allocation": {}}'

Allocations lower the invoice's outstanding_money and raise its credit_money. One that takes the balance to zero closes the invoice: it becomes paid when positive net collection remains, and credited when there is none. Allocations are append-only. Reversing one keeps its record with reversed_at set, returns the amount to the note, and reopens that much of the balance. An invoice that the allocation closed goes back to open or partially_paid. Credit never pays an order's unpaid tip or late fees; see Limits on an allocation.

Refunds go back to the payments collected through Flint on the invoice, not to manually recorded payments. The invoice stays paid, and its refunded_money and refund_status track the refund. Each refund carries credit_note_id and invoice_id, and the note's latest_refund_status follows the most recent one.

The note's money fields#

Five fields track where an issued note's value sits, and they always balance: total_money = allocated_money + pending_refund_money + refunded_money + available_money. A reversed allocation moves its amount from allocated_money back to available_money. A refund holds its amount in pending_refund_money until it resolves, then moves it to refunded_money if it succeeds, or back to available_money if it fails or is canceled.

For example, a $120.00 note applied $80.00 to the invoice. The buyer paid the rest, and a $25.00 refund from the note hasn't resolved yet:

Where a $120.00 credit note's value sits
  • Allocatedallocated_money
    $80.00
  • Pending refundpending_refund_money
    $25.00
  • Refundedrefunded_money
    $0.00
  • Availableavailable_money
    $15.00
  • Totaltotal_money
    $120.00

How line amounts are calculated#

Each line names one invoice_line_item_id, at most once per note, and a correction of type quantity (whole units) or amount (a billed value in the invoice currency). Flint calculates from the invoice line as it was frozen at issue, so later catalog prices and tax settings play no part. Credit notes correct merchandise lines only, not charges, tips, or late fees.

  • Shared remaining value. Each invoice line has one remaining pool of billed value, units, discount, and tax. Issued, non-void credit notes and committed return lines draw from it, so together they never exceed what the line billed. Drafts reserve nothing. Allocations, reversals, and refunds don't change the pool; voiding a note gives its corrections back.
  • Proportional tax and discount. A correction takes its proportional share of the line's remaining tax and discount, each rounded half up in minor units, and subtotal_money balances the line. An amount correction uses up value without using up units, so later quantity corrections divide the reduced value.
  • The source line's tax mode. With added tax, total_money = subtotal_money - discount_money + tax_money. With included tax, total_money = subtotal_money - discount_money. Either way, the amount before tax is total_money - tax_money.
  • Round-trip lines. Every read line returns the correction that produced it, in the shape draft writes accept. To replace a draft's lines, send them back in PATCH line_items, each with its credit_note_line_item_id.

See How Flint calculates each line for worked rounding examples and the line errors.

Retries and versions#

CallsIdempotency-Key
Issue, allocate, refundRequired. Flint keeps the key for as long as the call's effects exist.
Create, update, reverse, voidOptional. Flint keeps the key for 24 hours.

Retrying with the same key and body returns the original result, and a different body returns 409 IDEMPOTENCY_KEY_REUSED. To recover a lost response, list the note's allocations or refunds filtered by idempotency_key. An allocation made on issue has the key issue: followed by the issue request's key, so filter allocations by idempotency_key=issue:<your key>. A refund made on issue keeps your key as it is.

Every note has a version. Issue, allocate, reverse, refund, and void accept an optional expected_version, and replacing a draft's line_items requires it. A stale version returns 409 VERSION_CONFLICT with details[0].current_version. Allocations, reversals, and refund outcomes all move the version, so read it from the latest response.

Because drafts reserve nothing, another note or return can use up the same invoice lines before you issue. Issue never changes the amounts the draft previewed:

  • If the stored corrections still fit but their amounts would change, issue returns 409 VERSION_CONFLICT with the credit note's current_version. Read the note and send the request again with a new Idempotency-Key.
  • If they no longer fit, issue returns 409 ACTION_NOT_ALLOWED with reason not_offered.

For either, refresh the draft: retrieve it, resend its corrections with PATCH and the current expected_version, review the new amounts, and issue with a new key. Errors to handle lists every error and reason these endpoints return.

Permissions#

CallsScopes
Get, list, list allocations, download the PDFcommerce.credit_notes.read or commerce.credit_notes.write
Create, update, issue, allocate, reverse, voidcommerce.credit_notes.write
Issue with refund, or refund an issued notecommerce.credit_notes.write and commerce.refunds.write
List a note's refundscommerce.credit_notes.read and commerce.refunds.read, or the matching write scopes
Add expand=invoiceCredit note read access and commerce.invoices.read. Without invoice access, the request returns 403 INSUFFICIENT_SCOPE with param: expand.

Find credit notes#

GET /v1/credit-notes returns notes newest first. Filters combine with AND and apply before pagination. status and reason take several values, repeated or comma-separated, and match any of them. customer_id takes one valid customer ID and matches notes whose source invoice currently belongs to that customer, so you can find a customer's notes across all their invoices.

Add expand=invoice to the list or to GET /v1/credit-notes/{credit_note_id} to include the source invoice's summary as invoice on each note. invoice is the only expansion. Adding or dropping expand between pages keeps the page token valid.

cURL
curl -G https://api.withflintpay.com/v1/credit-notes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "customer_id=cus_01KF3Q7A1B3C5D7E9F1G3H5J7K" \
  --data-urlencode "reason=returned_goods,billing_error" \
  --data-urlencode "expand=invoice"

Buyers see notes through /v1/me/invoices/{invoice_id}/credit-notes, with a customer session or the invoice's access token. Those routes return issued and void notes only, leave out available_money, allocated_money, merchant_id, external_reference_id, and version, and don't accept filters or expand. See Show credit notes to the buyer.

Webhooks#

An allocation that closes the invoice also sends invoice.paid or invoice.credited, and a reversal that reopens it sends invoice.reopened. See Handle webhook events for the order they arrive in.

Credit notesCreate, issue, allocate, refund, and void a credit note, with full examples.InvoicingThe invoice a credit note corrects, and its balance fields.RefundsRefund statuses, reasons, and events, including refunds made from a credit note.

The Credit note object#

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

Returned by GET /v1/credit-notes/{credit_note_id} and carried by the endpoints below.

Attributes

allocated_moneyobjectRequired

Credit applied to the invoice, net of reversed allocations.

available_moneyobjectRequired

Credit available to allocate or refund. Zero on draft and void notes. On issued notes, total_money equals allocated_money plus pending_refund_money plus refunded_money plus available_money.

buyer_tax_identityobject or nullRequired

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

created_atstringRequired

When the credit note was created.

credit_note_idstringRequired

Unique identifier of the credit note.

credit_note_numberstring

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

external_reference_idstring or nullRequired

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

invoiceobject

Summary of the source invoice. Returned only with expand=invoice.

invoice_idstringRequired

The invoice this credit note corrects.

issued_atstring

When the credit note was issued. Absent on a draft.

latest_refund_statusenum

Status of the most recent refund linked to this credit note. Absent when no refund has been requested.

  • pending
  • succeeded
  • partially_succeeded
  • failed
line_itemsarray of objectRequired

Itemized corrections against frozen invoice lines. Amount and quantity corrections share each source line's remaining value, discount, and tax across issued, non-void credit notes. Drafts reserve no credit.

memostring or nullRequired

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

merchant_idstringRequired

The merchant that owns the credit note.

pending_refund_moneyobjectRequired

Credit reserved by linked refunds that have not resolved yet. Released if a refund fails or is canceled.

reasonenumRequired

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

  • returned_goods
  • order_adjustment
  • billing_error
  • goodwill
  • other
refunded_moneyobjectRequired

Credit consumed by linked refunds that succeeded.

seller_tax_identityobject or nullRequired

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.

updated_atstringRequired

When the credit note last changed.

versionintegerRequired

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

voided_atstring

When the credit note was voided. Absent unless it is void.

JSON
{
  "allocated_money": {
    "amount": 0,
    "currency": "USD"
  },
  "available_money": {
    "amount": 0,
    "currency": "USD"
  },
  "buyer_tax_identity": null,
  "created_at": "2026-03-21T15:03:00Z",
  "credit_note_id": "cn_01KEZF7C001MHR3WBEWAFG5DTD",
  "external_reference_id": null,
  "invoice_id": "inv_01J00000000000000000000000",
  "line_items": [],
  "memo": null,
  "merchant_id": "mer_01J00000000000000000000000",
  "pending_refund_money": {
    "amount": 0,
    "currency": "USD"
  },
  "reason": "billing_error",
  "refunded_money": {
    "amount": 0,
    "currency": "USD"
  },
  "seller_tax_identity": null,
  "status": "draft",
  "total_money": {
    "amount": 0,
    "currency": "USD"
  },
  "updated_at": "2026-03-21T15:04:05Z",
  "version": 1
}

List credit notes#

GET/v1/credit-notes

Requires scope commerce.credit_notes.read or commerce.credit_notes.write

Rate limit: read

Returns credit notes for the authenticated merchant, newest first. Filter by invoice_id to see everything credited against one invoice. Default order: created_at descending, then credit_note_id descending.

Query parameters

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.

created_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

invoice_idstring

Filter by invoice.

customer_idstring

Filter by the source invoice's current customer_id.

reasonarray of enum

Filter by credit note reason. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • returned_goods
  • order_adjustment
  • billing_error
  • goodwill
  • other
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 cn_01.

statusarray of enum

Filter by status. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • draft
  • issued
  • void
expandarray of enum

Include related objects in the response. Supported expansions: invoice. Include the requested related resources using scoped batch reads for this page. Each relationship requires its existing target read scopes. Expansion changes the representation without changing pagination tokens. Limits: at most 10 unique expand paths per request.

  • invoice

Response · 200

A page of credit notes.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

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

A page of credit notes.

JSON
{
  "data": [
    {
      "allocated_money": {
        "amount": 0,
        "currency": "USD"
      },
      "available_money": {
        "amount": 0,
        "currency": "USD"
      },
      "buyer_tax_identity": null,
      "created_at": "2026-03-21T15:03:00Z",
      "credit_note_id": "cn_01KEZF7C001MHR3WBEWAFG5DTD",
      "external_reference_id": null,
      "invoice_id": "inv_01J00000000000000000000000",
      "line_items": [],
      "memo": null,
      "merchant_id": "mer_01J00000000000000000000000",
      "pending_refund_money": {
        "amount": 0,
        "currency": "USD"
      },
      "reason": "billing_error",
      "refunded_money": {
        "amount": 0,
        "currency": "USD"
      },
      "seller_tax_identity": null,
      "status": "draft",
      "total_money": {
        "amount": 0,
        "currency": "USD"
      },
      "updated_at": "2026-03-21T15:04:05Z",
      "version": 1
    }
  ],
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Create credit note#

POST/v1/credit-notesIdempotent

Requires scope commerce.credit_notes.write

Rate limit: write

Creates a draft credit note against an invoice that has been issued and not voided. Include line_items for initial corrections or omit them for an empty draft. The draft uses frozen invoice economics and the remaining pools shared by issued, non-void notes. Drafts reserve no credit. It receives a credit note number when issued.

Request body

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.

line_itemsarray of object

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

memostring

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

reasonenumRequired

Why the invoice is being corrected: returned_goods, order_adjustment, billing_error, goodwill, or other. Shown on the credit note document.

  • returned_goods
  • order_adjustment
  • billing_error
  • goodwill
  • other

Response · 201

The created resource.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

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": "inv_01J00000000000000000000000",
    "line_items": [
      {
        "correction": {
          "quantity": 1,
          "type": "quantity"
        },
        "invoice_line_item_id": "invli_01KEZF7C00EEHJQZDWNCY60NBP"
      }
    ],
    "reason": "returned_goods"
  }'

Get credit note#

GET/v1/credit-notes/{credit_note_id}

Requires scope commerce.credit_notes.read or commerce.credit_notes.write

Rate limit: read

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

Path parameters

credit_note_idstringRequired

Flint credit note ID.

Query parameters

expandarray of enum

Include related objects in the response. Supported expansions: invoice. Include the source invoice summary with expand=invoice. Requires commerce.credit_notes.read and commerce.invoices.read. Limits: at most 10 unique expand paths per request.

  • invoice

Response · 200

The credit note.

Same response as Create credit note.

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

The credit note.

JSON
{
  "data": {
    "allocated_money": {
      "amount": 0,
      "currency": "USD"
    },
    "available_money": {
      "amount": 0,
      "currency": "USD"
    },
    "buyer_tax_identity": null,
    "created_at": "2026-03-21T15:03:00Z",
    "credit_note_id": "cn_01KEZF7C001MHR3WBEWAFG5DTD",
    "external_reference_id": null,
    "invoice_id": "inv_01J00000000000000000000000",
    "line_items": [],
    "memo": null,
    "merchant_id": "mer_01J00000000000000000000000",
    "pending_refund_money": {
      "amount": 0,
      "currency": "USD"
    },
    "reason": "billing_error",
    "refunded_money": {
      "amount": 0,
      "currency": "USD"
    },
    "seller_tax_identity": null,
    "status": "draft",
    "total_money": {
      "amount": 0,
      "currency": "USD"
    },
    "updated_at": "2026-03-21T15:04:05Z",
    "version": 1
  },
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Update credit note#

PATCH/v1/credit-notes/{credit_note_id}Idempotent

Requires scope commerce.credit_notes.write

Rate limit: write

Updates draft credit note fields and corrections atomically. Omitted fields are unchanged, a null memo clears it, and line_items requires expected_version. Replacing lines recalculates their amounts from current remaining creditable pools. Scalar edits preserve stored line values. Issued and void credit notes are frozen.

Path parameters

credit_note_idstringRequired

Flint credit note ID.

Request body

expected_versioninteger

Credit note version last read. Required when line_items is present. Required when any of these fields is present: line_items.

external_reference_idstring or null

Caller-owned identifier for this resource in an external system. Send null to clear it.

line_itemsarray of object

Full replacement of the draft's owned line collection; requires expected_version. Recalculates corrections from current remaining creditable pools. After VERSION_CONFLICT, replace the existing corrections using current_version as expected_version, review the new amounts, and issue again. Scalar memo or reason changes do not reprice lines.

memostring or null

Send null to clear it.

reasonenum

Why the invoice is being corrected: returned_goods, order_adjustment, billing_error, goodwill, or other. Cannot be null; omit it to keep the current reason.

  • returned_goods
  • order_adjustment
  • billing_error
  • goodwill
  • other

Response · 200

The updated credit note.

Same response as Create credit note.

curl -X PATCH https://api.withflintpay.com/v1/credit-notes/cn_01KEZF7C00N1TRRCVDNY8S471H \
  -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": 1,
    "line_items": [
      {
        "correction": {
          "quantity": 1,
          "type": "quantity"
        },
        "invoice_line_item_id": "invli_01KEZF7C00EEHJQZDWNCY60NBP"
      }
    ],
    "memo": "Credit one returned unit."
  }'

List credit note allocations#

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

Requires scope commerce.credit_notes.read or commerce.credit_notes.write

Rate limit: read

Returns every allocation made from a credit note, including reversed ones. Filter by idempotency_key to find the allocation a given request produced. Default order: allocated_at descending, then credit_note_allocation_id descending.

Path parameters

credit_note_idstringRequired

Flint credit note ID.

Query parameters

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.

idempotency_keystring

Filter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns current authorized resources, not the recorded response. A pending resource does not prove that the operation succeeded, and an empty list does not prove that it had no effect.

Response · 200

A page of allocations.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

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

A page of allocations.

JSON
{
  "data": [
    {
      "allocated_at": "2026-03-22T12:01:00Z",
      "amount_money": {
        "amount": 500,
        "currency": "USD"
      },
      "credit_note_allocation_id": "cna_01KEZF7C0054N70FZ2YY47QE7W",
      "credit_note_id": "cn_01KEZF7C001MHR3WBEWAFG5DTD",
      "idempotency_key": "credit-allocation-1842",
      "invoice_id": "inv_01J00000000000000000000000"
    }
  ],
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Allocate credit note#

POST/v1/credit-notes/{credit_note_id}/allocationsKey required

Requires scope commerce.credit_notes.write

Rate limit: write

Applies credit from an issued credit note to its invoice, reducing outstanding_money. The amount cannot exceed the credit note's available_money or the invoice's outstanding balance. Closing the balance with credit sets the invoice to paid when positive net collection remains, or credited when there is no positive net collection. 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 available_money or the invoice's outstanding balance.

expected_versioninteger

Credit note version last read. Optional; a stale version returns VERSION_CONFLICT.

Response · 201

The created resource.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/credit-notes/cn_01KEZF7C00N1TRRCVDNY8S471H/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": 500,
      "currency": "USD"
    },
    "expected_version": 2
  }'

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

Rate limit: read

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

The allocation.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

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

The allocation.

JSON
{
  "data": {
    "allocated_at": "2026-03-22T12:01:00Z",
    "amount_money": {
      "amount": 500,
      "currency": "USD"
    },
    "credit_note_allocation_id": "cna_01KEZF7C0054N70FZ2YY47QE7W",
    "credit_note_id": "cn_01KEZF7C001MHR3WBEWAFG5DTD",
    "idempotency_key": "credit-allocation-1842",
    "invoice_id": "inv_01J00000000000000000000000"
  },
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Reverse credit note allocation#

POST/v1/credit-notes/{credit_note_id}/allocations/{credit_note_allocation_id}/reverseIdempotent

Requires scope commerce.credit_notes.write

Rate limit: 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. Reversing credit on a paid invoice that also has collected payments moves it to partially_paid.

Path parameters

credit_note_idstringRequired

Flint credit note ID.

credit_note_allocation_idstringRequired

Flint credit note allocation ID.

Request body

expected_versioninteger

Version last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.

Response · 200

The updated resource.

Same response as Allocate credit note.

curl -X POST https://api.withflintpay.com/v1/credit-notes/cn_01KEZF7C00N1TRRCVDNY8S471H/allocations/cna_01KEZF7C00EH6DMS9BD8F72CMA/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": 3
  }'

Issue credit note#

POST/v1/credit-notes/{credit_note_id}/issueKey required

Requires scope commerce.credit_notes.write

Rate limit: external_provider_action

Issues a draft credit note and freezes its number, lines, and totals. Provide allocation to issue and apply credit to its invoice atomically, or refund to initiate a linked refund on a paid invoice. Allocation and refund cannot be combined. Omit allocation.amount_money to apply the smaller of the credit available after issue and the invoice's outstanding balance. An explicit amount must be positive, use the invoice's currency, and fit both balances. The result includes credit_note_allocation when allocation is requested. Idempotency-Key is required and is retained for as long as the issue's effects exist, scoped to merchant, environment, credit note, and key. Reuse the key with the identical request to recover the original credit note and allocation. Recover an allocation after a lost response by listing this note's allocations with idempotency_key=issue:<issue key>. For refunds, list this note's refunds filtered by the original idempotency_key. A pending refund is accepted but has not completed. Without allocation or refund, issuance leaves the invoice balance unchanged. Issue validates the stored preview against current shared creditable pools. A fitting correction whose preview changed fails with `VERSION_CONFLICT`, which includes the credit note and `current_version`: replace its existing corrections with PATCH using the current expected_version, review the recalculated amounts, and issue again. A stored correction exceeding the remaining pool fails with `ACTION_NOT_ALLOWED` and reason `not_offered`. Update the draft lines before issuing again. Affected historical tax allocations fail with `ACTION_NOT_ALLOWED` and reason `credit_note_tax_reconciliation_required`.

Path parameters

credit_note_idstringRequired

Flint credit note ID.

Request body

allocationobject

Issue the credit note and apply credit to its invoice atomically. If the allocation fails, the note stays a draft. Omit amount_money to apply the smaller of the credit available after issue and the invoice's outstanding balance. Cannot be combined with refund.

expected_versioninteger

Credit note version last read. Optional; a stale version returns VERSION_CONFLICT.

refundobject

Create a linked refund when the credit note is issued. Requires both credit-note and refund write permissions and a paid invoice. Cannot be combined with allocation.

Response · 200

The updated credit note.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/credit-notes/cn_01KEZF7C00N1TRRCVDNY8S471H/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": 1
  }'

Download credit note PDF#

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

Requires scope commerce.credit_notes.read or commerce.credit_notes.write

Rate limit: read

Returns the credit note document as application/pdf rather than a JSON envelope. The PDF exists from issue onward and shows the credited lines, totals, and the invoice it corrects. It uses your current branding, so a later download can differ in logo or colors, but not in content.

Path parameters

credit_note_idstringRequired

Flint credit note ID.

Response · 200

A PDF document.

Content type application/pdf

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

A PDF document.

Returns application/pdf.

List credit note refunds#

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

Requires scopes commerce.credit_notes.read (or the matching write scope) and commerce.refunds.read (or the matching write scope)

Rate limit: read

Lists linked refunds, including failed attempts, newest first. Filter by idempotency_key to recover a refund after a lost response. Default order: time each refund was applied to the credit note (descending), then refund_id descending.

Path parameters

credit_note_idstringRequired

Flint credit note ID.

Query parameters

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque next_page_token from the previous response. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An invalid, expired, or mismatched token returns a validation error.

idempotency_keystring

Filter by the original Idempotency-Key, after trimming surrounding whitespace. Matching is exact and case-sensitive. Returns current authorized resources, not the recorded response. A pending resource does not prove that the operation succeeded, and an empty list does not prove that it had no effect.

Response · 200

A page of refunds.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

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

A page of refunds.

JSON
{
  "data": [
    {
      "amount_money": {
        "amount": 500,
        "currency": "USD"
      },
      "created_at": "2026-03-22T12:01:00Z",
      "credit_note_id": "cn_01KEZF7C001MHR3WBEWAFG5DTD",
      "customer_id": "cus_01J00000000000000000000000",
      "invoice_id": "inv_01J00000000000000000000000",
      "merchant_id": "mer_01J00000000000000000000000",
      "order_id": "ord_01J00000000000000000000000",
      "payment_intent_id": "pi_4P0PGPVVCQ97Z18QNXAV528WCG",
      "reason": "requested_by_customer",
      "refund_id": "ref_01KEZF7C00H2GAMWD73WZ7K81W",
      "refunded_tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "status": "pending",
      "updated_at": "2026-03-22T12:01:00Z",
      "version": 1
    }
  ],
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Refund credit note#

POST/v1/credit-notes/{credit_note_id}/refundsKey required

Requires scopes commerce.credit_notes.write (or the matching write scope) and commerce.refunds.write (or the matching write scope)

Rate limit: external_provider_action

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

Credit to refund. Omit to refund all available credit, which Flint resolves once when it accepts the request.

expected_versioninteger

Credit note version last read. Optional; a stale version returns VERSION_CONFLICT.

reasonenumRequired

Why the refund is being made.

  • 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

Optional note explaining the refund.

Response · 201

The created resource.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/credit-notes/cn_01KEZF7C00N1TRRCVDNY8S471H/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 '{
    "amount_money": {
      "amount": 500,
      "currency": "USD"
    },
    "expected_version": 2,
    "reason": "requested_by_customer"
  }'

Void credit note#

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

Requires scope commerce.credit_notes.write

Rate limit: write

Voids an issued credit note. Reverse every allocation first. A credit note with a pending or succeeded refund can't be voided. Blockers fail with `RESOURCE_IN_USE`, and `details[0].blocking_resources` lists the allocations and refunds. 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

Version last read from the resource returned in `data` (the primary resource for a result object). The write fails with `VERSION_CONFLICT` if it has changed. Requiredness depends on the operation and fields being changed.

Response · 200

The updated resource.

Same response as Create credit note.

curl -X POST https://api.withflintpay.com/v1/credit-notes/cn_01KEZF7C00N1TRRCVDNY8S471H/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": 1
  }'

Was this helpful?