Glossary

Stripe Invoice Line Item

A Stripe invoice line item is the individual billed unit on an invoice, an object with its own amount, quantity, pricing block and service period, which means an invoice is a collection of separately priced and separately dated items rather than one charge with a total.

Also called: invoice line, invoice line item, subscription line, invoice item

Start a free trial View Pricing

Definition

Most people picture a line item as a row on a document: a description on the left, a number on the right. In Stripe it is an object, and the difference matters because the object carries four fields that answer four different questions. How much is this line worth. How many units. At what unit price. And for what span of time.

Those last two are the ones that get lost. A row on a printed invoice has no room for a service period, so people read the invoice date as the date of everything on it. Stripe does not work that way, and it says so directly in its own API reference. The invoice carries period_start and period_end, but Stripe describes those as the earliest and latest timestamps at which invoice items can be associated with the invoice, and then instructs you to "Use the line item period to get the service period for each price."

That is the sentence worth keeping. The invoice does not know what period it covers. Its lines do, individually, and they can disagree with each other. A single invoice can carry a subscription line covering next month, a proration covering three days of last month, and a one-off charge for something delivered in March.

So when a number on a Stripe invoice needs explaining, the invoice total is rarely where the answer is. The line is.

Key points

+Stripe on amount: "The amount, in the smallest currency unit."
+Stripe on subtotal: "The subtotal of the line item, in the smallest currency unit, before any discounts or taxes."
+Stripe on period: "The period this line_item covers. For subscription line items, this is the subscription period."
+Stripe instructs you to use the line item period, not the invoice period, "to get the service period for each price".
+Stripe on quantity: "Quantity of units for the invoice line item in integer format, with any decimal precision truncated."
+Full precision lives in quantity_decimal, "Non-negative decimal with at most 12 decimal places".
+Unit price sits in the pricing block, alongside the price and product the line came from.
+Discounts and taxes attach per line, not only to the invoice.
+Stripe on discountable: "If true, discounts will apply to this line item. Always false for prorations."
+If Stripe Revenue Recognition is enabled, "the period will be used to recognize and defer revenue".

Four fields, four different questions

The fastest way to stop conflating them is to read them as separate answers.

Amount is what the line is worth. Stripe defines it as "The amount, in the smallest currency unit", which means an amount of 1000 on a USD invoice is ten dollars, not a thousand. Subtotal is the same number taken earlier in the calculation: "The subtotal of the line item, in the smallest currency unit, before any discounts or taxes."

Quantity is how many units. Pricing is what one unit costs, and it is a block rather than a single number, holding the unit amount alongside references to the Stripe price and product the line came from. Quantity times unit price is where amount comes from, which is why a line whose amount looks right can still have a quantity that is wrong.

Period is the span of time the line covers, and it is the only one of the four that is not about money at all.

The practical value of separating them is diagnostic. If revenue is right and units are wrong, look at quantity. If units are right and revenue is wrong, look at pricing or at discounts. If both are right and the month is wrong, look at period. Those are three genuinely different problems and they get confused constantly because a printed invoice row shows them all in one place.

A range on one side, a single date on the other

A Stripe invoice line has a period. Stripe defines it as "The period this line_item covers", and spells out the three cases: "For subscription line items, this is the subscription period. For prorations, this starts when the proration was calculated, and ends at the period end of the subscription. For invoice items, this is the time at which the invoice item was created or the period of the item."

That field is doing real accounting work inside Stripe. If Stripe Revenue Recognition is switched on, the documentation states that "the period will be used to recognize and defer revenue". The period is the input that decides which months a line belongs to.

QuickBooks does have a date field at the line level. Its invoice lines can show a Service Date column alongside the product, description, quantity, rate and amount. The mismatch is not that QuickBooks has nowhere to put a date. It is that a Service Date is one date and a Stripe period is two.

A point cannot hold a range. An annual subscription line covering January through December can be stamped with a service date, and whichever date you choose, the fact that it spans twelve months is not in the field. That is a difference in the shape of the two data models rather than a defect in any particular integration, and naming it plainly explains a whole class of questions that otherwise look like sync problems.

If you need the span itself reflected in your books, it has to be reconstructed on the QuickBooks side rather than carried across, which is what deferred revenue schedules and periodic journal entries exist to do.

Quantity is not always the number you think it is

Two details make quantity less obvious than it looks, and both are in Stripe's own definition of the field.

The first is precision. Stripe describes quantity as the "Quantity of units for the invoice line item in integer format, with any decimal precision truncated", and points to a second field for the real number: "For the line item's full-precision decimal quantity, use quantity_decimal." Stripe also notes that quantity "will be deprecated in favor of quantity_decimal in a future version". For usage billing measured in fractional units, the integer field is a rounded-down view of the truth.

The second is meaning. For prorations and subscriptions, quantity is not the count of things sold on this line. Stripe puts it this way: "If the line item is a proration or subscription, the quantity of the subscription that the proration was computed for." A proration line on a seat-based plan carries the seat count the proration was calculated against, not a number of units delivered.

Both of these matter most to anyone building unit-level reporting on top of billing data. Quantity on a Stripe invoice is a billing quantity. It answers what was charged for, and it only sometimes coincides with what a warehouse or a headcount would call a quantity.

Discounts and tax attach to the line

A discount in Stripe is not only an invoice-level adjustment. Lines carry their own discount detail, in a field Stripe describes as "The amount of discount calculated per discount for this line item", and a flag controlling eligibility: "If true, discounts will apply to this line item. Always false for prorations."

