Credit Notes & Client Billing — Guide

Audience: MSP staff who issue and apply credits, organization admins who read their own billing position, and platform administrators who set credit limits.

What it is

A credit note is an accounts-receivable credit that reduces what a customer owes. Solidlio records each credit, lets MSP staff apply it against one or more invoices, keeps a per-invoice ledger of every application, and reflects the result in the customer’s balance, statements and transaction history.

Separately, Solidlio records credit lines — how much a client may owe at once and on what terms. Credit lines and credit notes are different things and are covered separately below.

Concepts

The three balances — read this first

Three modules in the API client are named “credit”. They are three unrelated tables, not three views of one balance. Nothing reconciles them against each other, and nothing is supposed to.

Two consequences you need to know:

• The MSP→client credit line is advisory. It is recorded, displayed and editable, and it is what an MSP tells a client their terms are. Adjust it by hand, or treat it as documentation of agreed terms.
• Only a credit note moves an invoice balance. A credit line never does.

Credit note

Credit note application

Each time a credit is applied to an invoice, Solidlio writes one application row:

Applications are reversed, never deleted. The database foreign keys are RESTRICT, so a credit note that has been applied cannot be deleted while its history exists. Reversed rows stay in place and are excluded from balance arithmetic.

Lifecycle

        QuickBooks credit-memo sync
                    │
                    ▼
                 ISSUED ──── apply (partial) ──► ISSUED   (remainingCredit reduced)
                    │                               │
                    │                               │ apply the remainder
                    ▼                               ▼
                 APPLIED  ◄─────────────────────────┘   (remainingCredit == 0)
                    │
                    │ reverse an application
                    ▼
                 ISSUED   (credit restored)

There is no PARTIALLY_APPLIED status. A partly-applied note stays ISSUED with a reduced remainingCredit; read remainingCredit, not status, to know what is left.

See §9.

Accounts and organizations

A managed client is a separate Account, not an organization inside the MSP’s account. Two different scopes follow from that, and mixing them up is a real failure mode:

Credit notes use billingScope: an MSP applying a credit for a client it services is a legitimate cross-account action. Client credit lines stay on accountScope, because a credit line is the providing MSP’s own commercial position and must not be visible to a co-managing MSP.

Roles and permissions

