Skip to main content
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

Use POST /subscriptions to create subscriptions programmatically from products, with optional trials and add‑ons.

API Reference

View the create subscription API.
Use PATCH /subscriptions/{id} to update quantities, cancel at period end, or modify metadata.

API Reference

Learn how to update subscription details.
Change the active product and quantities with proration controls.

API Reference

Review plan change options.
For on‑demand subscriptions, charge specific amounts on demand.

API Reference

Charge an on‑demand subscription.
Use GET /subscriptions to list all subscriptions and GET /subscriptions/{id} to retrieve one.

API Reference

Browse listing and retrieval APIs.
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: 
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ]
});

​
Plan changes with proration

Upgrade or downgrade a subscription and control proration behavior: 
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

​
Cancel at period end

Schedule a cancellation without immediate termination of access: 
await client.subscriptions.update('sub_123', {
  cancel_at_period_end: true
});

​
On‑demand subscriptions

Create an on‑demand subscription and charge later as needed: 
const onDemand = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_on_demand',
  on_demand: true
});

await client.subscriptions.createCharge(onDemand.id, {
  amount: 4900,
  currency: 'USD',
  description: 'Extra usage for September'
});

​
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.
⌘I