Stripe Subscription Item

What the object actually holds

The subscription item is small, and almost every field on it is something people expect to find on the subscription instead.

price is the price the customer is subscribed to, and quantity is described by Stripe as "The quantity of the plan to which the customer should be subscribed". subscription names the parent. Then three fields that quietly do a lot of work.

tax_rates is documented as "The tax rates which apply to this subscription_item", and Stripe adds the consequence directly: "When set, the default_tax_rates on the subscription do not apply to this subscription_item." That is an override, not an addition. An item with its own tax rate ignores the subscription default entirely.

discounts behaves similarly and has a documented order: "Subscription item discounts are applied before subscription discounts." So a bundle carrying both an item-level coupon and a subscription-level coupon applies them in a defined sequence, and the sequence changes the number.

billing_thresholds lets you "Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period", which means an individual item can trigger billing for the whole subscription.

The pair worth knowing about is current_period_start and current_period_end, described as the start and end of "this subscription item’s current billing period". The billing period is a property of the item, not only of the subscription.

Several items, one invoice

Stripe’s reason for the object is bundling. Subscribing a customer to multiple products "generates a single invoice each billing period that combines every price, and the customer only needs to make a single payment."

That single invoice comes with a hard constraint: "Using multiple products with a subscription results in a single invoice and payment, meaning all the prices for those products must use the same currency." One subscription cannot mix currencies, whatever its items are.

How many items fit depends on billing mode. Stripe states that "a subscription with flexible billing mode supports up to 100 subscription items, while a subscription with classic billing mode supports up to 20 subscription items."

Intervals are the other mode-dependent limit. Under classic billing mode, "all items in a subscription must have prices with the same interval and interval count." Under flexible billing mode, items "can have recurring prices with different intervals or interval counts. For example, a monthly price and an annual price can exist on the same subscription."

That last one matters for reading an invoice. A mixed-interval subscription produces invoices where some lines cover a month and others cover a year, on one document, for one customer.

Multiple items or multiple subscriptions

These are genuinely different structures and the choice is visible in your books forever.

Stripe describes the alternative plainly: a customer can hold several subscriptions at once, and "each subscription has its own separate billing period, invoice, and charge, even if the underlying prices have the same billing period." Each one also has "its own independent billing period, based on the billing cycle anchor of the subscription."

So two products on one subscription produce one invoice a period. The same two products on two subscriptions produce two invoices, potentially on different dates, from the same customer.

Stripe is explicit about the trap: "If you create multiple subscriptions with the same price, each subscription is independent, including payments and billing periods. If that’s not what you want, create a single subscription using multiple quantities instead."

For accounting, the practical difference is document count and matching. One invoice per period is easier to reconcile against one payment. Several subscriptions give you separate service periods at the cost of more documents to match.

The quantity is not always the number you think

Quantity is the item’s defining attribute and it has two documented ways of surprising you.

The first is a restriction. Stripe notes you can only specify a quantity when creating a subscription whose price has a recurring usage_type of licensed. A metered item does not carry a meaningful quantity in advance, because the number is not known until the period ends.

The second is transform_quantity, which lets you "instruct Stripe to transform the quantity before applying the per unit cost". Stripe’s worked example charges 10 USD for every 5 users: report 6 users and the item quantity billed is 2, not 6, because the system "divides the quantity by 5 and rounds up before calculating by the unit cost". Rounding can also be set to round down.

So the quantity you report and the quantity you are billed for can legitimately differ, and only one of them appears on the invoice. If your seat count and your invoice never agree, quantity transformation is the first thing to check.

Changing an item is where prorations come from

Stripe’s update endpoint is described as one that "Updates the plan or quantity of an item on a current subscription". That single sentence is the origin of most mid-cycle invoices.

One parameter on it is worth memorising because it silently rewrites data: "When changing a subscription item’s price, quantity is set to 1 unless a quantity parameter is provided." Switch a ten-seat item to a new price without restating the quantity and you now have a one-seat item. The invoice that follows is correct for what the subscription says and wrong for what the customer expects.

The timing of the resulting charge is controlled by proration_behavior, which Stripe documents as determining "how to handle prorations when the billing cycle changes... or if an item’s quantity changes", with a default of create_prorations. Its three values are always_invoice ("Always invoice immediately for prorations"), create_prorations (proration invoice items are created and "only be invoiced immediately under certain conditions"), and none ("Disable creating prorations in this request"). Our Stripe proration entry covers how the credit and charge amounts themselves are calculated.

One detail is easy to get wrong in the other direction. Removing an item is not cancelling: Stripe states that "Removing a subscription item from a subscription will not cancel the subscription." A delete also accepts clear_usage, which deletes all usage for the item and is "Allowed only when the current plan’s usage_type is metered".

Where the item shows up when you were not looking for it

Two places, both of which surprise people who think of the subscription as the unit.

Stripe chooses a statement descriptor by item order. Its documented rule is that "If a Subscription contains multiple items, then Stripe uses the first one in its items.data array (not the Invoice’s lines.data array) that has a custom statement descriptor." The descriptor your customer sees on their card statement is picked by item position, not by which item costs the most.

Cancellation dates can be set by item too. When a customer schedules a cancellation through the customer portal under flexible billing mode, Stripe sets cancel_at to "the maximum current_period_end across all subscription items", and notes that "when an item’s current_period_end changes, the cancellation date (cancel_at) isn’t updated." The subscription ends on a date that one of its items decided.