stripe invoice "amount_remaining" vs "amount_due" after a partial payment

TL;DR

amountdue is the original invoice total; amountremaining is what is still unpaid after partial payments. After a partial payment, amountdue stays the same and amountremaining drops. Reconcile against amount_remaining, and mark the invoice paid only when it hits zero.

amount_remaining vs amount_due partial payment

Use this when

• An invoice shows amountdue larger than amountremaining after a partial payment.
• Your reconciliation code treats amount_due as the outstanding balance and double-counts.
• A customer paid part of an invoice and asks what they still owe.

Not for this skill when

• The customer overpaid. Overpayments create credit balances, a different field set.
• The invoice total itself is wrong. That is a line-item problem.

Steps

1. ('Read both fields on the invoice. Verify: amountdue is the original total, amountremaining is total minus payments.', 'Sum the invoice payments and confirm they equal amountdue minus amountremaining. Verify: the math reconciles.', 'When amountremaining hits zero, the invoice auto-finalizes as paid. Verify: status is paid, not open.', 'Update your ledger from amountremaining, never amount_due, for outstanding balances. Verify: no invoice is double-counted as owed.', 'If a partial payment was accidental, issue a refund or apply the remainder as credit per your policy. Verify: the customer record reflects the resolution.')

Variant phrasings

stripe amountremaining amountdue difference

Field-comparison search.

stripe invoice partial payment remaining balance

Symptom search.

amount_due not updating after payment stripe

Confusion search.

Compatibility: Stripe Billing invoices API, all client versions. Both fields are on the invoice object.

Why it happens

Stripe keeps amountdue as the invoice total for its lifetime, a record of what was billed, while amountremaining tracks collection progress. Partial payments are common in B2B (deposits, split payments, wire plus card), so the invoice object needs both the original bill and the live balance. amount_due never shrinks because the bill itself did not shrink; only the unpaid remainder did.

Edge cases / pitfalls

• Do not key dunning off amount_due. A half-paid invoice would get full-balance collection emails.
• amount_remaining can go negative on overpayments; handle that branch explicitly.
• Refunds increase amount_remaining back up. Partial refunds re-open collection.
• Your webhook handler should compare against amount_remaining when deciding invoice.paid means paid in full.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ip3OXGa6IaPN9MqFE9o7WA