Subscriptions let you sell ongoing access with automated renewals. Use flexible billing cycles, free trials, plan changes, and add‑ons to tailor pricing for each customer.
Upgrade & Downgrade
Control plan changes with proration and quantity updates.
On‑Demand Subscriptions
Authorize a mandate now and charge later with custom amounts.
Customer Portal
Let customers manage plans, billing, and cancellations.
Subscription Webhooks
React to lifecycle events like created, renewed, and canceled.
What Are Subscriptions?
Subscriptions are recurring products customers purchase on a schedule. They’re ideal for:- SaaS licenses: Apps, APIs, or platform access
- Memberships: Communities, programs, or clubs
- Digital content: Courses, media, or premium content
- Support plans: SLAs, success packages, or maintenance
Key Benefits
- Predictable revenue: Recurring billing with automated renewals
- Flexible cycles: Monthly, annual, custom intervals, and trials
- Plan agility: Proration for upgrades and downgrades
- Add‑ons and seats: Attach optional, quantifiable upgrades
- Seamless checkout: Hosted checkout and customer portal
- Developer-first: Clear APIs for creation, changes, and usage tracking
Creating Subscriptions
Create subscription products in your Dodo Payments dashboard, then sell them through checkout or your API. Separating products from active subscriptions lets you version pricing, attach add‑ons, and track performance independently.Subscription product creation
Configure the fields in the dashboard to define how your subscription sells, renews, and bills. The sections below map directly to what you see in the creation form.Product details
- Product Name (required): The display name shown in checkout, customer portal, and invoices.
- Product Description (required): A clear value statement that appears in checkout and invoices.
- Product Image (required): PNG/JPG/WebP up to 3 MB. Used on checkout and invoices.
- Brand: Associate the product with a specific brand for theming and emails.
- Tax Category (required): Choose the category (for example, SaaS) to determine tax rules.
Pick the most accurate tax category to ensure correct tax collection per region.
Pricing
- Pricing Type: Choose Subscription (this guide). Alternatives are Single Payment and Usage Based Billing.
- Price (required): Base recurring price with currency.
- Discount Applicable (%): Optional percentage discount applied to the base price; reflected in checkout and invoices.
- Repeat payment every (required): Interval for renewals, e.g., every 1 Month. Select the cadence (months or years) and quantity.
- Subscription Period (required): Total term for which the subscription remains active (e.g., 10 Years). After this period ends, renewals stop unless extended.
- Trial Period Days (required): Set trial length in days. Use 0 to disable trials. The first charge occurs automatically when the trial ends.
- Select add‑on: Attach up to 3 add‑ons that customers can purchase alongside the base plan.
Changing pricing on an active product affects new purchases. Existing subscriptions follow your plan‑change and proration settings.
Add‑ons are ideal for quantifiable extras such as seats or storage. You can control allowed quantities and proration behavior when customers change them.
Advanced settings
- Tax Inclusive Pricing: Display prices inclusive of applicable taxes. Final tax calculation still varies by customer location.
- Generate license keys: Issue a unique key to each customer after purchase. See the License Keys guide.
- Digital Product Delivery: Deliver files or content automatically after purchase. Learn more in Digital Product Delivery.
- Metadata: Attach custom key–value pairs for internal tagging or client integrations. See Metadata.
Use metadata to store identifiers from your system (e.g., accountId) so you can reconcile events and invoices later.
API Management
Create subscriptions
Create subscriptions
Use
POST /subscriptions
to create subscriptions programmatically from products, with optional trials and add‑ons.API Reference
View the create subscription API.
Update subscriptions
Update subscriptions
Use
PATCH /subscriptions/{id}
to update quantities, cancel at period end, or modify metadata.API Reference
Learn how to update subscription details.
Change plans (proration)
Change plans (proration)
Change the active product and quantities with proration controls.
API Reference
Review plan change options.
On‑demand charges
On‑demand charges
For on‑demand subscriptions, charge specific amounts on demand.
API Reference
Charge an on‑demand subscription.
List and retrieve
List and retrieve
Use
GET /subscriptions
to list all subscriptions and GET /subscriptions/{id}
to retrieve one.API Reference
Browse listing and retrieval APIs.
Usage history
Usage history
Fetch recorded usage for metered or hybrid pricing models.
API Reference
See usage history API.
Common Use Cases
- SaaS and APIs: Tiered access with add‑ons for seats or usage
- Content and media: Monthly access with introductory trials
- B2B support plans: Annual contracts with premium support add‑ons
- Tools and plugins: License keys and versioned releases
Integration Examples
Checkout Sessions (subscriptions)
When creating checkout sessions, include your subscription product and optional add‑ons:Plan changes with proration
Upgrade or downgrade a subscription and control proration behavior:Cancel at period end
Schedule a cancellation without immediate termination of access:On‑demand subscriptions
Create an on‑demand subscription and charge later as needed:Best Practices
- Start with clear tiers: 2–3 plans with obvious differences
- Communicate pricing: Show totals, proration, and next renewal
- Use trials thoughtfully: Convert with onboarding, not just time
- Leverage add‑ons: Keep base plans simple and upsell extras
- Test changes: Validate plan changes and proration in test mode
Subscriptions are a flexible foundation for recurring revenue. Start simple, test thoroughly, and iterate based on adoption, churn, and expansion metrics.