Skip to main content
Whenever a subscription’s price changes mid-cycle — typically because the customer switched to a different product or changed seats — there’s an unused portion of the current billing period that has already been paid for. Proration is how Polar reconciles that difference. You pick the proration behavior either at the organization level (as the default) or per API call.

​
Proration behaviors

Polar supports three standard proration behaviors:

​
Invoice Immediately (invoice)

The subscription is updated immediately and Polar invoices the prorated difference right away. If the update is an upgrade the customer is charged; if it’s a downgrade they’re credited on the new invoice. Use this when you want money to change hands at the same time as the change — for example, on upgrades where you want to collect the extra revenue now.

​
Next Invoice (prorate)

The subscription is updated immediately, but the prorated difference is carried over and applied on the next scheduled invoice instead of triggering a charge now. The customer’s billing cycle is unchanged. This is typically the smoothest experience for the customer: their plan changes instantly, and they see the adjustment on their regular renewal invoice.
If the billing interval changes (for example, monthly to yearly), prorate is promoted to invoice automatically — there’s no “next invoice” on the old cycle to defer the difference to.
For invoice and prorate, the subscription update is applied only if the immediate payment (if any) succeeds. If the payment fails, the API returns an error and the subscription stays unchanged.

​
Next Period (next_period)

The change is not applied immediately. It’s scheduled as a pending update and applied at the start of the next billing period. No proration charge or credit is issued — the new plan simply takes effect on renewal. While a next_period update is pending, the subscription’s pending_update field describes the scheduled change. Submitting a new update always supersedes the pending one: if you scheduled a next_period change and then make another update with invoice or prorate, the pending update is discarded and the new change is applied right away. This behavior is the safer default for downgrades where you don’t want to issue credits, and for any case where you want the current period’s terms to stay intact.

​
Opting out of proration (reset)

The subscription switches to the new plan immediately, Polar invoices the full price of the new plan right away, and the billing cycle is reset to start now. No proration is applied: the customer isn’t credited for the unused portion of the old period, and they aren’t charged a prorated amount — they pay the full new price and begin a fresh billing period. Because the cycle restarts, the new period’s anchor day becomes the day the change was made, and all future renewals follow the new schedule. Use this when a plan change should behave like a brand-new subscription — for example, when an upgrade should restart the commitment period rather than carry over the current one.
The reset proration behavior is currently in preview. You’ll only be able to use the reset proration behavior if you are on a paid plan.

​
Setting the default behavior

Each organization has a default proration behavior that applies whenever you don’t pass an explicit proration_behavior on an API call — including plan changes customers initiate from the Customer Portal. You can change it from Settings → Subscriptions in the dashboard, or via the Update Organization API.

​
Overriding per update

Every subscription update that changes the price — a product change or a seat change — accepts an optional proration_behavior that overrides the organization default for that single call: 
curl --request PATCH \
  --url https://api.polar.sh/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "<product_id>",
    "proration_behavior": "invoice"
  }'
Valid values are invoice, prorate, and next_period. If your organization has access to the preview reset behavior, you can pass reset here as well.

​
How the prorated amount is calculated

Polar prorates on a per-second basis. If S seconds remain out of T total seconds in the current billing period:
  • Unused credit on the old plan: old_plan_price * S / T
  • Charge on the new plan for the remainder: new_plan_price * S / T
  • Prorated difference: the new-plan remainder minus the old-plan unused credit
For an upgrade the difference is positive, so the customer is charged; for a downgrade it’s negative, so the customer is credited.

​
Upgrade

A customer subscribed to a $5/month plan on a 30-day month (2,592,000 seconds total). After 1 day (86,400 seconds elapsed, 2,505,600 seconds remaining) they upgrade to a $20/month plan.
  • Unused credit on the 5 plan: `\5 * 2,505,600 / 2,592,000 = $4.83`
  • New charge for the remaining 2,505,600 seconds on the 20 plan: `\20 * 2,505,600 / 2,592,000 = $19.33`
  • Prorated difference: $14.50
With invoice, that $14.50 is charged immediately. With prorate, it’s added to the next monthly invoice (which is also the new $20 charge for the next cycle).

​
Downgrade

A customer subscribed to a $20/month plan on a 30-day month (2,592,000 seconds total). After 1 day (2,505,600 seconds remaining) they downgrade to a $5/month plan.
  • Unused credit on the 20 plan: `\20 * 2,505,600 / 2,592,000 = $19.33`
  • New charge for the remaining 2,505,600 seconds on the 5 plan: `\5 * 2,505,600 / 2,592,000 = $4.83`
  • Prorated difference: -$14.50 (credit to the customer)
With invoice, a credit invoice for $14.50 is issued immediately. With prorate, the credit is applied on the next invoice.
Because proration is computed from the exact number of seconds remaining, the change time-of-day matters: upgrading at noon credits a different amount than upgrading at midnight. Polar always uses the real length of the current billing period (so 28-, 29-, 30-, and 31-day months are all handled exactly).