State how subscriptions should change
Put trial, cancellation and price-adjustment decisions next to the product they govern. Wildo applies the supported settings when opening checkout or changing a subscription, while provider-managed collection settings remain with the provider.
Example — Give a plan a trial and a clear exit
A professional plan offers a fourteen-day trial and cancellation at the end of the paid period. Those decisions belong to the product rather than being repeated in each button handler.
For engineers
Wonder Todos’ professional plan contains the following policy. These are selected fields from shared-lib/src/engine/product.ts:
The following selected excerpt is from product.ts; the surrounding module and explanatory source comments are omitted.
behaviorPolicy: {
trial: { days: 14, requirePaymentMethod: false },
upgrade: { proration: ProrationBehavior.CREATE_PRORATIONS, timing: BillingTiming.IMMEDIATE },
downgrade: { proration: ProrationBehavior.NONE, timing: BillingTiming.AT_PERIOD_END },
cancellation: { allowImmediate: false, defaultBehavior: BillingTiming.AT_PERIOD_END },
},
Trial days come from the product policy, falling back to the application default. Checkout callers cannot override them; a product value of zero disables the trial. requirePaymentMethod is passed to hosted checkout when starting a trial. Cancellation resolves caller preference, product default and application default, then refuses any effective immediate cancellation forbidden by the product. An authored immediate default requires allowImmediate: true; contradictory product policies fail validation. An explicit period-end choice still overrides an immediate default.
Distinguish adjustment from scheduling
| Declaration | Runtime meaning |
|---|---|
| Upgrade/downgrade proration | Sent as the provider’s subscription-update proration behavior |
| Upgrade/downgrade timing | Carried as metadata; the Stripe adapter does not schedule a future plan change |
| Trial days and payment method | Used when opening subscription checkout |
| Cancellation policy | Controls refusal and immediate versus period-end cancellation |
| Payment grace period and retry count | Commercial declarations; configure collection retries at the provider |
The target product’s tier order distinguishes an upgrade from a downgrade. An application should not tell a customer that a downgrade is scheduled merely because timing says period-end: a scheduled change needs a provider scheduling mechanism. Keep the commercial wording consistent with the actions offered. Other product-policy fields, such as metering declarations, also require their corresponding usage implementation rather than executing by declaration alone.