That last clause is a small rule with a real consequence. Proration lines cannot be discounted, so a percentage-off coupon applied to a subscription does not reduce the proration generated when that subscription changes mid-cycle.

Tax works the same way. Each line carries its own tax information rather than inheriting a single rate from the document.

The reason to know this is that it changes what "subtotal" means at each level. A line's subtotal is stated as the amount "before any discounts or taxes". The invoice's subtotal is a different calculation: Stripe defines it as the total of all subscriptions, invoice items and prorations "before any invoice level discount or exclusive tax is applied", and adds that "Item discounts are already incorporated". So line-level discounts are inside the invoice subtotal and invoice-level discounts are not. Two numbers, both called subtotal, computed at different stages.

Where lines come from, and what order they arrive in

Every line records its own origin. Stripe calls this the parent, "The parent that generated this line item", and it distinguishes a line created from a standalone invoice item, a line generated by a subscription, and a proration, which is flagged as such on the parent rather than being a separate object type.

That provenance is the reliable way to tell what a line is. Descriptions are human text and vary; the parent is structured.

Order is also defined rather than arbitrary. Stripe documents the sort 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. If you have ever wondered why a proration appears above the subscription charge it relates to, that is why.

None of this is visible on the rendered invoice a customer sees, which flattens all of it into rows. It is visible in the API, and it is what any system reading the invoice is actually working from.

How Acodei treats invoice lines

Acodei documents a narrow and specific surface here, and it is worth stating exactly rather than generally.

When a Stripe invoice is finalized, Acodei creates a QuickBooks invoice that its documentation says "reproduces every line-item, and tax lines, as allowed by the user's mapping settings". The mapping settings are the qualifier doing the work: each invoice line uses the product returned by Multiple Product Mapping when that is enabled, and the default product otherwise. So the QuickBooks product on a line is a mapping decision, not a copy of the Stripe product.

A documented limitation sits directly on top of this. In its metadata mapping documentation, Acodei states that it does not allow matching multiple lines from the same transaction, giving the example of mapping three different products on different lines and different amounts within a single sales receipt.

Several documented settings change the shape of the lines that get written. Quantity tracking on invoices writes the Stripe quantity rather than a hard-coded 1, is off by default, requires backend enablement, and is documented as incompatible with inclusive tax invoices. Coupon tracking posts coupons and discounts as a separate line item, and requires a Discounts product to be configured first. Shipping cost tracking breaks out Stripe's shipping amount as its own line, and needs a designated Shipping product. By default, Acodei also includes an applied customer balance as a line item on the QuickBooks invoice.

On the date question, Acodei documents three mutually exclusive service and supply date toggles, all off by default: one copies the invoice date into the QuickBooks Service Date field, one back-dates the QuickBooks invoice to the Stripe supply date, and one writes the supply date into the Service Date only. Note what those sources are. They fill the Service Date from the invoice date or from Stripe's supply date, not from the line period, and nothing in Acodei's documentation describes the Stripe line period being carried into QuickBooks. No such mapping is claimed here.

Want to see this on your own Stripe data?

Start a free trial

Frequently asked questions

What is a Stripe invoice line item?

It is the individual billed unit on a Stripe invoice, held as an object rather than a row of text. Each line carries its own amount, its own quantity, its own pricing information and its own service period, so an invoice is a collection of separately priced and separately dated items.

Does the invoice date tell me what period a charge covers?

No, and Stripe is explicit about it. The invoice carries period_start and period_end, but Stripe describes those as the earliest and latest timestamps at which invoice items can be associated with the invoice, and directs you to "Use the line item period to get the service period for each price". The period lives on the line.

What is the difference between quantity and quantity_decimal?

Stripe defines quantity as the "Quantity of units for the invoice line item in integer format, with any decimal precision truncated", and says to use quantity_decimal for "the line item's full-precision decimal quantity". Stripe also states that quantity "will be deprecated in favor of quantity_decimal in a future version".

Why can I not apply a discount to a proration line?

Because Stripe excludes them. The discountable field is documented as "If true, discounts will apply to this line item. Always false for prorations." A subscription-level coupon therefore does not reduce the proration created when that subscription changes mid-cycle.

Why do two things called subtotal show different numbers?

They are computed at different stages. A line item subtotal is the amount "before any discounts or taxes". The invoice subtotal is the total of subscriptions, invoice items and prorations "before any invoice level discount or exclusive tax is applied", and Stripe adds that "Item discounts are already incorporated". Line discounts are inside the invoice subtotal; invoice-level discounts are not.

What happens to the line period when the invoice syncs to QuickBooks?

QuickBooks invoice lines can carry a Service Date, so there is a date field. What there is not is a range: a Service Date is one date and a Stripe period is a start and an end. A twelve-month line can be stamped with a date, but the span is not preserved. That is a difference in the shape of the two data models rather than a fault in a particular sync, and reflecting a service span in QuickBooks means reconstructing it there.

Does the QuickBooks line show the same product as the Stripe line?

It shows the mapped product. Acodei documents that each invoice line uses the product returned by Multiple Product Mapping when that is enabled, and the default product otherwise, and that the QuickBooks invoice reproduces every line item and tax line "as allowed by the user's mapping settings".

What customers say about running Stripe through Acodei

★★★★★

“If you're testing out all the different Stripe/QuickBooks integration apps right now, let me save you some time. This one is the best one by far.”

RyanOwner at Indie Music Academy