Order to cash (AR)

The complete receivables stack: quote → order → fulfilment → invoice → collection → cash application → revenue.

The rule that governs the whole family:

An invoice is a claim, a payment is cash, and revenue is recognition. They are three different events on three different dates, and a UI that conflates any two of them will misstate something.

1. The lifecycle

Quote → Sales order → Fulfilment → Invoice → Dunning → Payment → Application → Cash
  │         │            │            │                  │           │
  │         │            │            └─ Dr AR / Cr Revenue          │
  │         │            └─ revenue recognition trigger (point-in-time)
  │         └─ backlog; no GL impact
  └─ no GL impact
                                                         └─ Dr Cash / Cr AR

No GL impact until the invoice. Quotes and orders are commitments, not transactions. Showing them in a revenue figure is the most common way a pipeline gets mistaken for performance. SalesOrderTable renders backlog and is visually separated from anything ledger-derived.

States

void and credited are different and the distinction matters. Voiding says the invoice should never have existed; crediting says it existed and is being reversed for a reason. A voided invoice with a payment against it is an error state. InvoiceDetail offers void only while unpaid and within the open period.

2. The invoice

type Invoice = {
  number: string;                  // sequential and unique — many VAT regimes require it
  customerId: string;
  issueDate: Date;
  dueDate: Date;                   // derived from terms; overridable with a reason
  terms: PaymentTerms;
  currency: string;
  lines: InvoiceLine[];
  subtotal: Money;
  discounts: Discount[];
  taxes: TaxLine[];                // per jurisdiction, per rate — never one lump
  total: Money;
  amountPaid: Money;
  amountCredited: Money;
  balanceDue: Money;               // total − paid − credited
  exchangeRate?: { rate: number; asOf: Date };   // if not in functional currency
  poNumber?: string;               // customer's PO — required by many AP departments
  revenueSchedule?: PerformanceObligation[];
};

UI rules:

• Invoice numbers are sequential and unique. Many VAT regimes require it, and gaps are a standard audit red flag. The UI never lets a user pick a number, and a gap is an audit finding surfaced in InvoiceRegister.
• balanceDue is the number that matters, and it's the one shown largest. Total is context; balance is the ask.
• Taxes are itemized by jurisdiction and rate, never a single "Tax" line. A customer disputing tax needs to see which authority and which rate.
• The customer PO number is prominent when present. An invoice missing the PO an AP department requires will be rejected and the user needs to see that before sending.
• Foreign-currency invoices show the rate and date used. The receivable is recorded at the transaction-date rate, revalued at period end, and settled at the payment-date rate — three rates, two FX gain/loss events. See multi-entity & FX.

Payment terms

type PaymentTerms =
  | { kind: "net"; days: number }                             // Net 30
  | { kind: "eom"; days: number }                             // Net 30 EOM
  | { kind: "discount"; discountPct: number; discountDays: number; netDays: number }  // 2/10 net 30
  | { kind: "due-on-receipt" }
  | { kind: "installments"; schedule: { date: Date; amount: Money }[] };

2/10 net 30 must be rendered in full, not as a code. "2% discount if paid within 10 days, otherwise due in 30 days" — and the component computes and shows both the discounted amount and the discount deadline, because that's the decision the customer is making.

3. Aging

The core AR view, and the one that ties to the balance sheet.

UI rules:

• Aging is by due date, not invoice date. Aging from the invoice date makes Net 60 terms look delinquent on day 31. This is a common and embarrassing bug.
• The aging total ties to the AR control account. Displayed, asserted. A difference means either the aging or the ledger is wrong.
• Row totals and column totals both foot, and the grand total is proven both ways.
• Bucket severity uses a sequential lightness ramp, not a red gradient — it survives greyscale and the signal palette. Age is also stated numerically ("47 days past due"), never color alone.
• Credit balances in AR are shown, not hidden. A customer with a net credit (overpayment, unapplied cash) appears as a negative in the aging and should arguably be reclassified to a liability at period end. The component flags it rather than burying it.
• Disputed invoices are excluded from dunning but included in aging. They are still receivables.

4. Cash application

