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 },
downgrade: { proration: ProrationBehavior.CREATE_PRORATIONS },
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 | There is none to declare: a plan change applies when it is confirmed. Deferring one to the period end is not built yet |
| 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. A plan change applies when it is confirmed, so an application should not tell a customer that a downgrade is scheduled for the period end. Choose the downgrade proration knowing that: NONE gives no credit for the unused part of the higher plan. 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.