BiasDocs

Plan changes and proration

Move a subscriber to another plan or quantity without waiting for the next renewal.

When a subscription’s items change partway through a period, Bias prorates the change by default: it credits the unused time on the old items and charges the rest of the period on the new ones, right away.

Change a subscription’s items

  1. On the subscription’s page, click Edit on the Items card, or choose Edit items from its menu.
  2. Change an item’s price or quantity, add a product, or remove an item. A subscription keeps at least one item.
  3. Leave Prorate checked to bill the change now. The Billed now summary shows what the customer will be charged before you save.
  4. Click Update items.
Editing a subscription's items from Pro to Business, with the prorated amount billed now

The Billed now summary lists:

  • Unused time credited: the part of the current period the customer already paid for on the old items.
  • Remaining time charged: the rest of the period on the new items.
  • Credit applied or Previous balance due: credit from the customer’s balance that pays toward the charge, including the unused time just credited, or an amount they already owed.
  • Due now: what Bias charges or invoices when you save.

Uncheck Prorate to change the items without crediting or charging anything now. The sheet shows the date of the next renewal, when the new items are billed.

Only active and past-due subscriptions are prorated. A trialing subscription’s items change with nothing charged, and the first invoice after the trial bills the new items.

How a prorated change is billed

Bias credits the unused time against the invoice that billed it, at what that invoice charged after discounts and tax. If that invoice is still open, the credit first lowers what’s due on it. Bias then creates an invoice for the remaining time, taxed at today’s rates, and applies the credit to it first. Time is prorated to the millisecond, and each line is rounded to the cent. The invoice is charged to the subscription’s payment method right away, or emailed if the subscription is billed by emailed invoice.

  • Upgrade: the charge is larger than the credit, so the customer pays the difference.
  • Downgrade: the credit is larger, so nothing is charged. What’s left stays on the customer’s balance and comes off their next invoices.
  • Removing an item: its unused time is credited, with no new invoice.

Plan changes never refund a payment. If the charge is declined, the change stays and the invoice follows the subscription’s failed payment retries.

Each credit appears as a credit note with the reason Proration on the invoice it credits. The charge is an invoice of its own on the subscription.

Change the billing interval

Moving a subscription to prices on another interval, such as monthly to yearly, starts a new period now. The unused time on every item, and on shipping, is credited and a full new period is charged, even without proration. Interval changes are made in the billing portal or with the API.

Scheduled changes

A change can also be scheduled for the next renewal, such as a downgrade a customer makes in the billing portal. The subscription’s page then shows the new plan, the date it takes effect and what’s billed at the next renewal. Click Cancel scheduled change to keep the current plan.

Editing the subscription’s items replaces a scheduled change.

Customer changes

Customers can upgrade, downgrade and change quantities themselves in the billing portal. You choose which prices they can switch to and whether downgrades apply right away or at the end of the period. Portal changes with an immediate charge apply only once the payment goes through.

Choosing the prices customers can switch to in the billing portal settings

Change plans with the API

Update the subscription’s items. Set proration_behavior: "none" to skip proration, apply_at: "period_end" to schedule the change as the subscription’s pending_change, or payment_behavior: "error_if_incomplete" to apply the change only if its charge succeeds. To show a customer the cost first, preview the change and pass the returned proration_at to the update within 30 minutes. Proration credit notes have reason: "proration", and the charge is an invoice with billing_reason: "subscription_update".

server.ts

const items = [{ id: "si_...", price: "price_...", quantity: 1 }];

const preview = await bias.subscriptions.upcomingInvoice("sub_...", { items });
if (preview.object === "error") throw new Error(preview.error.message);

// Show preview.proration?.amount_billed to the customer, then:
const subscription = await bias.subscriptions.update("sub_...", {
    items,
    proration_at: preview.proration?.proration_at,
});