Prorations

Proration is the process of adjusting a subscription’s charges when an item changes mid-cycle, such as switching prices, changing quantity, or replacing a recurring line item with another. Instead of charging the full price of the new item or refunding the full price of the old one, Solidgate credits the unused portion of the current billing period and charges only the value of the new item for its remaining time, so customers pay only for the time they use.

Proration applies when you update a subscription with mode set to IMMEDIATE and proration_mode set to UNUSED , according to the proration rules for immediate subscription changes.

Actions that trigger proration

Proration applies to changes that affect the value of a subscription’s line items:

• Changing the quantity on the subscription's recurring line item, such as increasing the number of seats from 10 to 15
• Replacing the recurring line item with another one, such as switching from a $30 plan to a $60 plan
• Resetting the billing anchor without changing any line items. Solidgate credits the unused time on the current recurring item and charges a full new period for the same item.

Adding or removing a recurring line item on its own, without a matching replacement in the same request, is not supported and the update request fails.

Adding a one-time line item in the same request does not itself get prorated. It is added in full, independent of any credit or charge calculated for the recurring item.

Proration does not apply to changes that do not affect item value:

• Applying or removing a coupon
• Changing the payment instrument
• Updating metadata or description

These changes do not create a credit or charge line on the subscription, regardless of the proration_mode value.

How proration is calculated

Solidgate credits the remaining time on the line item being replaced or updated, and charges the new line item for its remaining period:

• If billing_anchor is KEEP , the charge uses the same remaining ratio as the credit, so the customer pays only for the time left in the current period.
• If billing_anchor is RESET , the charge covers a full new billing period starting now.

Solidgate calculates the remaining-time ratio using second-level granularity. The ratio reflects the exact time between the proration date and the end of the billing period, not a whole-day count.

Examples

Switching prices mid-period

A subscription item that costs $30 per billing period is replaced halfway through the current period with an item that costs $60 per billing period.

• Old item price: $30 per billing period
• New item price: $60 per billing period
• Timing of the change: halfway through the period

With billing_anchor set to KEEP , the billing cycle continues unchanged:

Proration calculation	Amount
Credit for the old item ($30 × 50%)	−$15
Charge for the new item's remaining half ($60 × 50%)	+$30
Net amount charged	$15

With billing_anchor set to RESET , a new billing cycle starts immediately:

Proration calculation	Amount
Credit for the old item ($30 × 50%)	−$15
Charge for a full new period at the new price ($60 × 100%)	+$60
Net amount charged	$45

Increasing quantity mid-period

A subscription with ten seats at five dollars per seat per billing period increases to fifteen seats one third of the way into the period.

• Starting quantity: 10 seats at $5 per seat per billing period
• New quantity: 15 seats
• Timing of the change: one third into the period

Proration calculation	Amount
Additional seats added	5 seats
Charge for the additional seats for the remaining two thirds of the period (5 × $5 × 66.7%)	+$16.67

Solidgate charges an incremental amount for the additional seats instead of the full price of the new quantity for a period the customer already started paying for.

Downgrading to lower-priced item

A subscription item that costs $100 per billing period is replaced three quarters of the way through the period with an item that costs $20 per billing period.

• Old item price: $100 per billing period
• New item price: $20 per billing period
• Timing of the change: three quarters through the period

Proration calculation	Amount
Credit for the old item ($100 × 25%)	−$25
Charge for the new item's remaining quarter ($20 × 25%)	+$5
Net result (credited to the customer's account balance)	−$20

The $20 net credit goes to the customer’s account balance instead of a refund, tracked under customer balance credits.

Resetting the billing anchor without item changes

A subscription item that costs $30 per billing period resets its billing anchor immediately halfway through the current period, with no change to the item itself.

• Item price: $30 per billing period
• Timing of the reset: halfway through the period

Proration calculation	Amount
Credit for the unused remainder of the current period ($30 × 50%)	−$15
Charge for a full new period at the same price ($30 × 100%)	+$30
Net amount charged	$15

Solidgate charges for a full new billing period starting immediately, instead of waiting for the current period to end.

When a change nets to zero, for example swapping between two prices of equal value, Solidgate still creates the proration invoice with its credit and charge line items, so a record of the change exists. No invoice is created when proration_mode is NONE .

Customer balance credits

When the proration calculation results in a negative net amount, meaning the credit for unused time is larger than the charge for the new item, Solidgate credits the difference to the customer’s account balance instead of issuing a refund. This happens most often when a customer downgrades to a lower-priced item partway through a billing period.

The credit appears in the customer’s balance transaction log with a subscription_update source type. Solidgate applies an available balance automatically toward the customer’s next invoice.

Coupons and proration

A coupon applied to the subscription applies to the proration invoice. Solidgate calculates the credit and charge line items using the subscription’s active discount, not the full list price of the old and new items.

Example

Replacing an item with an active coupon

A subscription item priced at $50 per billing period has a 20% coupon applied, so the customer pays $40 per period. Halfway through the period, the item is replaced with one priced at $80 per period, and the same 20% coupon still applies.

• Old item price: $50 per billing period ($40 discounted)
• New item price: $80 per billing period ($64 discounted)
• Timing of the change: halfway through the period

Proration calculation	Amount
Credit for the old item's discounted price ($40 × 50%)	−$20
Charge for the new item's remaining half at the discounted price ($64 × 50%)	+$32
Net proration charge	$12

Proration invoice

Solidgate creates a proration invoice with billing_reason set to SUBSCRIPTION_UPDATE and charges it to the subscription’s payment instrument. The invoice becomes the subscription’s last_invoice_id .

The subscription keeps its current items and billing cycle until the proration invoice is paid. Once paid, Solidgate applies the staged changes, including item swaps, quantity updates, and the billing anchor update.

The invoice is due within two hours. If it remains unpaid after that window, Solidgate voids it and the requested change does not apply.

Unpaid proration invoice

If the proration invoice is voided, Solidgate removes any discount added for the update and discards the requested change. The subscription’s items and billing cycle remain unchanged, and its status stays ACTIVE throughout. You can submit the same update request again. Solidgate treats it as a new request and creates a new proration invoice.

Proration restrictions

Solidgate returns an error and does not apply the update if:

• The subscription has an existing one-time line item, even if the request does not modify it.
• A recurring line item included in the request has not started billing yet.
• A recurring line item included in the request has an unapplied change scheduled for the next renewal (requested earlier with mode set to PERIOD_END ).

These requests return ERROR_PRORATE_DELAYED_ITEMS . Adding a new one-time line item in the same request is not affected by this restriction. It is charged in full, not prorated.

If a renewal is due to start before the proration can complete, the update request returns ERROR_SUBSCRIPTION_IN_PROCESSING instead, the same error returned when mode is IMMEDIATE on a subscription that is not ACTIVE .

Solidgate also validates the structure of the update request before applying proration: