Glossary

Stripe Price

A Stripe Price is the object that holds the amount, currency and billing scheme for a product, and it is the rule that converts a quantity into the amount charged on an invoice line.

Also called: price object, billing_scheme, tiers_mode, unit_amount, graduated pricing, volume pricing

Start a free trial View Pricing

Definition

A product says what you sell. A Price says how much, in what currency, and how often. It also says something that gets forgotten: by what rule.

Stripe puts the pair at the centre of the model: to build a pricing model "you use products (what you sell) and prices (how much and how often to charge for your products)". Most of the time the rule is dull. A price of 10 USD per unit times four units is 40 USD, and nothing interesting happened. The rule stops being dull the moment quantity stops being a multiplier.

Consider an invoice line reading `20 units` at a total of `120.00`. That line is consistent with a flat rate of 6 USD each. It is equally consistent with a tiered price where the first five units cost 7 USD and the rest cost less, or with a volume price where crossing a threshold repriced every unit at once. Same quantity, same product, three different rules, and on the finished document they are indistinguishable.

That is the bookkeeping problem this object creates. Reconstructing what a customer was actually charged for, as opposed to what they paid, needs the Price that produced the line. The line records the outcome. The rule lives somewhere else, and it is usually frozen.

Key points

+billing_scheme is either per_unit or tiered, and unit_amount is only set on per-unit prices.
+tiers_mode is graduated or volume, and the two return different totals for the same quantity.
+Almost nothing on a Price can be changed after creation: amount, currency, scheme and tiers are all fixed.
+tax_behavior can never be changed once it is set to inclusive or exclusive.
+lookup_key is the one identifier that can be moved from one price to another.
+The invoice line records the amount, not the rule that produced it.

The two billing schemes

Every Price is one of two shapes, and `billing_scheme` is the field that says which.

Stripe defines it as describing "how to compute the price per period. Either `per_unit` or `tiered`." Per-unit means "the fixed amount (specified in `unit_amount` or `unit_amount_decimal`) will be charged per unit in `quantity` (for prices with `usage_type=licensed`), or per unit of total usage (for prices with `usage_type=metered`)". Tiered means "the unit pricing will be computed using a tiering strategy as defined using the `tiers` and `tiers_mode` attributes".

The practical tell is which fields are populated. Stripe documents `unit_amount` as "Only set if `billing_scheme=per_unit`", and the same for `unit_amount_decimal`. So a Price whose `unit_amount` is null is not a broken price. It is a tiered one, and the amounts are inside the `tiers` array, which has to be expanded to be read at all.

One restriction is worth knowing before designing around it. `transform_quantity`, which applies "a transformation to the reported usage or set quantity before computing the amount billed", "cannot be combined with `tiers`". Package pricing and tiered pricing are alternatives, not layers.

Graduated and volume answer the same question differently

When `billing_scheme` is `tiered`, a second field decides the arithmetic. Stripe defines `tiers_mode` as: "Defines if the tiering price should be `graduated` or `volume` based. In `volume`-based tiering, the maximum quantity within a period determines the per unit price. In `graduated` tiering, pricing can change as the quantity grows."

That is a compact sentence carrying a large difference. Stripe's own worked example uses three tiers (1 to 5 fonts at 7 USD, 6 to 10 at 6.50 USD, 11 and above at 6 USD) and runs the same quantities through both modes.

Under volume, "the entire `quantity` (or `usage`) is multiplied by the unit cost of the tier". Six fonts are billed entirely at the 6 to 10 rate: 39 USD. Twenty fonts are billed entirely at the top rate: 120 USD.

Under graduated, Stripe "charges for the usage in each tier instead of applying a single price for overall usage", and "the totals for each tier are summed together". Six fonts cost 41.50 USD: 35 USD for the first five, then 6.50 USD for the sixth. Twenty fonts cost 127.50 USD.

So the same twenty units on the same tier table produce 120 USD or 127.50 USD depending on one enum. Stripe also flags the counterintuitive consequence of volume mode: because the tier price applies to the whole quantity, "the total might decrease when calculating the final cost". A customer can buy more and be billed less than a customer who bought slightly less. That is the design working, not a pricing bug, and it is worth being able to say so with the tier table in hand.

A flat rate can ride along with the tiers

Each tier can carry a fixed charge as well as a per-unit one. Stripe: "You can specify a flat rate (`flat_amount`) to add to the invoice. This works for both volume and graduated pricing."

The combination rule is strict and easy to get backwards: "A tier can have either a `unit_amount` or a `flat_amount`, or both, but it must have at least one of the two."

Stripe's worked example is the clearest way to see the two modes diverge again. With five tiers running from 5 USD per unit plus a 10 USD flat rate down to 1 USD per unit plus a 50 USD flat rate, a quantity of 12 bills as `12 × 3 USD + 30 USD = 66 USD` under volume, and as `(5 × 5 USD + 10 USD) + (5 × 4 USD + 20 USD) + (2 × 3 USD + 30 USD) = 111 USD` under graduated. Graduated accumulates a flat rate for every tier it passes through.

The zero case surprises people, and it produces real invoice lines. Stripe: "If `quantity` is `0`, the total amount is 10 USD regardless of the tiered pricing model used. Stripe always bills the first flat rate tier when `quantity=0`." A customer who used nothing still gets charged, because the first tier's flat rate is unconditional. Stripe gives the escape hatch too: "To bill `0` when there's no usage, set up an `up_to=1` tier with an `unit_amount` equal to the flat rate and omit the `flat_amount`."

What you cannot change after creation

This is the half that decides how you investigate an old invoice, and it is narrower than most people assume.

