Adding Seats Mid-Cycle in Stripe: Proration and QuickBooks

A customer on your $20-per-seat plan has 10 seats. Halfway through the month they add 5 more. Stripe has to decide three things: whether to charge for the half month those 5 seats will be used, when to charge it, and on which invoice. One parameter, proration_behavior, makes all three decisions, and each of its three values leaves a different set of invoices for QuickBooks to receive.

Most teams never set it. The default works, so nobody looks until month-end, when April's seat revenue shows up on a May invoice, or a customer who added seats got them free for two weeks, or a support ticket asks why there was a $50 charge on the 16th.

Seat changes, synced as Stripe bills them. With Acodei's Invoice Sync, a paid-plan feature, a QuickBooks invoice is created when a Stripe invoice is finalized, with its lines reproduced as your mapping settings allow, and the payment is applied when it is paid. Start a free trial.

This post walks through what Stripe does when a seat count changes mid-cycle, the three values of proration_behavior side by side with real numbers, downgrades and the credit trap, and what to check in QuickBooks for each choice.

What Stripe does when the seat count changes

In Stripe, a seat count is the quantity on a subscription item. Stripe's quantities guide calls this "per-seat licensing, which has a linear cost increase: 10 uses incurs a cost of 10 times the base price." It also says you prorate quantities "when the subscription changes. This includes when you change subscription quantities."

A proration is Stripe's word for charging "a percentage of a subscription's cost to reflect partial use." Stripe's prorations guide lists changing an item's quantity as one of the updates that create one by default.

Four facts from that guide drive everything below:

• The amount is fixed at the moment of the change. "The prorated amount is calculated as soon as the API updates the subscription," using the current billing period's start and end.
• It is precise to the second. "By default, Stripe calculates prorations down to the second."
• It is usually two lines, not one. One is a credit for unused time at the old quantity. The other is a debit for the remaining time at the new quantity.
• It does not move money by itself. "Negative prorations aren't automatically refunded and positive prorations aren't immediately billed, although you can do both manually."

That last point is where proration_behavior comes in. It decides what happens to those two lines after Stripe calculates them.

The three values of proration_behavior

Stripe's update subscription reference says the parameter "Determines how to handle prorations when the billing cycle changes... or if an item's quantity changes." There are three values.

create_prorations (the default). Stripe creates the proration items and leaves them pending. In the reference's words, "the prorations are created but not automatically invoiced." They wait for the next invoice, which for most subscriptions is the renewal. The prorations guide adds that they are "only invoiced immediately under certain conditions," such as a change that resets the billing cycle.

always_invoice. Stripe creates the prorations, invoices them straight away and attempts to collect. The reference describes it as the way to "create prorations, automatically invoice the customer for those proration adjustments, and attempt to collect payment."

none. No proration items at all. The prorations guide says that "customers are billed the full amount at the new price when the next invoice is generated." There is no switch that turns prorations off for good: "No parameter turns off all future prorations for a subscription." You have to pass none on every request that would create one.

Worked example: 10 seats to 15, halfway through the month

The setup:

• A plan at $20 per seat per month, billed on the 1st.
• The customer has 10 seats, so the April 1 invoice was $200.
• The April 1 to May 1 period is 30 days.
• At midnight on April 16, with 15 days left, the customer goes to 15 seats.
• Cards are charged at Stripe's standard rate for domestic cards: 2.9% + 30¢ per successful transaction.

Stripe calculates two proration lines:

Line	Calculation	Amount
Unused time on 10 seats (credit)	10 × $20 × 15/30	-$100.00
Remaining time on 15 seats (debit)	15 × $20 × 15/30	+$150.00
Net proration		+$50.00

What happens next depends on the value you passed.

	create_prorations	always_invoice	none
Invoice on April 16	None	$50.00 (the two proration lines)	None
Invoice on May 1	$350.00 (renewal $300 + proration lines)	$300.00 (renewal only)	$300.00 (renewal only)
Total billed for April 16 to May 31	$350.00	$350.00	$300.00
Card fees	$10.45	$1.75 + $9.00 = $10.75	$9.00
Invoices in QuickBooks with Invoice Sync	1	2	1

Three things stand out.

create_prorations and always_invoice bill the same money on different dates. Both collect $350. The difference is whether April's $50 of extra seat time lands on an April invoice or a May one. If you keep your books on an accrual basis and recognize revenue by invoice date, the default moves $50 of April revenue into May. On one customer that is noise. On a seat-based business where customers add seats all month, it is a systematic shift.

