What Is Account Credit?
Account credit is money held on a client's account that is automatically applied to future invoices. It reduces the amount the client needs to pay and, if it covers the full invoice, marks the invoice paid without any gateway payment.
Credit is stored as a BIGINT cents value per client in client_credits. It is separate from payment methods and cannot be "withdrawn" — it can only be applied to invoices.
Sources of Credit
| Source | How it's added |
|---|---|
| Admin manually adds credit | Admin → Client → Credits → Add Credit |
| Refund issued as credit note | Refund dialog → choose "Credit Note" |
| Overpayment | Rare — if a payment exceeds the invoice total, the surplus becomes credit |
The most common source is admin-added credit (for goodwill adjustments, promotions, or service credits) and credit notes from refunds.
How Auto-Apply Works
Commerce applies available credit automatically in two places:
1. When a new invoice is generated
When commerce:generate-renewal-invoices creates a renewal invoice, it checks the client's credit balance. If credit is available:
- The credit amount is deducted from the invoice total
- A credit application record is written to
client_credit_applications - If credit fully covers the invoice, the invoice is immediately set to
paid— no email payment link is sent - If credit partially covers the invoice, the remaining balance is shown when the client opens Pay Now
2. When the client opens the Pay Now page
When a client visits the payment page for an unpaid invoice, Commerce re-checks the credit balance and applies any remaining credit before rendering the gateway form. The page shows:
Invoice total: $100.00
Account credit applied: -$25.00
────────
Amount due: $75.00
[!IMPORTANT] Credit auto-apply is not optional. Clients always have their available credit applied. This is by design — credit should be consumed before new payments are taken.
Adding Credit Manually
- Go to Admin → Clients → [client]
- Click the Credits tab
- Click Add Credit
- Enter the amount (in the client's currency) and an internal note
- Click Save
The credit is available immediately on the next invoice the client pays (or the next renewal invoice generated).
[!TIP] Use the note field to track why credit was added — for example: "Service outage compensation April 2026" or "Promotional discount Q2". These notes appear in the credit history and help with accounting.
Viewing Credit History
Admin view:
Go to Admin → Clients → [client] → Credits tab. The table shows every credit transaction:
| Column | Description |
|---|---|
| Date | When the transaction occurred |
| Type | addition, application, or refund |
| Amount | Positive (added) or negative (used) |
| Invoice | Invoice number the credit was applied to (if applicable) |
| Note | Admin note or system description |
| Running balance | Credit balance after this transaction |
Client view:
Clients see their current credit balance on their dashboard (e.g. "Account credit: $25.00"). A full transaction history is available under Client → Billing → Account Credit.
Credit and Currency
Credit is stored per-currency. If a client has credit in USD and receives a EUR invoice, the credit does not auto-apply across currencies. Ensure credit is added in the same currency as the client's invoices.
[!WARNING] Multi-currency credit matching is strict — a $50 USD credit will not apply to a €50 EUR invoice even if the exchange rate makes them equivalent. Add credit in the correct currency for the client's invoices.