Upgrade Types and Timing
Immediate Upgrade
The subscription changes at the moment of the upgrade request. Stripe generates an invoice for the prorated amount (the unused portion of the current plan applied toward the new plan) and attempts payment off-session.
Proration formula:
|
Calculation |
Example |
|---|---|
|
Credit = current price × (remaining days ÷ paid days) |
$30/mo × (15 ÷ 30) = $15.00 credit |
|
Upgrade charge = new plan price − credit |
$60/mo − $15.00 = $45.00 charged |
|
Downgrade refund = credit − new plan price |
$15.00 − $8.00 = $7.00 credited to subscriber |
Deferred (Scheduled) Upgrade
The subscription changes at end of billing period. No proration. Full price of new plan billed from the next renewal date. Optionally: subscriber can gain access to new resource immediately, before billing transition.
Deferred upgrades are not affected by the off-session model change. They were already off-session in Piano billing. No change in payment behavior. The additional benefit in processing asynchronous payment methods with Stripe Billing, in case of payment failure instead of immediate cancellation grace period and Smart retries apply for all supported methods.
Upgrade payment failure by payment type
For BYOP async payment methods, the payment is initiated after the upgrade but confirmed or rejected days later (typically 2 to 5 days depending on the payment method). If that deferred payment fails:
|
Payment Type |
Upgrade Payment Fails |
Access Outcome |
|---|---|---|
|
Stripe-native (card, SEPA etc.) |
Grace period starts. Smart Retries activated. |
Access maintained during grace period. |
|
BYOP sync (immediate result) |
Grace period starts. Passive Churn Prevention retries activated. |
Access maintained during grace period. |
|
BYOP async (deferred result) |
Subscription cancelled immediately. No grace period. |
Access revoked on cancellation. |
Why BYOP async cancels immediately
BYOP async payments (such as direct debit or bank transfer) are processed on Piano's side, not Stripe's. Piano payment processing rules apply. In Piano billing, BYOP async upgrade payment failures resulted in immediate cancellation with no grace period. This behavior remains the same. If your publisher account uses BYOP async payment methods and supports upgrades, subscribers will be cancelled rather than put into grace period if their async upgrade payment fails. It is recommended to use Stripe Payments for async payment method processing which can be retried.
Upgrade Lifecycle Operations
For deferred upgrades, publishers can manage the lifecycle with the following operations:
|
Operation |
Who Can Trigger |
What It Does |
|---|---|---|
|
Suspend |
Subscriber or Admin |
Pauses a deferred upgrade. The current subscription expires at end of billing period if not resumed. |
|
Resume |
Subscriber or Admin |
Reactivates a suspended upgrade. Stripe schedule restored. Auto-renewal re-enabled. |
|
Cancel |
Admin only |
Cancels the deferred upgrade. Subscription returns to ACTIVE. No cancellation of the current subscription. |
|
Abort (auto) |
System (automatic) |
If a suspended upgrade reaches billing period end without being resumed, it auto-aborts. Subscription expires at the end of the period. |