Key Takeaways

• A line item stores a service period, not just a price, and revenue recognition reads that period to decide which month the money belongs to.

• Stripe's line_item object holds amount as an integer in the smallest currency unit, so 1000 means $10.00 USD, and quantity_decimal accepts up to 12 decimal places.

• Each line item points back at the object that created it through a parent field, which is what lets anyone trace a total to a subscription, a one-off charge, or a proration.

• Stripe's API reference states that updating an invoice's line item is only possible before the invoice is finalized, so corrections after issuance run through a credit note instead.

What fields does an invoice line item carry?

An invoice line item carries a description, a quantity, a rate, a service period, and the amount those produce, plus a pointer back to whatever generated it. Stripe's public API reference names each field, and the shape repeats across billing systems even when the spelling differs.

Here's the example object Stripe publishes, trimmed to the fields above:

{
  "id": "il_tmp_1Nzo1ZGgdF1VjufLzD1UUn9R",
  "object": "line_item",
  "amount": 1000,
  "currency": "usd",
  "description": "My First Invoice Item (created for API docs)",
  "period": { "start": 1696975413, "end": 1696975413 },
  "pricing": { "price_details": { "price": "price_1NzlYfGgdF1VjufL0cVjLJVI" } },
  "quantity_decimal": "1",
  "taxes": []
}

The period field does more work than it looks like it does. Stripe's docs note that Revenue Recognition reads it to recognize and defer revenue. Get the period wrong and the arithmetic still foots while the revenue lands in the wrong month.

How does a billing system generate line items?

A billing engine generates line items when it closes a billing period, by walking every billable object attached to the subscription and emitting one row per priced thing it finds. Nobody types these in.

The sequence that produces a finished invoice:

1. Collect the recurring subscription items due for the period.

2. Read the aggregated usage total for each metered item and multiply it by the rate structure.

3. Emit proration rows for any mid-cycle plan or seat change.

4. Apply discounts and credits, which land either on individual lines or as separate negative rows.

5. Sum the lines into a subtotal, calculate tax on it, and write the total.

Everything up to finalization lives in a draft invoice, which is why late usage can still change a number without anyone issuing a correction. Here's what four lines look like on a real monthly bill, in dollars:

Those four rows sum to a subtotal of 1,062.67. Tax at 8.25% adds 87.67, so the total due is 1,150.34. I'd check that in the smallest currency unit rather than in dollars, because that's where rounding errors show up: 30000 + 49600 + 30000 - 3333 = 106267, plus 8767 of tax, equals 115034.

Related terms

These pages cover the objects that sit either side of a line item on a real bill.

• Draft invoice covers the mutable state a line item lives in before finalization.

• Billing engine is the component that turns usage and contract terms into these rows.

• Billing vs invoicing separates calculating what's owed from issuing the document.

• Credit memo is the instrument for correcting a line after the invoice ships.

• Billing period sets the boundary that decides which lines land on which invoice.

• Consolidated invoicing explains what happens when lines from several subscriptions merge onto one document.

FAQ

What's the difference between an invoice item and an invoice line item?

An invoice item is a pending charge staged against a customer, and it becomes a line item once the billing system builds the invoice. Stripe keeps these as separate API resources. The invoice item is the instruction, the line item is the result.

Can you edit a line item after an invoice is finalized?

No. Stripe's API reference states that updating an invoice's line item is only possible before the invoice is finalized. After that, you issue a credit note or an adjusting invoice.

Do invoice line items include tax?

Not in the line amount itself. Tax sits in a separate taxes array on the line and gets summed into the invoice total, which keeps the taxable base auditable per row. That separation matters when one invoice mixes taxable and exempt items.

Why would a line item show a negative amount?

Negative line items record credits: proration refunds for downgrades, promotional discounts applied as their own row, or prepaid balance drawdowns. They reduce the subtotal exactly the way positive lines increase it.