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.

​
Subscription Trials

Trials let customers access subscriptions without immediate payment. The first charge occurs automatically when the trial ends.

​
Configuring Trials

Set Trial Period Days in the product pricing section (use 0 to disable). You can override this when creating subscriptions: 
// Via subscription creation
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_monthly',
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});
The trial_period_days value must be between 0 and 10,000 days.

​
Detecting Trial Status

Currently, there is no direct field to detect trial status. The following is a workaround that requires querying payments, which is inefficient. We are working on a more efficient solution.
To determine if a subscription is in trial, retrieve the list of payments for the subscription. If there is exactly one payment with amount 0, the subscription is in trial period: 
const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

​
Updating Trial Period

Extend the trial by updating next_billing_date: 
await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});
You cannot set next_billing_date to a past time. The date must be in the future.

​
Subscription Plan Changes

Plan changes let you upgrade or downgrade subscriptions, adjust quantities, or migrate to different products. Each change triggers an immediate charge based on the proration mode you select.

​
Proration Modes

Choose how customers are billed when changing plans:

​
prorated_immediately

Charges prorated amount based on remaining time in the current billing cycle. Best for fair billing that accounts for unused time. 
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

​
difference_immediately

Charges the price difference immediately (upgrade) or adds credit for future renewals (downgrade). Best for simple upgrade/downgrade scenarios. 
// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});
Credits from downgrades using difference_immediately are subscription-scoped and auto-applied to future renewals. They’re distinct from Customer Credits.

​
full_immediately

Charges full new plan amount immediately, ignoring remaining time. Best for resetting billing cycles. 
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});

​
Changing Plans with Add-ons

Modify add-ons when changing plans. Add-ons are included in proration calculations: 
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});
Plan changes trigger immediate charges. Failed charges may move the subscription to on_hold status. Track changes via subscription.plan_changed webhook events.

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