stripe upcoming invoice preview ignores pending invoice items

TL;DR

The upcoming invoice preview does not include pending invoice items by default: it previews the subscription's next invoice, not the customer's pending item queue. To see the true next total, fetch pending invoice items for the customer separately and add them to your preview math, or pass them explicitly where the API supports it. Design your preview UI to always combine both sources.

stripe upcoming invoice preview ignores pending invoice items

Use this when

• Stripe upcoming invoice preview ignores pending invoice items
• Your preview total is lower than the actual next invoice
• You show customers a pre-billing estimate

Not for this skill when

• The subscription itself previews incorrectly (check subscription items and discounts)
• Pending items are missing from the finalized invoice too (different bug)
• You are debugging metered usage rather than pending items

Steps

1. Fetch the customer's pending invoice items via the invoice items list endpoint. Expected: You see the items the preview omitted.

2. Compare with the upcoming invoice preview response. Expected: The gap is quantified.

3. Add the pending items' amounts to the preview total in your display logic. Expected: The customer sees the true upcoming total.

4. Where the API supports it, pass the pending items explicitly into the preview call. Expected: The preview itself includes them.

5. Add a regression check: preview total must equal subscription preview plus pending items. Expected: Drift is caught automatically.

Tool compatibility

Stripe upcoming invoice preview and invoice items APIs; pending invoice items are customer-scoped, not subscription-scoped.

Variant phrasings

stripe upcoming invoice missing pending items

The gap stated directly.

stripe preview invoice pending invoice items

The API-object phrasing.

stripe next invoice total wrong pending items

The customer-impact phrasing.

Why it happens

Pending invoice items belong to the customer, not to any single subscription: they are a queue of unbilled charges waiting to be swept onto the next invoice. The upcoming invoice preview, however, is subscription-centric: it projects the next invoice for one subscription. The two scopes do not automatically merge in the preview response. Your integration must combine them, because the finalized invoice will include the pending items even though the preview did not.

Edge cases / pitfalls

• Pending items can also be swept onto invoices you create manually; the preview gap applies there too.
• Discounts and tax on pending items are computed at finalize time; your preview math is an estimate.
• If pending items should not bill next cycle, clear or void them rather than hiding them from the preview.

Provenance

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

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

Thread query: stripe upcoming invoice preview ignores pending invoice items

TL;DR: The upcoming invoice preview does not include pending invoice items by default: it previews the subscription's next invoice, not the customer's pending item queue. To see the true next total, fetch pending invoice items for the customer separately and add them to your preview math, or pass them explicitly where the API supports it. Design your preview UI to always combine both sources.