Subscription plan changes and proration
A subscriber who upgrades mid-month should pay for the better plan only for the time they use it, and one who downgrades should keep what they already paid for. Flint handles both. Every plan change and seat change takes a billing_starts timing that says whether to charge now, how much, and whether the billing date moves. Flint calculates the prorated amount to the second, charges it in the same call, and applies the change only if the payment succeeds.
This guide assumes you have subscriptions on plans, as in Subscription billing.
Choose when a change takes effect#
Two routes make changes, and both take billing_starts:
POST /v1/subscriptions/{subscription_id}/change-planmoves a subscription to another plan, or to its own plan's current prices.POST /v1/subscriptions/{subscription_id}/change-quantitychanges seats or other line quantities and keeps the plan.
billing_starts | Charged today | Billing date | New terms apply |
|---|---|---|---|
prorated_now | The new terms for the rest of the period, less credit for unused paid time | Stays the same | Now, if the payment succeeds |
now | A full new period on the new terms, less credit for unused paid time | Moves to today | Now, if the payment succeeds |
next_renewal | Nothing | Stays the same | Now, billed from the next charge, with no credit |
period_end | Nothing | Stays the same | At the next charged renewal |
Pick by what the subscriber is doing:
- Upgrade and keep the billing date:
prorated_now. This is what most SaaS products want. - Upgrade and restart the period today, or switch from monthly to yearly billing:
now. - Downgrade and keep the paid plan until renewal:
period_end. - Change the plan right away and start the new price at the next charge:
next_renewal. Nothing is credited or charged for the current period.
change-plan accepts all four. change-quantity accepts prorated_now, next_renewal, and period_end.
How proration is calculated#
A prorated_now change, a now change, and a quantity change billed now all credit what the subscriber paid for the part of the current period they won't use:
credit = round(paid * unused seconds / period seconds)
paidis what the subscriber paid for the current period's items: the line subtotals less line discounts on the order that paid the period, before tax and shipping, less any refund on that order. If more than one order paid for the period, such as an earlier prorated change, Flint credits each one over the time it covered.- Unused time runs from the change to
current_period_end_at. The period runs fromcurrent_period_start_attocurrent_period_end_at. - Rounding is half up, to the cent, once for each term.
The credit is 0 when no Flint order paid the period, such as an imported subscription before its first Flint charge.
What the subscriber pays depends on the timing:
prorated_now: charge = round(new items * unused seconds / period seconds) - credit
now: charge = new items for a full period - credit
new items is the price of every item on the subscription after the change, at its cycle price and after the cycle's promotions, before tax and shipping. Flint calculates tax on the result and doesn't credit shipping.
On the order, the credit appears as a discount named "Unused time on" and the old plan's name, with source: "plan_change_credit". A prorated_now charge also carries a discount with source: "proration" for the part of the period that has already passed, named "Elapsed time in current period".
Example: an upgrade, four ways#
A subscriber on a $29.00 monthly plan paid for October 1 to November 1, 31 days. At midnight UTC on October 13, they upgrade to a $49.00 plan, with 19 of the 31 days unused:
credit = round(2900 * 19 / 31) = round(1777.42) = 1777
billing_starts | Charged October 13 | Next renewal |
|---|---|---|
prorated_now | $12.26 | $49.00 on November 1 |
now | $31.23 | $49.00 on November 13 |
next_renewal | $0.00, on the $49.00 plan from today | $49.00 on November 1 |
period_end | $0.00, on the $29.00 plan until then | $49.00 on November 1 |
All amounts are before tax.
prorated_now: keep the billing date#
Flint charges the new plan for the 19 days left and credits the unused $29.00 time:
new items for the rest of the period = round(4900 * 19 / 31) = round(3003.23) = 3003
charge = 3003 - 1777 = 1226
curl -X POST https://api.withflintpay.com/v1/subscriptions/sub_1kmn0aExample/change-plan \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: upgrade-sub-ada-001" \
-d '{
"subscription_plan_id": "plan_1kmn0bExample",
"billing_starts": "prorated_now"
}'
{
"data": {
"billing_starts": "prorated_now",
"subscription": {
"subscription_id": "sub_1kmn0aExample",
"subscription_plan_id": "plan_1kmn0bExample",
"status": "active",
"recurring_subtotal_money": {"amount": 4900, "currency": "USD"},
"current_period_start_at": "2026-10-01T00:00:00Z",
"current_period_end_at": "2026-11-01T00:00:00Z",
"next_billing_at": "2026-11-01T00:00:00Z",
"completed_cycles": 4
},
"order": {
"order_id": "ord_1kmn0bExample",
"subscription_cycle": 4,
"discounts": [
{
"customer_facing_name": "Elapsed time in current period",
"source": "proration",
"applied_money": {"amount": 1897, "currency": "USD"}
},
{
"customer_facing_name": "Unused time on Starter",
"source": "plan_change_credit",
"applied_money": {"amount": 1777, "currency": "USD"}
}
],
"pricing_amounts": {
"subtotal_money": {"amount": 4900, "currency": "USD"},
"discount_money": {"amount": 3674, "currency": "USD"},
"total_money": {"amount": 1226, "currency": "USD"}
}
},
"order_payment_attempt": {
"order_payment_attempt_id": "opat_1kmn0bExample",
"status": "succeeded"
}
},
"request_id": "req_..."
}
The period, next_billing_at, billing_anchor_day, and completed_cycles stay the same. The charge is an order for the current subscription_cycle, not a new renewal, and it ships nothing, so neither plan can have lines that ship. The interval must stay the same: to move from monthly to yearly, use now or period_end.
now: start a new period today#
Flint starts a full $49.00 period on October 13 and subtracts the same credit:
charge = 4900 - 1777 = 3123
The new period runs from October 13 to November 13, billing_anchor_day moves to the 13th, and the charge is a regular renewal order with the next subscription_cycle. On a subscription that ships, that order ships too. A now change uses one cycle of each repeating promotion, because it's a charged cycle.
now is also how to move a subscriber to yearly billing mid-month. On the same October 13, moving to a plan that offers $290.00 a year, with billing_interval: "yearly" and billing_interval_count: 1, charges $290.00 less the $17.77 credit, $272.23, and the next renewal is October 13 of the following year.
Downgrades#
A downgrade usually costs less for the rest of the period than the credit for what the subscriber already paid. Flint holds no credit balance to carry the difference, so a change whose net would be negative is refused with 409 ACTION_NOT_ALLOWED, reason credit_exceeds_charge, and nothing changes.
Take the reverse of the example: a subscriber on the $49.00 plan moves to $29.00 on October 13.
prorated_nowis always refused for a cheaper plan: the $29.00 plan for 19 days, $17.77, is less than the $30.03 credit.nowis refused early in the period, because the credit is larger then. On October 13 the $30.03 credit is more than the $29.00 plan costs. On October 25, with 7 days left, the credit is $11.06, sonowcharges $29.00 less $11.06, $17.94, and starts a new period.period_endkeeps the $49.00 plan and its access until November 1, then bills $29.00. Use it for downgrades.
To give part of a period back as well, refund the order that paid the period with the refunds API.
Change seats and quantities#
Per-seat pricing is a plan line with allow_quantity_adjustment: true. Choose the seat count at signup as in Choose seats at signup, and change it later with change-quantity, naming each subscription_line_item_id and its new quantity:
curl -X POST https://api.withflintpay.com/v1/subscriptions/sub_1kmn0aExample/change-quantity \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: seats-sub-ada-001" \
-d '{
"billing_starts": "prorated_now",
"line_items": [{"subscription_line_item_id": "sli_1kmn0aExample", "quantity": 10}]
}'
line_items takes 1 to 50 of the subscription's lines, each with a quantity from 1 to 9,999. The plan, prices, and other lines stay as they are.
billing_starts | What happens |
|---|---|
prorated_now | Charges the prorated difference now and keeps the period. Use it to add seats. |
next_renewal | Changes the quantities now without charging. The next renewal bills the new count. |
period_end | Keeps the current quantities until the next billing boundary, then applies the new ones. Use it to remove seats at renewal. |
A seat decrease with prorated_now has a negative net and returns credit_exceeds_charge, as a downgrade does.
Example: adding seats twice in one period#
A subscriber pays $10.00 a seat and renewed 5 seats, $50.00, for September 1 to October 1, 30 days. On September 16, halfway through, they go to 10 seats:
new items = round(10 * 1000 * 15 / 30) = 5000
credit = round(5000 * 15 / 30) = 2500
charge = 5000 - 2500 = 2500
With a quarter of the period left, they go to 12 seats. Two orders paid for that time, so Flint credits both: the renewal's $50.00 covered the whole period, and the $25.00 change covered its second half.
new items = round(12 * 1000 * 1/4) = 3000
credit = round(5000 * 1/4) + round(2500 * 1/2) = 1250 + 1250 = 2500
charge = 3000 - 2500 = 500
Across the period the subscriber pays $50.00, $25.00, and $5.00 plus tax, and the October 1 renewal bills 12 seats, $120.00.
Buyers change their own seats#
In your account pages, a buyer with a full customer session changes seats with POST /v1/me/subscriptions/{subscription_id}/change-quantity and an Idempotency-Key. They can change only the line with allow_quantity_adjustment: true, within the min_quantity and max_quantity frozen on the subscription at signup, with billing_starts of prorated_now or period_end. The update_quantity entry in buyer_actions says whether they can.
When the charge succeeds or fails#
A prorated_now or now change returns 200 with billing_starts, subscription, order, and order_payment_attempt, even when the card is declined. Read order_payment_attempt.status:
succeeded: the change is in place.failed: Flint closed the unpaid order, and the subscription is exactly as it was. Update the card, then send the change again with a newIdempotency-Key.
When the net charge is 0, order and order_payment_attempt are null and the change still applies. next_renewal and period_end charge nothing, so both are always null for them.
Send a new Idempotency-Key for each change you mean. A second key is a second change, and with now or prorated_now it charges again. Replaying the same key returns the stored result.
When a prorated change is refused#
A prorated_now plan change or quantity change returns 409 ACTION_NOT_ALLOWED and changes nothing when Flint can't compute or collect the charge:
reason | Meaning |
|---|---|
credit_exceeds_charge | The net is negative, such as a downgrade or a seat decrease. Use period_end, or next_renewal for quantities. |
minimum_charge | The net is above zero but below the card minimum: $1.00, or your higher minimum. details[0].minimum_money has it. Make a larger change, or bill it at the next renewal. |
paid_period_required | No Flint order paid the current period, such as an imported subscription before its first Flint charge. |
in_progress | A renewal, another change, or a refund on an order that paid the period is still running. Send the change again once it finishes. |
unsupported_state | The subscription isn't active. |
trial_in_progress | The subscription is in a free trial. Use next_renewal. |
external_billing_schedule | Your integration sets this subscription's billing dates. |
plan_change_scheduled | A quantity change while a period_end change is pending. Clear or replace it first. A prorated_now plan change clears the pending change instead. |
already_applied | The quantities are already what you sent. |
A now change needs what Order now needs: an active subscription on a flint schedule, not set to cancel, with nothing else charging it. A plan in another currency returns 400 INVALID_REQUEST. Change a subscriber's plan lists every refusal.
Preview before you charge#
Show the amount before the subscriber confirms. POST /v1/subscription-previews runs the same checks as the change and saves nothing:
curl -X POST https://api.withflintpay.com/v1/subscription-previews \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"mode": "plan_change",
"subscription_id": "sub_1kmn0aExample",
"subscription_plan_id": "plan_1kmn0bExample",
"billing_starts": "prorated_now"
}'
- Plan change:
mode: "plan_change"withsubscription_plan_idandbilling_starts.credit_adjustment_moneyis the credit, andrenewal.total_moneyis what the change charges today fornowandprorated_now, or the boundary charge forperiod_end. - Quantity change:
mode: "quantity_change"withbilling_starts: "prorated_now"andline_items. - Buyers: the same modes on
POST /v1/me/subscription-previewswith a customer session.
The preview measures unused time when you call it, so the charge a moment later can be slightly lower.
Scheduled changes#
period_end freezes the target plan's lines, prices, interval, and quantities when you schedule it, and applies them at the next charged renewal. The subscription reports the pending change in scheduled_plan_change:
{"scheduled_plan_change": {
"subscription_plan_id": "plan_1kmn0cExample",
"billing_interval": "monthly",
"billing_interval_count": 1,
"recurring_subtotal_money": {"amount": 2900, "currency": "USD"},
"effective_at": "2026-11-01T00:00:00Z",
"requested_by": "merchant",
"scheduled_at": "2026-10-13T09:12:00Z"
}}
- Grant access from
subscription_plan_id, the plan the subscriber is on now, never from the pending snapshot. - The change applies before the renewal is charged, so a failed renewal and its retries bill the new plan. Editing or archiving the target plan afterward doesn't change it.
- Replace it by calling
change-planagain withperiod_end. Clear it withPATCH /v1/subscriptions/{subscription_id}and{"scheduled_plan_change": null}. Canceling the subscription also clears it. - While it's pending, quantity, cadence, and line-item changes return
plan_change_scheduled. - Skips and pauses delay it to the next charged renewal; see Pause, skip, and resume subscriptions.
A price change scheduled with next_renewal or period_end within the renewal notice window, 3 days before most renewals and 30 days before yearly ones, takes effect on the following charged renewal, and the upcoming charge keeps its current terms. The response reports billing_starts: "period_end" and the date in effective_at.
Flint sends no plan change email. Tell the subscriber before a new price takes effect.
Events#
prorated_nowandnowsendsubscription.plan_changedandsubscription.payment_succeeded, and the order sendsorder.paid. A quantity change billed now sends the same. With a net of 0, onlysubscription.plan_changed.next_renewalsendssubscription.plan_changed.period_endsendssubscription.plan_change_scheduledwhen you schedule or replace it, andsubscription.plan_changedwhen it takes effect. Clearing it sendssubscription.plan_change_canceled.- A declined change sends no subscription event, because nothing changed.
Events carry the new snapshot but not the previous plan, so compare subscription_plan_id with the plan you provisioned.
Let buyers change plans#
List the plans a subscriber can move to in the plan's plan_change_options, each with its own billing_starts, such as prorated_now for upgrades and period_end for downgrades. Buyers change plans with POST /v1/me/subscriptions/{subscription_id}/change-plan and see their options on the subscription. Let buyers change plans covers the setup.
Coming from Stripe Billing#
<!-- Stripe facts from https://docs.stripe.com/billing/subscriptions/prorations, checked 2026-11-21. -->
Stripe's default proration_behavior, create_prorations, adds proration items to the next invoice: positive prorations aren't billed right away and negative ones aren't refunded automatically. always_invoice bills them at once.
Flint's prorated_now charges the difference in the same call and applies the change only once the charge succeeds, so a declined card leaves the subscription as it was. Flint keeps no credit balance: a change that would owe the subscriber money is refused, and period_end keeps the paid plan until renewal instead. Both prorate to the second. Migrating from Stripe maps the rest of Stripe Billing.
Related guides#
- Subscription billing: plans, seats at signup, and first-period proration for anchored billing dates.
- Failed renewal payments and dunning: what happens when the next renewal fails.
- Pause, skip, and resume subscriptions: breaks in billing.
- Refunds: give part of a period back.
Ready to bill upgrades and seats the day they happen? Create a Flint account and preview your first plan change in a sandbox.