Review a billing proration engine

Review exercise · TypeScript

Nightmare55 min

Review brief

A subscription platform replaces its billing provider's mid-period plan-change calculation. The engine receives authoritative net prices after discounts and exact billing instants, and webhooks may be delivered concurrently or retried after partial failures.

Behavioral contract

Every numeric input is a finite safe integer. Prices and taxBasisPoints are non-negative, taxBasisPoints is at most 10,000, and the caller guarantees every addition, subtraction, and multiplication in both the submitted and required formulas remains within Number's safe-integer range; arbitrary-precision arithmetic is out of scope.
The period is the half-open instant range [periodStartMs, periodEndMs), and effectiveAtMs is inside it; use exact elapsed milliseconds rather than calendar-day approximations.
oldNetCents and newNetCents are the integer full-period prices actually owed after discounts. Compute one signed numerator (newNetCents - oldNetCents) * remainingMs / periodMs and round the aggregate once to the nearest cent with halves away from zero.
Negative adjustments are credits and remain negative. Tax is the same signed half-away rounding of adjustmentCents * taxBasisPoints / 10000, so a credit also refunds tax.
changeId uniquely identifies a plan-change event. Processing atomically claims that ID before creating exactly one invoice; concurrent and retried deliveries return the original invoice.
The invoice identity includes accountId and changeId. A failure before commit leaves the claim retryable, while a committed invoice and claim are visible together.

Review instructions

1Trace exact arithmetic separately from delivery idempotency and transaction ordering.
2Use concrete upgrade, downgrade, boundary, and retry scenarios.
3Prioritize no more than six findings.

Learning objectives

• Preserve exact monetary and temporal proration semantics
• Trace credits, charges, and tax as one signed adjustment
• Make invoice creation idempotent across concurrency and partial failure

src/proration-types.tsTypeScript

@@ -0,0 +1,28 @@

1+export interface PlanChange {

2+ changeId: string;

3+ accountId: string;

4+ periodStartMs: number;

5+ periodEndMs: number;

6+ effectiveAtMs: number;

7+ oldListCents: number;

8+ oldNetCents: number;

9+ newNetCents: number;

10+ taxBasisPoints: number;

11+}

12+

13+export interface AdjustmentInvoice {

14+ id: string;

15+ accountId: string;

16+ adjustmentCents: number;

17+ taxCents: number;

18+}

19+

20+export interface InvoiceRepository {

21+ findByChangeId(changeId: string): Promise<AdjustmentInvoice | undefined>;

22+ insert(invoice: AdjustmentInvoice): Promise<void>;

23+ markChangeProcessed(changeId: string): Promise<void>;

24+ claimAndCreateByChangeId(

25+ changeId: string,

26+ invoice: AdjustmentInvoice,

27+ ): Promise<AdjustmentInvoice>;

28+}

Reference solution

The findings below are ordered by priority.

Findings

1. Concurrent deliveries can both create an invoice

Location: src/process-plan-change.ts:11-25

The read-before-insert check does not claim changeId atomically. Two workers can both observe no existing result and insert, while a crash after insert but before markChangeProcessed makes a retry create another invoice.

Use claimAndCreateByChangeId to claim the change ID and create the invoice in one transaction with a uniqueness constraint, returning the committed invoice to losers and retries.

2. Invoice identity collides for distinct changes in one period

Location: src/process-plan-change.ts:18-22

The ID contains the account and period start but not changeId. Two legitimate plan changes in the same period produce the same identity even though each requires a distinct idempotent adjustment.

Derive identity from account and change ID, with the event claim as the authoritative deduplication key.

3. Whole-day approximation changes the contracted fraction

Location: src/proration-calculator.ts:3-13

Rounding period duration to days and rounding remaining duration up loses exact instant semantics. Partial days are overcharged, and sufficiently short periods can round to zero and produce division by zero.

Use the exact positive millisecond durations directly in the rational calculation.

4. The credit uses list price and rounds both legs separately

Location: src/proration-calculator.ts:15-21

oldListCents refunds money the customer did not pay when the old plan was discounted. Separately rounding the credit and charge can differ by a cent from rounding their signed difference once.

Use newNetCents - oldNetCents as one numerator and perform the required half-away rounding only after applying the remaining fraction.

5. Downgrade credits are discarded

Location: src/proration-calculator.ts:22

Math.max(0, ...) clamps every negative adjustment to zero. A customer moving to a cheaper plan receives no required credit for the unused value.

Preserve the signed rounded result; negative invoice adjustments are supported by the contract.

6. Tax is calculated from the new-plan charge rather than the net adjustment

Location: src/proration-calculator.ts:22-24

Tax ignores the old-plan credit and is always non-negative. Upgrades are overtaxed and downgrades omit the required tax refund; Math.round also does not implement halves away from zero for negative values.

Apply the basis points to the signed final adjustment and use the explicit symmetric rounding rule once.

Reasonable non-findings

Integer cents are the correct input and output representation.
Returning an already committed invoice for a repeated change ID is required behavior.
The engine may rely on the stated finite safe-integer and intermediate-operation bounds; arbitrary-precision arithmetic outside them is not required.