Client credit

Client credit is money you owe a client that you keep on their account instead of paying it back. It comes from a credit note on an invoice that was already paid: rather than refunding, you choose to keep the amount as credit and use it on the client's next invoice. This suits regular clients who would rather have the amount taken off their next bill than wait for a refund.

When client credit is created

A credit note reduces what a client owes on an invoice. What happens next depends on whether the invoice was already paid:

If you choose refund, the money goes back through the payment rail when it supports refunds (Stripe), or you record the refund manually (bank transfer and other rails). See Refunds.

If you choose keep as client credit, the credited amount is added to the client's credit balance in the credit note's currency. The credit note itself stays on record with its own number (for example CN-2027-0001) and is linked to the original invoice.

How the balance works

• Each client has one credit balance per currency. Credit in EUR can only be applied to EUR invoices; credit in USD only to USD invoices. There is no automatic currency conversion.
• The balance can never go below zero.
• Every change is written as an entry in an append-only history with a reason: credit_note (credit added), applied (used on an invoice) or refunded (paid back later). Entries are never edited or deleted, so you can always see how a balance was built.
• The balance and its entries are updated together in one step, so they always agree.

Apply credit to an invoice

Credit does not apply itself silently. You apply it to an invoice, which reduces that invoice's balance by the credited amount.

An invoice's balance is always its total minus what has been paid minus what has been credited. Applying client credit counts toward the credited part, so an invoice covered fully by credit and payments shows a zero balance.

Through the API

Creating a credit note is destructive (it changes what a client owes), so the call needs "confirm": true. Without it you get confirmation_required and a preview of what would happen. Send an Idempotency-Key so a retry never creates a second credit note.

curl -X POST "https://api.freeinvoiceautomation.com/v1/documents/0193f2b4-5a6b-7c8d-9e0f-1a2b3c4d5e6f/credit-notes" \
  -H "Authorization: Bearer $FIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cn-inv-0042-credit" \
  -d '{
    "amount_minor": "20000",
    "settlement": "client_credit",
    "confirm": true
  }'

{
  "data": [
    { "currency": "EUR", "balance_minor": "20000" }
  ]
}

Then apply it to the next invoice:

curl -X POST "https://api.freeinvoiceautomation.com/v1/documents/0193f2b6-1a2b-7c3d-8e4f-5a6b7c8d9e0f/apply-credit" \
  -H "Authorization: Bearer $FIA_API_KEY" \
  -H "Idempotency-Key: apply-credit-inv-0051"

Over MCP, create_credit_note is a destructive tool: your assistant shows you what it is about to do and needs your confirmation. Applying credit is not on the MCP tool list; use the app, the API or the CLI (freeinvoiceautomation doc apply-credit, from the week of 25 January 2027; command names are proposed).

What the client sees

• The credit note is a document the client can open and download, marked as a credit note on the PDF, with its own number and a link to the invoice it credits.
• When credit is applied, the next invoice's pay page shows the reduced amount due.
• From January 2027, the client portal shows the client's documents, credit notes and a statement, so they can follow how credit was added and used.

Rules and edge cases

• Only paid invoices create credit. On an unpaid invoice, a credit note simply lowers the balance.
• A credit note cannot exceed what can be credited. If you try, you get credit_exceeds_balance.
• Voided invoices. An invoice with recorded payments cannot be voided; you issue a credit note instead. A voided invoice accepts no further actions, including applied credit (document_voided).
• Same currency only. Credit is held per currency; apply it to an invoice in that currency.
• Credit can be refunded later. A refunded entry records credit that you later pay back to the client.
• Store refunds. Refunds from the Shopify app and WordPress plugin create credit notes automatically and are recorded as refunded outside our system, not as client credit.

Permissions

Errors

Related