Stripe invoiceitem attached to the wrong upcoming invoice

Not specified by the original author.

TL;DR

Invoice items attach to a customer by default and land on that customer's next invoice, which surprises people expecting them on a specific subscription. Pass the subscription id when creating the item to pin it to that subscription's next invoice, or delete and recreate the item with the right scope. Always scope explicitly.

Error

```text
invoiceitem in_xxx attached to invoice in_yyy (wrong subscription period)

## Steps

1. Retrieve the invoice item and read its customer and subscription fields.
   Expected: You see which scope it actually carries.
2. If the subscription field is empty, that is the bug: customer-scoped items join the next invoice for the whole customer.
   Expected: Root cause confirmed.
3. Delete the mis-scoped item (only possible while it is still pending) and recreate it with the subscription id set.
   Expected: The charge now targets the right subscription's next invoice.
4. If the wrong invoice already finalized, void it if unpaid or issue a credit note, then recreate correctly.
   Expected: The books are fixed without double billing.
5. Make subscription id a required parameter in your invoice-item creation helper.
   Expected: Future items cannot be created unscoped.

## When to use

- A one-off charge lands on the wrong invoice
- A customer has multiple subscriptions and the item picked the wrong one
- You expected subscription scoping but passed only a customer

## When not to use

- The item is correct but proration lines confuse the invoice layout
- The invoice already paid and you need a refund flow instead
- Tax behavior differs per subscription (that is a tax-settings issue)

## Compatibility

Stripe API 2018-05-21 and later; invoiceitems endpoint across all SDKs. Pending items are editable and deletable; invoiced items are not.

## Variant phrasings

### ### invoiceitem wrong subscription Stripe

### ### pending invoice item wrong invoice

### ### scope invoice item to subscription

## Root cause

Invoice items are customer-level ledger entries by default; Stripe sweeps every pending item for a customer into the next invoice generated for that customer, regardless of which subscription triggered the billing run. The subscription field exists precisely to narrow that sweep.

## Edge cases

- Items created moments before finalization can still sneak into the closing invoice
- Metered usage items behave the same way: scope them too
- Deleting a pending item is safe, but an item on a finalized invoice needs a credit note

## Provenance

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

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

Thread query: Stripe invoiceitem attached to the wrong upcoming invoice

TL;DR: Invoice items attach to a customer by default and land on that customer's next invoice, which surprises people expecting them on a specific subscription. Pass the subscription id when creating the item to pin it to that subscription's next invoice, or delete and recreate the item with the right scope. Always scope explicitly.

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

An empty upcoming-invoice preview is normal when the subscription has no pending invoice items, no plan change, and no upcoming renewal within the window. Add pending invoice items, apply a coupon, or adjust the subscription date to generate preview lines. Check the subscription state before assuming the API is broken.

upcoming invoice returns no lines

Use this when

• The upcoming invoice API returns zero lines when you expected a preview.
• You are building a checkout preview page and it shows nothing.
• A prorated plan change should produce lines but does not.

Not for this skill when

• A finalized invoice is missing lines. That is a data problem, not a preview problem.
• The subscription itself does not exist or is canceled. Nothing billable can exist.

Steps

1. ('Fetch the subscription and confirm it is active or trialing. Verify: status is not canceled or incompleteexpired.', 'Check for pending invoice items on the customer. Verify: none exist if the preview is empty.', 'Check the next invoice date and any scheduled subscription changes. Verify: nothing changes between now and the preview window.', 'To preview a plan change, call the upcoming-invoice endpoint with the subscriptionitems override. Verify: proration lines appear in the response.', 'To preview usage or metered charges, post pending invoice items first, then re-preview. Verify: lines reflect the new items.')

Variant phrasings

stripe upcoming invoice empty

The short search.

stripe preview invoice no lines

API-method phrasing.

stripe upcoming invoice lines missing proration

Plan-change context.

Compatibility: Stripe Billing API upcoming invoices endpoint, all client versions.

Why it happens

The upcoming-invoice endpoint renders what the next invoice would contain, and a subscription with no pending items and no scheduled changes genuinely bills zero lines next cycle. Metered usage not yet reported, coupons already consumed, and trials with no items all produce empty previews. Empty is the API telling the truth about a quiet billing period, not a bug.

Edge cases / pitfalls

• Passing the wrong customer id silently previews a different customer with no items. Double-check.
• A plan change previewed without subscription_items override shows the unchanged plan: empty if the period already invoiced.
• Upcoming invoices are previews only; they never create anything, so an empty one costs you nothing.
• If the UI hides empty previews, add a fallback message ("no charges due") so users do not see a blank page.

Provenance

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

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

Thread query: stripe upcoming invoice returns no lines: no upcoming invoice items on the subscription

TL;DR: An empty upcoming-invoice preview is normal when the subscription has no pending invoice items, no plan change, and no upcoming renewal within the window. Add pending invoice items, apply a coupon, or adjust the subscription date to generate preview lines. Check the subscription state before assuming the API is broken.