Subscriptions - Dodo Payments Documentation

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

가격 유형: 구독을 선택합니다(이 가이드). 대안으로는 단일 결제와 사용량 기반 청구가 있습니다.
가격(필수): 통화가 포함된 기본 반복 요금. 가격은 최소 $1(또는 선택한 통화와 동등한 금액) 이상이어야 합니다. 이 최소 금액 이하의 요금은 지원되지 않으며, 구독이 작동하지 않습니다.
할인 적용 가능(%): 기본 가격에 적용되는 선택적 할인 비율; 체크아웃 및 청구서에 반영됩니다.
반복 결제 간격(필수): 갱신 간격, 예: 매 1개월. 주기(달 또는 연도)와 수량을 선택합니다.
구독 기간(필수): 구독이 활성 상태로 유지되는 총 기간(예: 10년). 이 기간이 끝나면 갱신이 중단되며 연장되지 않는 한 종료됩니다.
체험 기간 일수(필수): 체험 기간을 일 단위로 설정합니다. 체험을 비활성화하려면 0을 사용하십시오. 체험이 끝나면 첫 번째 요금이 자동으로 청구됩니다.
추가 기능 선택: 최대 10개의 추가 기능을 기본 플랜과 함께 고객이 구매할 수 있도록 첨부합니다.

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. Depending on the proration mode you select, a change may trigger an immediate charge, create credit, or apply no billing adjustment.

You can change subscription plans and update the next billing date directly from the Dodo Payments dashboard. This provides a quick way to adjust subscriptions for customer support requests, promotional upgrades, or plan migrations without making API calls.

Enable self-service plan changes: Want customers to upgrade or downgrade their own subscriptions via the Customer Portal? Add your subscription products to a Product Collection and enable “Allow Subscription Updates” in your Subscription Settings.

Product Collections

Group related products into collections to enable seamless upgrade/downgrade paths in the Customer Portal.

Proration Modes

Choose how customers are billed when changing plans:

Quick comparison of the four proration modes:

	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Upgrade	Prorated charge for remaining days	Full price difference charged	Full new plan price charged	No charge — switch immediately
Downgrade	Prorated credit for remaining days	Full price difference as credit	No credit, full charge	No credit — switch immediately
Billing cycle	Stays the same	Stays the same	Resets to today	Stays the same
Best for	Fair time-based billing	Simple tier changes	Billing cycle resets	Free migrations or courtesy switches

`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 Credit-Based Billing entitlements.

When a customer downgrades with difference_immediately, the unused value becomes a subscription-scoped credit that automatically offsets future renewals:

`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'
});

`do_not_bill`

Switches to the new plan without any billing adjustment. No proration charges, no credits — the customer simply moves to the new plan. Best for courtesy migrations, free plan switches, or scenarios where you want to absorb the cost difference.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});

Example: Prorated upgrade calculation

Scenario: Customer on Basic (

30/month) upgrades to Pro (

80/month) on day 16 of a 30-day cycle using prorated_immediately.

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

Next renewal on the original billing date: $80.00/month.

For more detailed calculation examples and edge cases, see our full Upgrade & Downgrade Guide.

Example: Downgrade credit calculation

Scenario: Customer on Pro (

80/month) downgrades to Starter (

20/month) using difference_immediately.

Credit = Old plan − New plan = $80 − $20 = $60.00

The $60 credit auto-applies to future renewals:

Renewal 1: $20 −$ 20 (credit) = ** $0.00** ($ 40 credit remaining)
Renewal 2: $20 −$ 20 (credit) = ** $0.00** ($ 20 credit remaining)
Renewal 3: $20 −$ 20 (credit) = $0.00 (credit exhausted)
Renewal 4: $20.00 (full price)

Learn more about how credits are managed in the Upgrade & Downgrade Guide.

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.

Previewing Plan Changes

Before committing to a plan change, preview the exact charge and resulting subscription:

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

Preview Change Plan API

Preview plan changes before committing to them.

Subscription States

Subscriptions can be in different states throughout their lifecycle:

active: Subscription is active and will renew automatically
on_hold: Subscription is paused due to failed payment. Payment method update required to reactivate
cancelled: Subscription is cancelled and will not renew
expired: Subscription has reached its end date
pending: Subscription is being created or processed

On Hold State

A subscription enters on_hold state when:

A renewal payment fails (insufficient funds, expired card, etc.)
A plan change charge fails
Payment method authorization fails

When a subscription is in on_hold state, it will not renew automatically. You must update the payment method to reactivate the subscription.

Reactivating from On Hold

To reactivate a subscription from on_hold state, update the payment method. This automatically:

Creates a charge for remaining dues
Generates an invoice
Processes the payment using the new payment method
Reactivates the subscription to active state upon successful payment

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

After successfully updating the payment method for an on_hold subscription, you’ll receive payment.succeeded followed by subscription.active webhook events.

API Management

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

Use PATCH /subscriptions/{id} to update quantities, cancel at next billing date, or modify metadata.

API Reference

Learn how to update subscription details.

Change plans (proration)

Change the active product and quantities with proration controls.

API Reference

Review plan change options.

On‑demand charges

For on‑demand subscriptions, charge specific amounts on demand.

API Reference

Charge an on‑demand subscription.

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

Fetch recorded usage for metered or hybrid pricing models.

API Reference

See usage history API.

Update payment method

Update the payment method for a subscription. For active subscriptions, this updates the payment method for future renewals. For subscriptions in on_hold state, this reactivates the subscription by creating a charge for remaining dues.

API Reference

Learn how to update payment methods and reactivate subscriptions.

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 next billing date

Schedule a cancellation that takes effect at the end of the current billing period:

await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: 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.charge(onDemand.id, {
  amount: 4900,
  currency: 'USD',
  description: 'Extra usage for September'
});

Update payment method for active subscription

Update the payment method for an active subscription:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

Reactivate subscription from on_hold

Reactivate a subscription that went on hold due to failed payment:

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  type: 'new',
  return_url: 'https://example.com/return'
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

Subscriptions with RBI-Compliant Mandates

UPI and Indian card subscriptions operate under RBI (Reserve Bank of India) regulations with specific mandate requirements:

Mandate Limits

The mandate type and amount depend on your subscription’s recurring charge:

Charges below Rs 15,000: We create an on-demand mandate for Rs 15,000 INR. The subscription amount is charged periodically according to your subscription frequency, up to the mandate limit.
Charges Rs 15,000 or above: We create a subscription mandate (or on-demand mandate) for the exact subscription amount.

For detailed information about RBI-compliant mandates for Indian payment methods, see the India Payment Methods page.

Upgrade and Downgrade Considerations

Important: When upgrading or downgrading subscriptions, carefully consider the mandate limits:

If an upgrade/downgrade results in a charge amount that exceeds Rs 15,000 and goes beyond the existing on-demand payment limit, the transaction charge may fail.
In such cases, the customer may need to update their payment method or change the subscription again to establish a new mandate with the correct limit.

Authorization for High-Value Charges

For subscription charges of Rs 15,000 or more:

The customer will be prompted by their bank to authorize the transaction.
If the customer fails to authorize the transaction, the transaction will fail and the subscription will be put on hold.

48-Hour Processing Delay

Processing Timeline: Recurring charges on Indian cards and UPI subscriptions follow a unique processing pattern:

Charges are initiated on the scheduled date according to your subscription frequency.
The actual deduction from the customer’s account occurs only after 48 hours from payment initiation.
This 48-hour window may extend up to 2-3 additional hours depending on bank API responses.

Mandate Cancellation Window

During the 48-hour processing window:

Customers can cancel the mandate via their banking apps.
If a customer cancels the mandate during this period, the subscription will remain active (this is an edge case specific to Indian card and UPI AutoPay subscriptions).
However, the actual deduction may fail, and in that case, we will put the subscription on hold.

Edge Case Handling: If you provide benefits, credits, or subscription usage to customers immediately upon charge initiation, you need to handle this 48-hour window appropriately in your application. Consider:

Delaying benefit activation until payment confirmation
Implementing grace periods or temporary access
Monitoring subscription status for mandate cancellations
Handling subscription hold states in your application logic

Monitor subscription webhooks to track payment status changes and handle edge cases where mandates are cancelled during the 48-hour window.

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.

구독은 반복 수익을 위한 유연한 기반입니다. 간단하게 시작하고, 철저히 테스트하며, 채택, 이탈 및 확장 지표에 따라 반복하세요.

48시간 처리 창 동안:

고객은 은행 앱을 통해 맨데이트를 취소할 수 있습니다.
고객이 이 기간 동안 맨데이트를 취소하면 구독은 활성 상태로 유지됩니다(이는 인도 카드 및 UPI AutoPay 구독의 특정 경계 사례입니다).
그러나 실제 공제가 실패할 수 있으며, 이 경우 구독을 보류 상태로 전환합니다.

경계 사례 처리: 고객에게 청구 시점에 즉시 혜택, 크레딧 또는 구독 사용을 제공하는 경우 이 48시간 창을 애플리케이션에서 적절히 처리해야 합니다. 고려할 사항:

혜택 활성화를 결제 확인까지 지연
유예 기간 또는 임시 접근 구현
맨데이트 취소에 대한 구독 상태 모니터링
애플리케이션 논리에서 구독 보류 상태 처리

구독 웹훅을 모니터링하여 결제 상태 변경을 추적하고 48시간 창 동안 맨데이트가 취소되는 경계 사례를 처리합니다.

모범 사례

명확한 티어 시작: 2–3개의 명확한 차이가 있는 플랜
가격 소통: 총액, 비례 배분 및 다음 갱신 표시
체험을 신중하게 사용: 단순한 시간보다 온보딩으로 전환
추가 기능 활용: 기본 플랜을 간단하게 유지하고 추가 항목 판매
변경 사항 테스트: 계획 변경 및 비례 배분을 테스트 모드에서 확인

구독은 반복 수익의 유연한 기반입니다. 간단하게 시작하고 철저하게 테스트하며, 채택, 이탈 및 확장 지표에 따라 반복합니다.

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​What Are Subscriptions?

​Key Benefits

​Creating Subscriptions

​Subscription product creation

​Product details

​Pricing

​Advanced settings

​Subscription Trials

​Configuring Trials

​Detecting Trial Status

​Updating Trial Period

​Subscription Plan Changes

Product Collections

​Proration Modes

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​Changing Plans with Add-ons

​Previewing Plan Changes

Preview Change Plan API

​Subscription States

​On Hold State

​Reactivating from On Hold

​API Management

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​Common Use Cases

​Integration Examples

​Checkout Sessions (subscriptions)

​Plan changes with proration

​Cancel at next billing date

​On‑demand subscriptions

​Update payment method for active subscription

​Reactivate subscription from on_hold

​Subscriptions with RBI-Compliant Mandates

​Mandate Limits

​Upgrade and Downgrade Considerations

​Authorization for High-Value Charges

​48-Hour Processing Delay

​Mandate Cancellation Window

​Best Practices

​모범 사례

What Are Subscriptions?

Key Benefits

Creating Subscriptions

Subscription product creation

Product details

Pricing

Advanced settings

Subscription Trials

Configuring Trials

Detecting Trial Status

Updating Trial Period

Subscription Plan Changes

Proration Modes

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

Changing Plans with Add-ons

Previewing Plan Changes

Subscription States

On Hold State

Reactivating from On Hold

API Management

Common Use Cases

Integration Examples

Checkout Sessions (subscriptions)

Plan changes with proration

Cancel at next billing date

On‑demand subscriptions

Update payment method for active subscription

Reactivate subscription from on_hold

Subscriptions with RBI-Compliant Mandates

Mandate Limits

Upgrade and Downgrade Considerations

Authorization for High-Value Charges

48-Hour Processing Delay

Mandate Cancellation Window

Best Practices

모범 사례