The update endpoint accepts a short list: `active`, `currency_options`, `lookup_key`, `metadata`, `nickname`, `tax_behavior` and `transfer_lookup_key`. Nothing else. The amount, the currency, the billing scheme, the tiers, the tier mode, the recurring interval and the product the price belongs to are all fixed at creation and cannot be edited afterwards.

The Dashboard states the same boundary in plainer words when you build a tiered price: "You can only edit the product and price until you create a subscription with them."

`tax_behavior` is the one field on the updatable list that is only updatable once. Stripe: "Once specified as either `inclusive` or `exclusive`, it cannot be changed." A price left at `unspecified` can still be settled; a price already committed either way cannot be flipped.

The consequence for anyone reconciling: a repricing is a new Price object, not an edited one. The old price is archived by setting `active` to false, which Stripe defines as "whether the price can be used for new purchases". Archiving stops new sales without touching the history. So the Price attached to a two-year-old invoice line is still the one that produced it, still readable, and still correct.

lookup_key is the one thing that can move

Because prices are immutable and repricing means creating a new object, application code that hardcodes a price ID has to be redeployed on every price change. `lookup_key` exists to break that link. Stripe describes it as "a lookup key used to retrieve prices dynamically from a static string", up to 200 characters.

The transfer is the useful part, and it is the part worth reading carefully rather than assuming. The update endpoint takes `transfer_lookup_key`, documented as: "If set to true, will atomically remove the lookup key from the existing price, and assign it to this price."

So the key is not copied and it is not shared. It is moved, in one operation, from the old price to the new one. Code asking for `standard_monthly` gets the new price from that moment on, and the old price keeps everything except the key.

For bookkeeping this is a hazard worth naming. A lookup key is not a stable identifier for a price over time. Two invoices six months apart, both raised against `standard_monthly`, can point at two different Price objects with two different amounts. Only the price ID on the line is stable.

What the invoice line carries, and what it does not

The line item on a finalized invoice records the amount, the quantity and a reference to the price and product it came from. It does not record the arithmetic.

There is no field on the line saying "this was graduated" or "this crossed into the third tier". To answer that you have to retrieve the Price, expand its `tiers` array, and run the quantity through the table yourself. On a price that has since been archived and replaced, you have to make sure you retrieved the right one, which means trusting the price ID on the line rather than the lookup key or the nickname.

Which is the practical advice this entry exists to give. When a revenue figure has to be defended and the invoice line will not explain itself, the price ID on the line is the thread to pull. Everything else about a Price is convenience. The name, the nickname and the lookup key can all move.

How Acodei handles priced lines

Acodei's product documentation has no page on Prices, and nothing in it describes reading or interpreting a price's billing scheme or tiers. So there is no documented behaviour to describe on that front, and this entry does not invent one.

What is documented is what happens to the line the Price produced. When a Stripe invoice is finalized, Acodei creates a QuickBooks invoice that reproduces every line item, and tax lines, as your mapping settings allow. Each line uses the product returned by Multiple Product Mapping if you have it enabled, and the default product otherwise. Whichever scheme produced the amount, what Acodei reproduces is the line.

Quantity is a separate setting rather than a given: Invoice Sync pushes Stripe quantities instead of a hard-coded 1 per line only when Quantity Tracking is enabled, and that option is not available with inclusive tax. If you need the unit count on the QuickBooks line as well as the amount, that is the toggle that decides it.

For the mapping side of that, see which QuickBooks product a priced line lands on.

Want to see this on your own Stripe data?

Start a free trial

Frequently asked questions

What is the difference between a Stripe product and a Stripe price?

A product is what you sell. A price is how much and how often you charge for it, including the currency and the rule used to turn a quantity into an amount. One product can have many prices (different currencies, different intervals, different tiers), and every price belongs to exactly one product.

Why is unit_amount null on my price?

Because the price is tiered rather than per-unit. Stripe documents `unit_amount` as "Only set if `billing_scheme=per_unit`". On a tiered price the amounts live in the `tiers` array instead, and that array has to be expanded in an API request before you can read it.

What is the difference between graduated and volume tiering?

Volume bills the entire quantity at the rate of the tier the quantity lands in. Graduated bills each tier separately and sums the results. On Stripe's own example tiers, twenty units cost 120 USD under volume and 127.50 USD under graduated. Same tier table, same quantity, one enum apart.

Can I change the amount on an existing Stripe price?

No. The update endpoint accepts only `active`, `currency_options`, `lookup_key`, `metadata`, `nickname`, `tax_behavior` and `transfer_lookup_key`. Changing what you charge means creating a new price and archiving the old one by setting `active` to false, which stops new purchases without altering existing invoices.

Is a lookup key a reliable way to identify a price in my records?

No, and this is a common trap. `transfer_lookup_key` "will atomically remove the lookup key from the existing price, and assign it to this price", so the same key can point at different prices over time. Two invoices raised against the same lookup key months apart may carry different amounts from different price objects. Use the price ID on the line.

Why was a customer with zero usage still charged?

If the price is tiered and the first tier carries a flat rate, Stripe "always bills the first flat rate tier when `quantity=0`". To bill nothing for no usage, Stripe's documented approach is an `up_to=1` tier whose `unit_amount` equals the flat rate, with `flat_amount` omitted.

Does the QuickBooks invoice show which pricing tier applied?

No. Acodei's documentation describes reproducing every line item, and tax lines, as your mapping settings allow, on the product your mapping selects. Nothing in it describes carrying a price's billing scheme or tier structure into QuickBooks, and the Stripe invoice line does not record that either. Retrieve the price by its ID if you need to reconstruct the arithmetic.

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