Dynamic terms are Piano's most flexible subscription type. They let you build multi-phase billing structures that combine trials, paid periods, free periods, and upgrades into a single subscriber journey. They're widely used for introductory pricing, metered access, seasonal offers, and complex subscription packages, see more in our Dynamic terms documentation.
Starting mid-July 2026, all eligible dynamic term subscriptions are integrated with Stripe Billing. Manual renewal and future start date support for dynamic terms are planned for August 2026.
How dynamic terms map to Stripe
Each dynamic term maps to a Stripe subscription schedule. Every access period in your dynamic term becomes a phase in the Stripe schedule, preserving the same structure and billing behavior your subscribers already experience.
Piano calculates pricing and generates dynamic price_data for each phase. This is the same approach used for payment terms, extended to support multi-phase billing structures.
Supported capabilities
All core dynamic term capabilities are supported on Stripe Billing:
-
Multi-phase billing: trials, paid periods, free periods, and transitions between them
-
Single-payment and one-off terms: including terms with a single charge and ongoing free access
-
Free periods: zero-amount billing phases within a subscription schedule
-
Promotions and discounts: applied to dynamic term subscriptions
-
Cancellation: both immediate and end-of-period
-
Upgrades: dynamic-to-dynamic and payment-to-dynamic
-
Billing plan refresh: configuration changes to your terms apply to Stripe subscriptions
-
Tax support: manual tax rates created and applied automatically, same as payment terms
-
BYOP: dynamic terms are fully supported for non-Stripe payment providers, using the same model described in Non-Stripe Providers (BYOP)
Dynamic term upgrades
Dynamic-to-dynamic and payment-to-dynamic upgrades follow the same subscription-first model described in Subscription Upgrades. Piano cancels the existing subscription and creates a new one with the target term and a proration credit applied, while in Stripe the subscription remains the same and the result is represented as an updated subscription schedule period.
3-year billing guideline
The 3-year billing guideline applies to dynamic terms. A dynamic term exceeds the guideline if any of its access periods is set up with a billing period over 3 years, or uses unlimited access with a free or single-payment billing plan. One non-compliant access period makes the entire term unswitchable, not just the subscriptions on that period. Non-compliant terms are skipped during switching. They stay on Piano billing while your other terms move to Stripe. Your existing terms, subscribers, and offers are not disrupted. The term stays usable for existing subscribers, but its ID can no longer be used in payment-subscription imports, and the Dashboard shows a warning on the term detail page and in the terms list.
For full details on what counts toward the limit, how to identify affected terms, and step-by-step remediation guidance, see the 3-year billing guideline.
Switching behavior
Switching is automatic and happens per term, per app. It follows the same process described in Legacy Subscription Switching. Compatible terms switch automatically; incompatible terms (such as those exceeding the 3-year guideline) are skipped. One incompatible term does not hold back the rest. Each term is evaluated independently. Your subscribers won't see any difference; the change is purely on the billing infrastructure side, and following remediation Piano expects all terms and subscriptions to switch.
Dynamic terms in Stripe Dashboard
Switched dynamic term subscriptions appear in your Stripe Dashboard as subscriptions with associated schedules. Each access period maps to a phase in the schedule. The same metadata conventions described in Piano Metadata in Stripe apply: pianoCreationReason, pianoAid, pianoSubscriptionId, and phase-level metadata such as pianoInTrial are set automatically.
Important: Do not make any changes to dynamic term subscription schedules directly in the Stripe Dashboard. This will cause out-of-sync state. Use Piano Dashboard for all subscriber operations.