Subscription plans (add-on)

Every subscription plan in the store, each with the product and variant it sells, its billing interval, its free trial, its billing mode, its renewal variant, its grace period, its own price and label if it has them, what happens to its place when a subscription ends, the customer group it puts live subscribers in, its position among the variant's billing options, its per-provider price references and how many live subscriptions are running on it. A plan is a product variant plus a calendar: the name, the description, the images and any sale live on the variant in the base plugin's product editor, and so does the price unless the plan names its own in price_minor. One variant can carry several plans, which are the billing options its buy button offers, all selling from the variant's one stock count. On a store that sells in more than one currency each plan also carries currency_amounts, the plan's own price in the other currencies as decimal strings; a currency with no entry is one the plan cannot be bought in. The response also carries the base currency, the registered payment providers and the defaults a new plan opens with. The live count is what makes a delete decision honest, because a plan with subscriptions on it cannot be removed.

One plan with the variant it sells, the variant a renewal carries, its interval, trial, billing mode, grace period, price, label, stock setting, customer group, sort position, per-provider references and its live subscription count, plus the list of registered payment providers. On a store that sells in more than one currency it also has currency_amounts, the plan's own price in the other currencies. Read this before updating a plan so you know which fields are already set and whether anything is running on it.

Every purchasable variant in the catalog with its price in minor units, its product status, plan_ids listing every plan it already carries with the default first, and plan_id, the default plan, or null when it carries none. A variant can carry several plans, so an already-planned variant is still a valid choice for a second billing option; the ids are there so a Monthly is not created twice. Each row is named the way the storefront names it, product title then option combination then SKU, which is the only way to tell three sizes of one product apart on a catalog whose variant titles are empty. Capped at 500 rows, so narrow with q on a large catalog rather than paging.

Start selling an existing product variant on a calendar. Only variant_id is required and the product is resolved from it rather than trusted; everything else defaults to billing monthly, no trial, automatic billing mode, the store's grace period, the variant's price and enabled. A variant that does not exist is refused with 422. A variant that already carries a plan takes another as a second billing option, placed after the ones it has. Whatever the price, each subscription freezes what its customer actually paid, sale and coupon included, so it renews at that amount for the life of the agreement.

Change a plan's calendar. Only the fields sent are written, so switching one off does not have to resend the interval. The variant is not editable and sending a different variant_id is refused with 422: every running subscription froze its amount from that variant, and repointing the plan would silently change what those customers believe they are paying for. An interval unit nobody bills in is also a 422. Everything here applies to new subscribers only, including the billing mode, since each subscription carries its own frozen copy.

Remove a plan. Refused with 422 while any live subscription is running on it, naming the count, because a subscription reads its interval off the plan every time the calendar advances and losing the row would leave the store unable to say when the next charge is due. Cancel those subscriptions or let them run out first. To stop selling a plan without touching what is running on it, send enabled false to update_plan instead.