Changing a price
Replace a price without disrupting the customers already on it.
A price does not change once customers are on it. Instead of editing a live price, you replace it: yRecurring creates a new version and archives the old one. The customers already on the old price keep billing on it, undisturbed.
Important
To change what a plan costs, replace the price; do not try to edit a live one. Replacing keeps existing subscribers on their old price by default, so a price change never surprises anyone mid-subscription.
Existing subscribers keep billing here. They are grandfathered.
New subscriptions use this one.
Migrate (optional): move the grandfathered subscribers from version 1 onto version 2.
Replace, do not edit
When you want to change what a plan costs, you replace its price. That creates a new version of the price and archives the old one. The two are linked, so you can see that the new price came from the old.
New subscriptions use the new price. Existing subscriptions stay on the old one. This is grandfathering: the price a customer signed up at keeps applying to them, so a price change never surprises anyone mid-subscription.
Grandfathered by default
Replacing a price does not move anyone. Every existing subscriber keeps billing on the version they are on. This is the safe default: you can change your pricing for new customers without touching the bills of your current ones.
Moving customers to the new price
When you do want existing customers on the new price, you migrate them. Migration moves the grandfathered subscribers from the old price to the new one, as a deliberate action rather than a side effect of the replace. You can preview a migration first to see how many subscriptions it would affect before you run it.
When the migration takes effect
A migration can land two ways, and the choice decides whether customers see a charge right away:
- At the next renewal (the default). Each subscription moves to the new price when its next period begins. Nothing is billed mid-cycle, so no one gets a surprise charge. This is the safe default when you leave the timing unset.
- Immediately. Each subscription moves now, in the middle of its period. Because the price changes mid-cycle, the move is prorated: the customer is credited for the unused part of the old price and charged for the rest of the period on the new one, the same way any mid-cycle change is prorated. Moving up in price bills the difference now; moving down leaves a credit.
So a renewal-timed migration is quiet until each customer's cycle turns over, while an immediate one settles the difference straight away.
Edge cases
- Editing is not how you change a price. You replace it, and the old version stays for the customers on it.
- Grandfathering is automatic. Existing subscribers are never moved by a replace; only a migration moves them.
- You can preview a migration to see the size of the cohort before committing.