Where AR actually breaks. Money arrives; matching it to invoices is the work.

type PaymentApplication = {
  paymentId: string;
  amountReceived: Money;
  applications: { invoiceId: string; amount: Money }[];
  unapplied: Money;              // received − sum(applied)
  writeOff?: { amount: Money; reason: string; account: string };
};

The cases the component must handle — all of them, not just the happy path:

UI rules:

• Unapplied cash is never revenue. A payment from a customer with open invoices reduces that customer's AR even before it's matched; only a net credit balance (or a prepayment with no receivable) is a liability, reclassified at period end. Products that book it to revenue, or leave a credit balance inside AR, misstate both.
• The suggested-combination feature is the highest-value interaction in AR. Given a lump sum, propose the set of invoices that sums exactly to it. When multiple combinations exist, show them ranked by oldest-first.
• A remaining difference always requires a disposition — write-off (with reason and account), leave unapplied, or dispute. The UI never lets a difference silently disappear.
• Write-off thresholds enforce approval. Small differences auto-write-off to a configured account; anything above the threshold requires an approver.
• Applying is reversible (unapply), and both actions are audited.

5. Collections and dunning

type DunningStep = {
  offsetDays: number;              // relative to due date; negative = pre-due reminder
  channel: "email" | "letter" | "task" | "call";
  template: string;
  escalateTo?: string;
  pauseIf: ("disputed" | "payment-plan" | "manual-hold")[];
};

UI rules:

• Disputes pause dunning automatically. Chasing a customer for an invoice they've formally disputed damages the relationship and is the single most common complaint about automated collections.
• The full communication history is on the customer, not scattered per invoice. A collector needs one timeline.
• Promise-to-pay is a first-class object with a date and an amount, and a broken promise escalates. "Customer said they'd pay Friday" is the most actionable fact in collections and it belongs in the data model.
• Payment plans convert one receivable into an installment schedule without changing the total. The aging reflects the plan's due dates, not the original.

6. Credit notes and refunds

Three different things, constantly conflated:

A write-off is not a credit note. A credit note says the customer doesn't owe it; a write-off says they owe it and won't pay. The revenue treatment and the tax treatment differ, and so does what it tells you about the business. The UI names each distinctly and never offers one where the other is meant.

Credit notes reference their original invoice and cannot exceed its balance without an explicit override.

7. Customer master

type Customer = {
  id: string; name: string; legalName?: string;
  billingAddress: Address; shippingAddress?: Address;
  taxId?: string; taxExemptCertificate?: Document;
  defaultTerms: PaymentTerms;
  creditLimit?: Money;
  currency: string;
  parentCustomerId?: string;       // hierarchy for group-level exposure
  contacts: Contact[];
  status: "active" | "on-hold" | "inactive";
};

UI rules:

• Credit limit and current exposure shown together, with exposure including unbilled orders. A limit without exposure is decoration.
• Customer hierarchy matters for exposure. Three subsidiaries of one group are one credit risk, and CustomerStatement supports rolling up.
• Tax exemption certificates expire. An expired certificate on an active customer is a flagged exception, because invoicing them tax-free after expiry is a liability.
• On-hold blocks new orders but not collections.

8. Revenue recognition, separated from billing

The most important structural point in this document.

Billing and recognition are independent. You can bill annually and recognize monthly, deliver first and bill later, or bill milestones that don't match delivery. Every combination is normal.

Received/due > Recognized  → contract liability (deferred revenue)
Recognized > Billed        → contract asset (right still conditional)
                             or unbilled receivable (right unconditional)

UI rules:

• An invoice does not automatically recognize revenue. It creates a receivable. What it credits — revenue or deferred revenue — depends on the performance obligations. InvoiceForm shows which, per line, before posting.
• The revenue waterfall is derived from obligations, not invoices.
• Never net contract assets against contract liabilities across contracts. Within a contract the position is presented net (required); across contracts it is not.
• Full model in schedules & accruals.

9. AR metrics

Every metric displays its formula, period, and inputs via MetricDefinition. DSO computed two different ways gives two different numbers, and a dashboard that doesn't say which is not comparable to anything.

10. AR component set