always_invoice costs an extra fixed fee per change. Every immediate invoice is another card charge, and every card charge carries the 30¢. Here that is $10.75 against $10.45. A customer who adjusts seats weekly produces four extra charges a month. If you are on Stripe Billing's pay-as-you-go pricing, its 0.7% of Billing volume is the same in both cases, because the billed total is the same.

none gives the seats away. The customer used 5 extra seats for 15 days and was never billed for them. That is $50 of revenue that exists nowhere: not in Stripe, not in QuickBooks. Sometimes that is the policy you want, for example a goodwill increase or a migration. If it is not deliberate, it is a leak, and no report will show it, because nothing was ever invoiced.

Where the proration lines show up, and what their dates say

Under create_prorations, the May 1 invoice carries three lines: the renewal for May, and the two proration lines for April 16 to May 1. Stripe's invoice line item reference explains why they cover different windows. For subscription lines the period "is the subscription period." For prorations, it "starts when the proration was calculated, and ends at the period end of the subscription."

So one invoice, dated May 1, describes two spans of time: a full May for the renewal and half of April for the prorations. If you use line-level service dates for revenue recognition, the proration lines belong to April even though the invoice is May's.

To find the prorations on an invoice programmatically, Stripe points to parent.subscription_item_details.proration on the invoice line item. It is true for proration lines.

The quantity on a proration line is not the seats you added

Stripe's line item reference has a detail that catches anyone who reads the Qty column: "If the line item is a proration or subscription, the quantity of the subscription that the proration was computed for."

In the example, the credit line carries quantity 10 and the debit line carries quantity 15. Neither says 5, the number of seats the customer actually added. The 5 only exists as the difference between them.

This matters if you track seat counts in QuickBooks. Acodei's Invoice Sync has a Quantity Tracking option, enabled on the backend and off by default, that pushes Stripe quantities onto QuickBooks invoice lines instead of a hard-coded 1. It is not available with inclusive tax. With it on, those proration lines carry Stripe's 10 and 15. The invoice quantity post covers the broader trade-off of turning quantity tracking on.

always_invoice: the immediate invoice and a failed payment

An always_invoice change creates an invoice outside the renewal schedule. In Stripe's invoice object reference, the billing_reason value subscription_update is described as "A subscription was updated." Check it on your first one and filter on it if you report renewals and mid-cycle changes separately. The billing_reason post lists every value and what it means for your books.

The harder question is what happens if the immediate charge fails. Stripe's change-price guide is direct: "When billing is performed immediately, but the required payment fails, the subscription change request succeeds and the subscription transitions to past_due." The customer has the 15 seats, and you have an unpaid $50 invoice.

Stripe's suggested fix is to "Combine this setting with pending updates so the subscription doesn't update unless payment succeeds on the new invoice." You do that by passing payment_behavior as pending_if_incomplete. The update reference says that if payment fails, "Stripe creates a pending update, which applies only if the payment eventually succeeds." The pending update glossary entry covers how long that wait lasts and what happens to the invoice if it expires.

For the books, an unpaid immediate invoice is a receivable like any other. With Invoice Sync on, the QuickBooks invoice is created when the Stripe invoice is finalized, so it sits open in Accounts Receivable until Stripe reports it paid. The payment is then created and applied to it. Acodei's documentation notes that applying synced payments relies on QuickBooks' Automatic Application setting being on.

Downgrades: the same mechanics in reverse, plus a trap

Now run it the other way. The customer has 15 seats and drops to 10 on April 16.

• Unused time on 15 seats (credit): 15 × $20 × 15/30 = -$150.00
• Remaining time on 10 seats (debit): 10 × $20 × 15/30 = +$100.00
• Net: -$50.00

Under create_prorations, Stripe's update reference describes the result: "a downgrade generates a credit that is applied to the next invoice." The May 1 invoice is the $200 renewal minus the $50 net proration, so $150. That is usually the cleanest outcome for the books: one positive invoice, with the credit visible as its own lines.

Under always_invoice, the immediate invoice nets to a credit, and Stripe does not refund it. "Negative prorations aren't automatically refunded." If your policy is to give money back on a downgrade, issue the refund yourself. If it is not, always_invoice on a downgrade just creates a negative invoice nobody needed. A practical pattern is to pass always_invoice on increases and create_prorations on decreases.

