Proration
Proration is how PaymentsAI handles partial billing cycles when a subscription's plan changes mid-cycle. The behavior is controlled by the proRataCredit flag on the plan-change request.
For the endpoint and request shape, see Upgrade and downgrade.
What proRataCredit does
proRataCredit is a boolean on the POST /subscriptions/{id}/items request body.
| Value | Behavior |
|---|---|
true | Proration is applied. The unused portion of the old plan and the cost of the remaining cycle on the new plan are reconciled at the moment of change, with the net amount charged or credited to the customer. |
false | No proration. The change takes effect according to retainRenewalTime without any mid-cycle reconciliation. |
The exact charge or credit produced by a prorated change depends on the prices of the old and new plans and on the time remaining in the current cycle. Confirm the resulting amount in the response from the plan-change call before relying on it for accounting.
When proration does not apply
proRataCredit: false: no proration is calculated; the change takes effect according toretainRenewalTimeonly.- Trial period: changing plans while a subscription is still in trial does not generate proration. The trial runs out as scheduled, and the new plan starts billing at the end of the trial.
- End-of-cycle changes: if the change date coincides with the renewal date, there is no partial cycle to prorate.