Stripe invoice finalize fails: no line items error
Fixes Stripe invoice finalization failures caused by empty invoices. Use when finalize_invoice returns an error about missing line items or a zero-amount invoice that cannot be finalized. Not for payment or tax failures.
TL;DR
Stripe refuses to finalize an invoice with no line items, so check the invoice has at least one item and a nonzero total before calling finalize. Add missing invoice items, or delete the empty draft and start over. Validate item presence in your code path so it never reaches finalize empty.
Error
```text
You cannot finalize an invoice with no line items.
## Steps
1. Retrieve the invoice and inspect its lines array before finalizing.
Expected: You confirm the lines array is empty, which is the cause.
2. Trace where the invoice was created and find why no invoice items were attached (race, skipped step, deleted items).
Expected: You know the upstream gap to fix.
3. Add the missing invoice items to the draft, or void and recreate the draft with items included.
Expected: The invoice now carries billable lines.
4. Re-fetch the invoice, confirm total is greater than zero, then call finalize.
Expected: Finalize succeeds and the invoice moves to open.
5. Add a guard in your code: refuse to call finalize when lines is empty or total is zero.
Expected: The failure mode is eliminated at the source.
## When to use
- finalize_invoice errors on an empty invoice
- Draft invoices exist with no line items
- An automation creates invoices that sometimes have nothing to bill
## When not to use
- Finalize fails on a payment method or 3DS step (different failure)
- The invoice has items but the total is zero (see zero-amount invoice handling)
- You intentionally want a zero invoice (use a different flow, like a credit note)
## Compatibility
Stripe API 2020-08-27 and later; finalize_invoice endpoint across all official SDKs.
## Variant phrasings
### ### cannot finalize invoice no line items
### ### Stripe empty draft invoice finalize
### ### finalize invoice with zero items
## Root cause
Finalization converts a draft into a real receivable: it assigns a number, sets due dates, and triggers collection. Stripe blocks that transition for empty invoices because a numbered invoice with nothing on it is a bookkeeping artifact with no legal meaning.
## Edge cases
- Items deleted from a draft after creation can empty it silently
- Proration-only subscription changes can leave a draft with net-zero lines that finalize rejects
- auto_advance drafts with no items get stuck open; clean them up on a schedule
## Provenance
Resolved from the public thread: https://vectle.com/posts/pst_I-QOqqMAIxjuWejBEc649A
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.