Glossary

Stripe Mixed Interval Subscription

A Stripe mixed interval subscription is one subscription whose items carry prices with different recurring intervals, so each item keeps its own billing period and the subscription no longer has a single cycle.

Also called: mixed interval subscription, mixed-interval subscription, monthly and annual on one subscription, different billing intervals

Start a free trial View Pricing

Definition

For years a Stripe subscription had one billing period, and every item on it renewed together. Flexible billing mode removed that rule. A mixed interval subscription is what you get when it is gone: one subscription, one customer, one currency, and items that renew on different clocks.

Stripe describes the shape plainly. You can "include multiple subscription items with different prices and billing periods on a single subscription and Stripe automatically handles invoice generation." The worked example in its documentation is an annual flat rate alongside a monthly usage-based fee, both as items on the same subscription.

The reason this matters to anyone reading the books rather than writing the integration is that two familiar assumptions stop holding at once. The subscription no longer has a billing period of its own in any useful sense, and one renewal no longer means one invoice. Both facts show up in QuickBooks as documents, and neither announces itself.

Key points

+Requires flexible billing mode. Classic billing mode does not support it at all.
+Every item carries its own current_period_start and current_period_end.
+Stripe combines items on one invoice when their periods align and issues separate invoices when they diverge.
+Each item interval must be a multiple of the shortest interval on the subscription.
+Weeks and months have no equivalence, so a weekly item and a monthly item cannot share a subscription.
+Dunning is subscription-wide: one item failing collection can cancel all of them.

Each item keeps its own clock

Stripe moved the billing period down a level. Its documentation states that "each subscription item has its own current_period_start and current_period_end", and that "subscription items track their respective billing periods directly instead of as a top-level shared billing period on the subscription resource."

The subscription still reports a period, but it is derived rather than owned. Take Stripe’s own example: a subscription created on January 1 with a monthly, a bimonthly and a quarterly item. At creation the monthly item runs January 1 to February 1, the bimonthly to March 1, the quarterly to April 1, and the subscription reports January 1 to February 1.

After the February 1 renewal, Stripe says "the subscription’s current period adjusts to match the latest current_period_start and earliest current_period_end of all the items." The monthly item is now February 1 to March 1, the other two are unchanged, and the subscription reads February 1 to March 1. Cycle again and the subscription reads March 1 to April 1, while the quarterly item is still sitting in the period that began on January 1.

So the subscription period is a computed window over the items, and at no point is it the service period of anything you are actually selling.

One invoice, or several, depending on the month

This is the part that surprises people, and it is the part that changes your document count.

Stripe states the rule directly: it "generates a single, combined invoice when item-level billing periods align and separate invoices when billing periods diverge." Alignment is not a setting. It is whether the items happen to renew on the same date.

Walk Stripe’s two-item example, a 15 USD monthly price and a 100 USD quarterly price, both starting January 1. January 1 produces one invoice carrying both lines. February 1 and March 1 each produce an invoice for the monthly item only. April 1 is the month the clocks meet again, and Stripe’s documentation says that renewal "creates an invoice for both the monthly and quarterly item."

Count that over a year and one subscription produces twelve invoices, four of which carry two lines and eight of which carry one. Nothing about the customer or the contract changed. The number of documents is a function of arithmetic on the intervals.

The invoice period is not the service period

On the combined invoice, the two lines cover different lengths of time, and the invoice header does not describe either of them.

In Stripe’s example for that first January invoice, the monthly line carries a period of January 1 to February 1 and the quarterly line carries January 1 to April 1, while the invoice’s own period_start and period_end are both January 1. That is not a bug. Stripe defines the invoice-level fields as bookkeeping about the invoice rather than about the service: period_end is "the latest timestamp at which invoice items can be associated with this invoice", and the documentation then tells you where to look instead. "Use the line item period to get the service period for each price."

The line-level field is the real one. Stripe documents it as "the period this line_item covers. For subscription line items, this is the subscription period", and adds that if you have Stripe Revenue Recognition enabled, "the period will be used to recognize and defer revenue."

Anyone building a deferral schedule from an invoice date, or from the invoice-level period, will spread a year of revenue across a month on a mixed interval subscription. The number that would have been right is one level down.

The intervals have to line up

Mixed does not mean arbitrary. Stripe requires that "every item’s price interval (the combination of price.recurring.interval and price.recurring.interval_count) must be a multiple of the shortest price interval in the subscription", and says outright that "some price interval combinations aren’t supported."

It treats 1 week and 7 days as equivalent, and 12 months and 1 year as equivalent. Combinations it lists as supported include 1 month with 3 months, 1 month with 1 year, 1 day with 1 week, and 2 months with 4 months and 6 months.

The unsupported list is the useful half, because the rejections are not obvious. Stripe states there are no equivalences between week and month, week and year, day and month, or day and year. It also lists 2 months with 3 months, 4 months with 6 months, 1 week with 1 month, and 5 months with 1 year as unsupported combinations.

So a weekly add-on cannot sit on a subscription with a monthly base price, however natural that product sounds in a pricing meeting. Two months and three months fails for the same reason: neither is a multiple of the other.