Role hierarchy: platform administrator > MSP administrator > MSP technician > organization administrator > power user > CUSTOMER`.

Two deliberate splits:

• Reading a credit note is not the same as applying one. An organization that has been granted a credit can see it — it is that customer’s own financial document. Writing off a receivable is the MSP’s decision, so POST /apply and POST /reverse carry a MSP technician floor inside the router while the three read routes are mounted at organization administrator.
• organization administrator, not unfloored. power user and CUSTOMER cannot read credit notes. All three reads are billingScoped regardless, so the floor changes who may ask, never which rows return.

Walkthroughs

Apply a credit note to an invoice (MSP staff)

Credit notes arrive from the QuickBooks credit-memo sync. Once present:

2. Pick a target invoice belonging to the same organization and the same currency.
3. The response reports both sides: appliedAmount, creditNoteRemaining, creditNoteStatus, invoicePaidAmount, invoiceBalance, invoiceStatus, and the applicationId you need to reverse it later.

A partial application leaves the note ISSUED with a reduced remainingCredit, so you can apply the rest to a different invoice. Each application is recorded separately.

Reverse an application

3. The credit returns to the note (an exhausted APPLIED note becomes ISSUED again), and the invoice’s balance is restored.

A VOID note stays VOID after a reversal — voiding is a deliberate act and a reversal must not undo it. Reversing twice returns 409 ALREADY_REVERSED.

Set up a client credit line (MSP staff)

1. Open the client. If no credit line exists, the panel shows Set Up Credit Account.
2. That creates the account with a zero limit and Net 30 terms.
3. Set Credit Limit, Net Terms, Payment History and Credit Status, then save.

Utilization shown on the panel is derived as creditLimit − availableCredit. Because nothing draws the line down automatically (§2.1), that figure only moves when someone edits it.

Read your billing position (organization admin)

• Billing shows the credit line, outstanding and overdue balances, the next invoice due, and auto-pay settings.
• Billing Statements → Monthly Statements shows the reconciling series described in §5.
• Billing Statements → Transaction History shows invoices, payments and credit notes in one feed. Anything that reduces the balance carries a negative amount.

Make escalation work billable (platform admin)

1. The assignment must be COMPLETED or PENDING_REVIEW and not already finalized.
2. Press Finalize Billing.
3. Solidlio stamps finalAmountCents on the assignment and creates two records: a PlatformFee charged to the requesting account, and a ServiceOrder carrying the revenue.

Finalizing twice returns 409 with Billing has already been finalized for this assignment — it will not charge twice.

Statements: how they reconcile

closingBalance = openingBalance + charges − payments − credits

Two details that make the series tie out end to end rather than starting from an implied zero:

• Pre-window seed. The oldest month’s openingBalance is computed from every invoice, payment and credit note dated before the requested window, not assumed to be zero.
• Chaining. Months are computed oldest-first so each opening is literally the previous closing, then returned newest-first for display.

Months are grouped on issueDate, not row-creation time: an invoice drafted in March and issued in April belongs on the April statement, which is the one the customer is asked to pay.

?months= is clamped to 1–24 (default 12) at both ends.

How an invoice’s paid amount is calculated

Invoice.paidAmount is derived, never incremented:

paidAmount =
    SUM(payment.amount − payment.refundedAmount)
        over payments WHERE status IN (SUCCEEDED, PARTIALLY_REFUNDED, REFUNDED)
  + SUM(application.amount)
        over credit_note_applications WHERE invoiceId = ? AND reversedAt IS NULL

Three properties follow:

1. A credit and a payment cannot erase each other. Both are terms in one sum, so applying a credit and then taking a card payment produces the correct total regardless of order.
2. A refund is subtracted by amount, not filtered out by status. A fully refunded payment contributes exactly zero; a $10 refund against a $100 payment leaves $90, not $0. Over-refunds are clamped per payment, so an over-refund on one payment can never consume another payment’s money.

Status is only recomputed for SENT, VIEWED, PARTIAL, PAID and OVERDUE. DRAFT and VOID are left alone — a refund against a cancelled invoice must not silently re-issue it. An OVERDUE invoice with a balance remaining stays OVERDUE; partial payment does not make it current again.

Why the formula exists twice

It has already earned its keep: it caught the two implementations disagreeing on whether an over-refund clamps per payment or on the aggregate, on its first run.

Configuration

Credit limits and available credit are stored as dollars (Decimal(12,2)), not cents.

Plan tiers

Credit notes and client billing carry no plan gate. Every capability in this guide is included in every plan, including Free. The only money-related plan gate in the catalogue is limits.maxContracts, which belongs to Contracts.

Limits and known behaviour

Say these out loud to a prospect rather than discovering them in week two.

• Without a QuickBooks connection this feature has no input.
• The MSP→client credit line is advisory. Nothing draws it down and nothing blocks an order that exceeds it (§2.1).
• Credits cannot cross currencies. Applying a note to an invoice in a different currency is refused rather than converted — a conversion would need an FX rate and a rate date this domain does not hold. Change one document’s currency or issue a note in the invoice’s currency.
• CreditNote.number is a single global sequence, shared across tenants, so a customer’s credit notes are not contiguous. Retained deliberately: renumbering issued financial documents would break records customers already hold.
• CreditNote.invoiceId is not the apply history. It records only the first target. Read applications.
• Credit notes do not have a PDF or a delivery path. They are visible in the API and in the org billing statements; nothing emails them.
• Statement figures are presentation values. They are computed in floating point and rounded to cents.
• The transaction feed’s page window fetches page × limit rows from each of the three streams. Counts are exact; very deep pages read proportionally more.

Troubleshooting

Messages below are the strings the service actually returns.

Verification

The single todo is automatic credit draw-down (§2.1), left deliberately unimplemented and deliberately absent from the datasheet.