Plan group components
Create a plan group in the dashboard
Go to Plans → Groups and click Create Group. Name the group, add your plans, then drag and drop to arrange them from lowest to highest tier. Each plan can only belong to one group. Plans in a group can sell different currencies and countries with Regional Prices. A subscriber can switch only to group plans that sell its currency in its country: the Customer Portal shows only those, and the API rejects the others with422 missing_regional_price.
This order defines the upgrade path and display order in the Customer Portal.
Default plan and signup trial
Open the group and choose Set as default on a free plan, or Set as signup trial on a paid plan whose default price has a trial without a payment method. A group has at most one of each. A customer created withplanGroupId starts at once on:
- the signup trial, when the group has one and the customer never had that plan;
- otherwise the default plan;
- otherwise no plan.
customers.createBatch accepts the same planGroupId for every customer in the batch. A customer that already has an open subscription keeps it.
A paid plan of the group moves to the default plan instead of being canceled when:
- the customer cancels it from the Customer Portal, at period end;
- its payment authorization is revoked;
- every payment retry fails;
- a trial without a payment method ends without a card.
Limitations
- The default plan must be a free plan in the group.
- A signup trial plan can’t remove the trial without a payment method from its default price.
- A customer gets the signup trial once per plan.
planGroupIdfor a group with neither a default plan nor a signup trial returns400.planGroupIdfor a group with a signup trial returns403while the organization can’t charge yet.