Stripe Invoice Item

The queue almost nobody looks at

Every Stripe account that has ever added a one-off charge to a subscription customer has a queue, whether or not anyone has opened it. It holds invoice items whose invoice field is still null.

Stripe does not present this as a queue, which is part of why it goes unnoticed. It presents it as a property of the object. The item exists, it has a customer, it has an amount, and the question of which invoice it belongs to has not been answered yet. Listing invoice items and filtering for a null invoice is how you see what is in there.

The reason to care is that an unbilled invoice item is money you have decided to charge and have not charged. It is not revenue, it is not a receivable, and it is not an error. It is a commitment sitting one step upstream of the first document your accounting system would recognise. If the queue is a day deep, nobody notices. If somebody added a charge against a customer whose subscription was cancelled the following week, it can sit there indefinitely, because the invoice that would have collected it is never created.

That is the failure mode worth knowing before you meet it: the item is not lost and nothing has broken, but no invoice is coming for it.

Two dates, and only one of them is the bill

An invoice item carries a date, which Stripe defines as the "Time at which the object was created". It also carries a period, an object with a start and an end, and Stripe is explicit about what that one is for: "When set to different values, the period will be rendered on the invoice", and if Stripe Revenue Recognition is enabled, "the period will be used to recognize and defer revenue".

So there are potentially three timestamps in play for a single charge, and they answer different questions. The date says when somebody decided to bill it. The period says what span of service it covers. The invoice date, which does not exist yet, will say when it was actually billed.

Most of the time nobody has to separate them, because the item is created and swept up in the same billing cycle and all three collapse to roughly the same week. The separation starts to matter at a period boundary. A charge created on the 28th of one month, against a service period in that month, billed on the invoice generated on the 1st of the next, is a genuinely ambiguous item to date, and the answer depends on whether your books run on cash or accrual and on what the period field says rather than what the created date says.

If you leave period unset, it defaults to the creation time on both ends, which is Stripe recording that it has no opinion about the service span. That is fine for a product sold on the spot and misleading for anything covering a stretch of time.

Subscriptions sweep, standalone invoices do not

This is the part that surprises people, and it is documented plainly enough that it is worth quoting rather than paraphrasing.

On a subscription, leaving the invoice parameter blank is all it takes. Stripe: "For subscription invoices, when left blank, the invoice item will be added to the next upcoming scheduled invoice." The next cycle picks it up with no further action.

On a standalone invoice, the same blank field does nothing of the kind. Stripe: "For standalone invoices, the invoice item won't be automatically added unless you pass pending_invoice_item_behavior: 'include' when creating the invoice." Create an invoice for that customer without that flag and it will be created without the pending item, which stays pending.

The practical shape of the mistake is a customer with no subscription, a one-off charge staged as an invoice item, and an invoice raised for them the following week that does not include it. Nothing errors. The invoice is correct for what it contains. The charge is simply still in the queue, and the natural conclusion, that the charge was somehow dropped, is wrong in a way that sends people looking in the wrong place.

There is a related scoping rule worth knowing if you run more than one subscription per customer. Set the subscription parameter and Stripe records the item against that subscription specifically: "When set, scheduled invoices for subscriptions other than the specified subscription will ignore the invoice item." Leave it blank and the next scheduled invoice takes it, whichever subscription generated that invoice.

Prorations are invoice items too

When a customer changes plan mid-cycle, the credit and the charge that result are not a special object type. They are invoice items, flagged as prorations, sitting in the same pending queue as anything you staged by hand.

Stripe marks them with a boolean, documented as whether the item "was created automatically as a proration adjustment when the customer switched plans", and applies one rule that catches people out: discountable is "Always false for prorations". A percentage-off coupon on the subscription does not reduce the proration the plan change generates.

This is why the pending queue on an active subscription account is rarely empty and rarely interesting. Most of what is in it is proration arithmetic that Stripe put there itself and will collect on the next cycle without anyone intervening. The items worth attention are the ones somebody created deliberately, because those are the ones that can have been staged against the wrong customer, or against a customer who has since stopped being billed.

Stripe also populates a proration_details block, and notes that it "is only populated for prorations created from subscriptions with billing_mode=flexible", so its presence is a signal about the subscription rather than about the item.

What it becomes once an invoice takes it

The moment an invoice picks the item up, it stops being an invoice item in any practical sense and becomes a line on that invoice, subject to everything that governs lines.

It also lands in a defined place. Stripe documents the sort order of an invoice's lines as pending invoice items including prorations in reverse chronological order first, then subscription items in reverse chronological order, then invoice items added after invoice creation in chronological order. That is why a one-off charge and a proration appear above the subscription charge on an invoice rather than below it, which reads as odd until you know the rule.

One more piece of Stripe vocabulary attaches here. If pending invoice items are the only reason an invoice was generated at all, Stripe records that on the invoice as a billing_reason of automatic_pending_invoice_item_invoice. Stripe lists that value among the possible enum values without giving it a separate description, so the honest reading is the name itself: an invoice that exists because items were waiting, rather than because a subscription cycled.

That value is the one reliable way, after the fact, to tell an invoice that was triggered by the queue from an invoice that would have been generated anyway.