Proration

Proration is the mid-cycle billing adjustment applied when the amount of a Subscription changes in the middle of a billing period. The customer is credited for the unused part of the old amount and charged for the same remaining part of the new one.

Proration Behavior

Value	Description
none	No adjustment is calculated and no proration event is created. The new amount is charged from the next billing cycle.
create_prorations	The adjustment is calculated and stored as a pending proration event. It is settled together with the next scheduled Subscription transaction.
immediate_action	A positive adjustment (the customer owes) is charged right away as a separate transaction. A negative adjustment (the customer is credited) is stored as pending, exactly like create_prorations. If the separate charge is declined or its amount is below the minimum chargeable amount, the adjustment stays pending and the amount change still goes through.

info

Proration never triggers a refund. A negative adjustment is always kept as a pending credit and subtracted from the next scheduled transaction.

Where the Behavior Comes From

The behavior of a single change is resolved in this order:

1. The proration_behavior sent on Update subscription or Proration preview.
2. The proration_behavior of the Plan the Subscription belongs to.
3. none, if neither is set.

Create subscription does not take a proration_behavior, a new Subscription always follows its Plan.

The proration_behavior sent on an Update is a one-time override. It applies to that request only and is not stored on the Subscription. The next Update falls back to the Plan's proration_behavior again, unless it sends its own override.

When a Proration Event Is Created

Updating a Subscription creates a proration event only when all of the following are true:

• the resolved behavior is create_prorations or immediate_action
• amounts.requested_amount or amounts.initial_amount differs from the current value
• billing_cycle and billing_factor are unchanged
• the Subscription has already been charged at least once
• the Subscription is not in its trial period
• the calculated net amount is not zero

Updating a Plan with update_subscriptions set to true creates a proration event on every related Subscription too, provided the Plan's proration_behavior is not none, the Subscription is active, and the billing cycle and factor did not change. The Subscription conditions above apply to each of them as well, so the ones that have never been charged or are in their trial period are skipped.

info

Sending a different plan_id on Subscription Update does not re-derive the amounts from the new Plan. Proration is calculated from the amounts you send in the request.

How the Amount Is Calculated

The base amount of the current period is initial_amount while the Subscription is in its first cycle, and amount afterwards.

Field	Calculation
days_in_period	whole days between the period start and next_bill_date
days_remaining	whole days between the change date and next_bill_date
credit_amount	old amount × days_remaining / days_in_period
charge_amount	new amount × days_remaining / days_in_period
net_amount	charge_amount − credit_amount

credit_amount and charge_amount are rounded to cents, so the two sides of a change can differ by a cent from a plain percentage.

A positive net_amount means the customer owes the difference. A negative net_amount means the customer is credited.

Event Lifecycle

Status	Meaning
pending	Calculated, not settled yet. It is added to the next scheduled transaction.
applied	Settled. applied_transaction_id holds the ID of the transaction that settled it.
voided	No longer collectable. Pending events are voided when the Subscription is canceled or deleted, or when it becomes declined.

Reading the Current State

Where	What it returns
balance on Get subscription	Sum of the net_amount of the Subscription's pending events.
proration_history on Get subscription	Every proration event of the Subscription, newest first.
Proration preview	The adjustment a change would produce, without applying it.

Rejected Prorations

A change is rejected with 400 and one of these messages:

Message	Reason
Proration cannot be applied because the billing cycle, or billing factor has been modified.	The cadence changed in the same Update subscription request.
Proration cannot be applied because the billing cycle, billing factor, or trial period has been modified.	The cadence changed in an Update plan request that also carries update_subscriptions and a prorating behavior.
The resulting charge is below the minimum chargeable amount.	The next transaction would not cover the processing and billing fees of the transaction.

The minimum chargeable amount check runs on every Update whose amount changes, none included, and also when the amount is unchanged but the Subscription still has a pending adjustment, because a pending credit alone can push the next transaction below the limit.