What you give up to get it

Flexible billing mode is a one-way door. Stripe states that "you can’t migrate a subscription from flexible billing mode to classic billing mode", so a subscription converted to carry mixed intervals stays converted.

Four limitations are worth knowing before you sell the pricing model, all of them Stripe’s own.

Dunning is not per item. Stripe says that "if all retries for a payment fail, even if the failing payment is for an invoice related to only one of the items on the subscription", it "cancels the entire subscription and marks it as unpaid or past due, depending on your configured dunning settings." A card failing on a 15 USD monthly add-on can take the annual contract with it. Cancellation behaves the same way: "canceling a mixed interval subscription or schedule cancels all the subscription items, regardless of their interval."

The deprecated cancel_at_period_end cannot tell which item to use and "defaults to the earliest item period end", so Stripe directs you to cancel_at with min_period_end, max_period_end, max_billed_until, or an explicit timestamp.

Subscription schedules with mixed intervals "can’t calculate total iterations accurately", so phase length has to be set with duration instead.

And two surfaces do not support it at all: you "currently can’t create mixed interval subscriptions on Checkout Sessions", and you "can’t apply a retention coupon on mixed interval subscriptions through the customer portal."

What a mixed interval subscription looks like in QuickBooks

Acodei’s product documentation has no page on subscriptions, subscription items or billing intervals, and nothing in it describes reading an interval or a per-line service period. What it documents is the invoice, and on a mixed interval subscription the invoices are the whole story anyway.

When a Stripe invoice is finalized, Acodei creates a QuickBooks Invoice that reproduces every line item, and tax lines, as your mapping settings allow. When it is paid, by a successful charge, by a manual payment per your settings, or by a credit balance offset, a QuickBooks Payment Receipt or Credit Memo follows and is applied to the invoice created earlier. Each line takes the product returned by Multiple Product Mapping when that is enabled, and the default product otherwise.

Read against the Stripe behaviour above, that gives you the shape without any guessing. Stripe decides how many invoices exist and which lines sit on each one, and the documented Acodei trigger is the finalized invoice, one QuickBooks Invoice each. The documented exception is an invoice whose line items are all zero, which is not synced. So a subscription whose items renew on different dates produces a varying number of QuickBooks Invoices per quarter for a customer whose contract never changed.

What is not documented anywhere in the hub is a destination for a per-line service period. The nearest documented settings are the three mutually exclusive Service and Supply Date toggles, which are Admin-level and all off by default, and they are described by invoice date and Stripe supply date rather than by line period. If your revenue schedule depends on which dates reach which QuickBooks field, check one synced invoice in your own file rather than assuming.

Want to see this on your own Stripe data?

Start a free trial

Frequently asked questions

What is a mixed interval subscription in Stripe?

It is a single Stripe subscription carrying items whose prices have different recurring intervals, for example a monthly price and an annual price on the same subscription. Stripe supports it only in flexible billing mode. Each item keeps its own billing period, and Stripe generates invoices per item period rather than on one shared cycle.

Can one Stripe subscription bill monthly and annually at the same time?

Yes, in flexible billing mode. Stripe states that under classic billing mode all items in a subscription must have prices with the same interval and interval count, while items on a mixed interval subscription can have recurring prices with different intervals or interval counts.

Does a mixed interval subscription produce one invoice or several?

Both, at different times. Stripe generates a single combined invoice when item-level billing periods align and separate invoices when they diverge. A monthly item and a quarterly item starting on the same day share an invoice at creation, then the monthly item invoices alone for two months, and the two are combined again when the quarter turns.

What billing period does the subscription itself report?

A derived one. Stripe sets the subscription current period to the latest current_period_start and the earliest current_period_end across all items, so it tracks whichever item renews soonest. It is not the service period of any particular item, and a longer item can be mid-period while the subscription has already cycled twice.

Which period should a deferred revenue schedule use?

The line item period. Stripe documents the invoice-level period_start and period_end 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. On a combined invoice those line periods differ in length, which is exactly the case an invoice-date deferral gets wrong.

Can I put a weekly item and a monthly item on one subscription?

No. Stripe requires every item interval to be a multiple of the shortest interval on the subscription, and states there are no equivalences between week and month, week and year, day and month, or day and year. It also lists 2 months with 3 months and 4 months with 6 months as unsupported, since neither is a multiple of the other.

What happens if payment fails on only one item?

The whole subscription is affected. Stripe states that if all retries for a payment fail, even when the failing payment relates to an invoice for only one of the items, it cancels the entire subscription and marks it unpaid or past due depending on your dunning settings. Canceling a mixed interval subscription also cancels every item regardless of interval.

How does Acodei sync a mixed interval subscription to QuickBooks?

Through the invoices, like any other Stripe invoice. Acodei documents that a finalized Stripe invoice becomes a QuickBooks Invoice reproducing every line item as your mapping settings allow, and that a paid invoice produces a Payment Receipt or Credit Memo applied back to it. Nothing in Acodei’s documentation describes reading subscription intervals, so the number and shape of your QuickBooks documents follows whatever Stripe chose to invoice.

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