The trap: credits for time nobody paid for. The prorations guide warns that Stripe calculates prorations "assuming that any previous invoices for the subscription will eventually be paid." If the April invoice is still unpaid when the customer downgrades, "they might receive a credit for unused time on the higher-priced plan, even if they haven't paid for that time yet." Stripe's advice is to pass none when the latest invoice is unpaid, then either create a one-off invoice for any new charges or reset the billing cycle anchor to now. Both "can lead to double payment if the customer eventually pays the old invoice," so void the old invoice. The billing cycle anchor post covers what a reset does to the invoice sequence.

Preview the charge before you make the change

You do not have to guess what a seat change will cost. A Stripe preview invoice returns the next invoice, including the proration lines, without changing anything. The prorations guide recommends it so you can "confirm the changes with the customer before modifying the subscription."

Because prorations are calculated to the second, the previewed amount can drift by the time you apply the change. Stripe's fix: "pass in a subscription_details.proration_date value when creating a preview. When you update the subscription, pass the same date using the proration_date parameter." The update reference adds that proration_date "can also be used to implement custom proration logic, such as prorating by day instead of by second."

Prorating by day is worth considering if your support team explains charges to customers. A $50.00 proration explains itself. One that comes out at $48.72 because the change happened at 9:14 in the morning instead of midnight generates a ticket.

Billing mode changes some credit amounts

One more variable. Stripe calculates credit prorations differently depending on the subscription's billing mode. The prorations guide documents a case where the same sequence of changes produces an invoice total of -3.34 USD under classic and a different credit under flexible, because flexible mode "creates a credit proration based on the last price billed for the subscription item."

Stripe's documented example of the gap is a credit calculated for a price the customer never paid, after an earlier change made with none. Mixing none and prorated changes on the same subscription is where the two modes part ways, which is one more reason to pick one approach and apply it consistently.

Five mistakes to avoid

1. Leaving the default without deciding. create_prorations moves mid-cycle seat revenue onto the next invoice date. That may be fine. Make it a decision, not an accident.
2. Using none to avoid confusing invoices. It avoids them by not billing for the seats at all. If you want fewer invoices, use create_prorations, which still bills the time.
3. always_invoice without pending_if_incomplete. A failed charge leaves the customer with the extra seats, the subscription past due and an unpaid invoice in Accounts Receivable.
4. always_invoice on downgrades. It produces a negative invoice that Stripe will not refund. Use create_prorations for decreases unless you intend to refund.
5. Reading proration quantities as seats added. The line quantities are the old and new totals (10 and 15), not the change (5).

If customers change their own seat counts, the same questions apply through the Stripe customer portal. Frequent changes have a limit of their own: Stripe warns that "Updating the quantity on a subscription many times in an hour may result in rate limiting" and suggests usage-based billing for quantities that change constantly.

FAQ

What does proration_behavior do in Stripe?

It decides what Stripe does with the proration it calculates when a subscription changes mid-cycle, including a quantity change. create_prorations (the default) creates the proration items and leaves them for the next invoice. always_invoice invoices them immediately and attempts payment. none creates no prorations, so the customer pays the new price from the next invoice.

Does Stripe charge immediately when a customer adds seats?

Not by default. With create_prorations, the charge for the rest of the current period waits for the next invoice, usually the renewal. To charge immediately, pass proration_behavior as always_invoice on the update.

Does Stripe refund a downgrade automatically?

No. Stripe states that "Negative prorations aren't automatically refunded." With the default behavior, the credit reduces the next invoice. If you want to return the money, refund it yourself.

Why is the quantity on a proration line 15 when the customer only added 5 seats?

Stripe's line item reference says the quantity on a proration line is "the quantity of the subscription that the proration was computed for." A 10-to-15 change produces a credit line with quantity 10 and a debit line with quantity 15. The seats added are the difference.

How do seat changes appear in QuickBooks?

With Acodei's Invoice Sync, a finalized Stripe invoice becomes a QuickBooks invoice with its lines reproduced as your mapping settings allow, each line using the product from Multiple Product Mapping if enabled or the default product otherwise. An invoice made up only of $0 lines is not synced. Under create_prorations, the proration lines arrive on the renewal invoice. Under always_invoice, they arrive as their own invoice on the day of the change. Under none, there are no proration lines to receive.

The point

A seat change is a small event that forces three decisions: whether to bill the partial period, when, and on which invoice. create_prorations bills it later, always_invoice bills it now and none doesn't bill it. Pick the behavior on purpose, pair always_invoice with pending_if_incomplete, keep it off downgrades, and remember that a proration line's quantity is a total, not a change.

Every finalized Stripe invoice, in QuickBooks. Acodei syncs finalized Stripe invoices into QuickBooks Online, including the mid-cycle invoices always_invoice creates, and applies each payment to the invoice it paid. Start a free trial.