Skip to main content
When a subscription’s price changes partway through a billing period (because the customer moved to a different plan), there’s an unused portion of the current period they’ve already paid for. Proration reconciles that difference. Bachs prorates by the exact time remaining in the period, so the customer is only charged or credited for what they actually use. You choose how the difference is settled with proration_behavior on the Update Subscription endpoint.

​
Proration behaviors

Always send proration_behavior explicitly so the outcome is predictable. If you omit it, Bachs settles the change immediately (invoice_now).
reset (charge the full new price and restart the cycle) is not supported yet; sending it returns 400.

​
Upgrades and downgrades

Proration cuts both ways, and Bachs handles each side differently. Upgrade (net charge). Moving to a more expensive plan owes money for the rest of the period. With invoice_now this is charged to the card immediately; with next_cycle it’s added to the next renewal. Downgrade (net credit). Moving to a cheaper plan means the customer overpaid for the rest of the period. Bachs always turns that into customer credit, regardless of the proration_behavior you chose, rather than refunding to the card.

​
Customer credit

A downgrade credit is added to the customer’s credit balance, a running per-customer, per-currency balance held on your account. It isn’t paid back to the card. Instead, Bachs draws it down automatically against the customer’s future invoices before charging their card:
  • On the next invoice, available credit is applied first.
  • If credit fully covers an invoice, that invoice is marked paid and the card is never charged.
  • Any leftover credit carries forward to the invoice after that.
This means a customer who downgrades typically sees smaller (or zero) charges on their next few renewals until the credit is used up.

​
How the amount is calculated

For the portion of the period remaining at the moment of the change:
  • A positive net is a charge (upgrade); a negative net is a credit (downgrade).
  • fraction_of_period_remaining is the exact share of the current billing period still ahead, between 0 and 1.
  • Amounts are rounded to two decimal places.

Managing subscriptions

Change a subscription’s plan and pass the proration behavior you want.

Payment recovery

What happens when an immediate proration charge fails.
Seat-based (per-unit) pricing and its proration are coming soon. This page covers plan changes; seats will be documented when they ship.