Proration

When a customer upgrades or downgrades, Rollo lets you schedule the new plan for the next period and optionally credit unused time as free days on the current period—without inventing a second invoice model.

How Rollo approaches plan changes

Call change-plan with the target recurring price. Rollo stores a pending price and amount on the subscription. At period end, renewals use the pending plan. If you pass credit_days, the current period is extended immediately—functionally a credit for unused time on the old plan.

This keeps upgrades predictable: no surprise mid-cycle invoice unless you choose to create a separate checkout for an immediate charge.

Calculating credit days

A simple approach: unused fraction of the period × days in the period, rounded down. For example, 10 days left on a 30-day month ≈ 10 credit days when moving to a similar-priced plan. Adjust for large price deltas in your application logic.

Dashboard

On Subscriptions, open Change plan, pick a recurring catalog price, and optionally enter credit days. Clear a pending change anytime before the period ends.

API

POST /v1/subscriptions/sub_.../change_plan
Authorization: Bearer rk_live_...

{
  "price": "price_...",
  "credit_days": 10
}

{
  "pending_amount": 7900,
  "credit_days": 10
}

Immediate upgrades

For an immediate charge to the new price, create a one-time Checkout Session for the prorated difference, then schedule the plan change with zero or fewer credit days. Keep the two steps explicit so customers see a clear receipt.