Subscription-Prorate

Settle the price difference immediately when you change amount, interval, intervalCount or nextPaymentAt mid-period. Unused time is credited at the current price. An amount change charges the remaining time at the new price and keeps the billing period. An interval or intervalCount change charges the full new price and restarts the period from now. A nextPaymentAt change charges the time from now until the new date and moves the period end to it, so a later date charges and an earlier one refunds.

A positive difference is charged to the saved payment method. A negative difference is refunded against the payments that funded the current period, newest money first: the charge taken by the most recent prorated change in this period, then the payment that renewed it. A refund those together cannot cover is rejected before any of it moves, so a change is either settled in full or not at all. The same rule applies to the preview, which returns the same rejection rather than quoting a settlement the update would refuse.

A billing period can be prorated more than once. Two limits apply:

While a settlement is in flight the next one is rejected, and the guard has one-second granularity, so a repeat inside the same second as the previous change is rejected too. Retry after at least a second.
A period whose length no longer matches the plan's interval cannot be prorated at all until the next renewal restores it. A nextPaymentAt change resizes the period by definition, and an interval or intervalCount change without prorate leaves the old period in place under the new interval. Either one closes the period to further prorated changes, because the credit and the charge are both fractions of the stored period and would divide by a length the price was never set against.

Accepted on active and trialing subscriptions only. On a trialing subscription the fields change and no money moves, because there is no paid time to credit. Any other status is rejected.

You cannot combine prorate with trialPeriodEnd, cancelAtPeriodEnd, pauseAtPeriodEnd, pauseIntervalCount or skipIntervalCount.

On an active subscription, these are rejected too:

A subscription that pays with Bizum, or whose allowedPaymentMethods include it.
prorate without a change to amount, interval, intervalCount or nextPaymentAt, because there is nothing to settle.
An interval or intervalCount change while cancelAtPeriodEnd, pauseAtPeriodEnd or skipIntervalCount is pending. An amount change is accepted.
A change that would refund, when refunds are disabled for the account.

A nextPaymentAt change has its own rules:

Only on an active subscription. A prorated nextPaymentAt change is rejected on a trialing one, where nothing would settle, and on a past due one, which a plain change accepts.
Not together with interval or intervalCount. Those already restart the period from now, so the new period end would have two answers.
The charge is capped at 24 billing periods. A date far enough ahead to exceed that is rejected rather than charged.
The clearing value described on nextPaymentAt is accepted on an anchor move and on nothing else. Any other prorated change still rejects those fields outright.

booleanSubscription-Prorate

A billing period can be prorated more than once. Two limits apply:

While a settlement is in flight the next one is rejected, and the guard has one-second granularity, so a repeat inside the same second as the previous change is rejected too. Retry after at least a second.
A period whose length no longer matches the plan's interval cannot be prorated at all until the next renewal restores it. A nextPaymentAt change resizes the period by definition, and an interval or intervalCount change without prorate leaves the old period in place under the new interval. Either one closes the period to further prorated changes, because the credit and the charge are both fractions of the stored period and would divide by a length the price was never set against.

Accepted on active and trialing subscriptions only. On a trialing subscription the fields change and no money moves, because there is no paid time to credit. Any other status is rejected.

You cannot combine prorate with trialPeriodEnd, cancelAtPeriodEnd, pauseAtPeriodEnd, pauseIntervalCount or skipIntervalCount.

On an active subscription, these are rejected too:

A subscription that pays with Bizum, or whose allowedPaymentMethods include it.
prorate without a change to amount, interval, intervalCount or nextPaymentAt, because there is nothing to settle.
An interval or intervalCount change while cancelAtPeriodEnd, pauseAtPeriodEnd or skipIntervalCount is pending. An amount change is accepted.
A change that would refund, when refunds are disabled for the account.

A nextPaymentAt change has its own rules:

Only on an active subscription. A prorated nextPaymentAt change is rejected on a trialing one, where nothing would settle, and on a past due one, which a plain change accepts.
Not together with interval or intervalCount. Those already restart the period from now, so the new period end would have two answers.
The charge is capped at 24 billing periods. A date far enough ahead to exceed that is rejected rather than charged.
The clearing value described on nextPaymentAt is accepted on an anchor move and on nothing else. Any other prorated change still rejects those fields outright.

Example: false

Subscription-Prorate
false

Was this page helpful?