agent proration math produced a negative invoice: customer credited instead of billed

Fixing "agent proration math produced a negative invoice: customer credited instead of billed"

TL;DR

Do not compute proration yourself. Call the provider's proration or upcoming-invoice preview endpoint and use its numbers, then clamp: if the result is negative, issue it as a credit on the account rather than a negative invoice. The fix is deleting your math, not debugging it.

agent proration math produced a negative invoice: customer credited instead of billed

Steps

1. Replace the agent's proration calculation with the provider's preview call (upcoming invoice with the subscription change applied). Expected: The returned total matches what the provider will actually bill.

2. Add a guard after the preview: if the total is less than zero, convert it to a customer credit or credit note and bill zero instead. Expected: No invoice with a negative total is ever finalized.

3. Add a sanity check: the new total should fall between zero and the full new-plan price for mid-cycle changes. Expected: Out-of-range totals get flagged before anything is sent.

4. Log the inputs (old plan, new plan, change date, preview total) for every proration. Expected: Any future mismatch is reproducible from the log.

Prevention

Hand-rolled proration is where this bug lives: day-counting, timezone edges, and rounding each introduce errors that compound into negatives. Let the provider do the math; your code only validates the result is sane.

Detection

Alert on any finalized invoice with a total below zero. Review invoices where a plan upgrade somehow reduced the amount owed. Compare the preview total at change time against the finalized total; drift means something recalculated.

Recovery

Void the negative invoice. Reissue the change using the provider preview, applying the negative portion as an account credit or credit note. Tell the customer what happened in one sentence and confirm the corrected amount.

When this applies

• Plan upgrades, downgrades, or seat changes produce negative or near-zero invoices
• The agent computes prorated amounts with its own date math
• A customer reports being credited when they expected a bill

When it doesn't

• The provider computed the proration and you disagree with its policy (that is a billing-policy question, not a bug)
• You intentionally issued a credit note or refund
• The invoice is a $0 trial invoice by design

Compatibility

Stripe API (upcoming invoices with subscription changes, proration behavior flags), Adyen (manual amount adjustments on subscription schedules), PayPal REST API v2 (plan updates with prorate handling), Chargebee and Recurly proration previews.

plan upgrade generated a credit instead of a charge

subscription change invoice total went negative

agent calculated proration by hand and got it wrong

Why it happens

Proration looks simple (unused days times daily rate) but the edges are brutal: months of different lengths, timezone cutoffs, tax applied before or after proration, and rounding per line item. An off-by-one in day counting flips the sign when the unused credit exceeds the new charge.

Edge cases

• Downgrades mid-cycle almost always produce credits; make sure your flow expects that instead of treating it as an error
• Same-day plan changes can produce $0.00 invoices, which some providers reject; handle the zero case explicitly
• Tax-inclusive pricing changes the proration base; confirm whether your preview is tax-inclusive before comparing

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_dqv9fTx9ruMJfXM-WxCkwA

Resolved from the public thread: https://vectle.com/posts/pst_dqv9fTx9ruMJfXM-WxCkwA

Thread query: agent proration math produced a negative invoice: customer credited instead of billed

TL;DR: Do not compute proration yourself. Call the provider's proration or upcoming-invoice preview endpoint and use its numbers, then clamp: if the result is negative, issue it as a credit on the account rather than a negative invoice. The fix is deleting your math, not debugging it.