Subscription Integration Guide

​

Prerequisites

• A Dodo Payments merchant account
• An API key from Developer → API Keys in the dashboard, stored in DODO_PAYMENTS_API_KEY
• A webhook secret from Developer → Webhooks, stored in DODO_PAYMENTS_WEBHOOK_KEY
• At least one subscription product created under Products

​

API Integration

​

Checkout Sessions

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

session = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "pdt_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

​

API Response

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

​

Webhooks

​

Subscription Event Types

1. subscription.active — Subscription is activated
2. subscription.updated — A field on the subscription changed
3. subscription.on_hold — A renewal or plan-change charge failed
4. subscription.failed — Subscription creation failed (terminal; customer must resubscribe)
5. subscription.renewed — A recurring charge succeeded
6. subscription.past_due — A renewal failed and the grace period started; the customer keeps access until past_due_ends_at
7. subscription.plan_changed — The plan was upgraded, downgraded, or changed
8. subscription.cancelled — The subscription was cancelled
9. subscription.expired — The subscription reached the end of its term

​

Payment Scenarios

1. subscription.active: the mandate is authorized and the subscription is activated.
2. payment.succeeded: confirms the first charge. Expect this within 2–10 minutes of checkout.

1. At trial start (checkout): subscription.active fires once the payment method is authorized. No recurring charge is taken yet. The first real charge is deferred until the trial ends.
2. At trial end: the recurring amount is charged, and you receive payment.succeeded together with subscription.renewed.

• subscription.renewed: fires on each billing cycle when the renewal payment is deducted, always alongside payment.succeeded. It also carries the updated next_billing_date.

1. Subscription Failure

• subscription.failed - Subscription creation failed due to failure to create a mandate.
• payment.failed - Indicates failed payment.

2. Subscription On Hold

• subscription.on_hold - Subscription is put on hold due to failed renewal payment or failed plan change charge. If your business has a grace period, a failed renewal first moves the subscription to past_due (subscription.past_due), and it moves to on_hold (or cancelled, depending on your grace period settings) only when the grace period ends. See Subscription States.
• When a subscription goes on hold, it will not renew automatically until the payment method is updated.

​

subscription.failed vs. subscription.on_hold

​

Handling Subscription On Hold

​

When Subscriptions Go On Hold

• Renewal payment fails: The automatic renewal charge fails due to insufficient funds, expired card, or bank decline
• Plan change charge fails: An immediate charge during plan upgrade/downgrade fails
• Payment method authorization fails: The payment method cannot be authorized for recurring charges

​

Reactivating Subscriptions from On Hold

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

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { 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 for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    payment_method={"type": "new", "return_url": "https://example.com/return"},
)

# For on_hold subscriptions, a charge is automatically created
if response.payment_id:
    print("Charge created for remaining dues:", response.payment_id)
    # Redirect customer to response.payment_link to complete payment

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { type: 'existing', payment_method_id: 'pm_abc123' }
});

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

​

Sample Subscription Event Payload

​

Changing Subscription Plans

​

Proration Options

​

1. prorated_immediately

• Credits the unused portion of the current billing cycle, prorated by the time remaining. The credit covers the base plan, quantity, and any add-ons
• Then charges a full cycle at the new plan, quantity, and add-ons. The charge itself is never prorated
• Net immediate charge = (full new cycle) minus (remaining fraction x full old cycle). If the credit is larger, the difference is held as subscription-scoped credit for future renewals
• During a trial period, this will immediately switch the user to the new plan, charging the customer right away

​

2. full_immediately

• Charges the customer the full subscription amount for the new plan with no credit for the previous cycle
• On upgrade or downgrade alike, the customer pays the entire new plan price from scratch
• Useful when you want to charge the full amount regardless of how much time was left on the old plan

​

3. difference_immediately

• The customer pays only the gap between the old plan price and the new plan price
• The amount does not depend on when in the cycle the change is made. The same upgrade costs the same on day 1 and on day 29
• When upgrading, the customer is immediately charged the difference. For example, $30/month → $80/month = $50 charged instantly
• When downgrading, the price difference is stored as subscription-scoped credit and applied automatically to future renewals. For example, $50/month → $20/month = $30 stored as credit

​

4. do_not_bill

• Applies the plan change immediately but does not charge anything at the time of the change. The new plan, quantity, and add-ons are usable straight away
• Because nothing is charged now, an upgrade gives the customer the higher plan free for the remainder of the current cycle. A downgrade takes effect immediately with no credit for the unused portion of the cycle they have already paid for
• Add-ons granted through do_not_bill are not credited on a later plan change, because they were never billed. A subsequent change bills the new add-on quantity in full
• The updated plan (and quantity/add-ons) is billed at the next scheduled renewal, and the original billing date is preserved

​

Behavior

• When you invoke this API, Dodo Payments immediately initiates a charge based on your selected proration option
• With prorated_immediately, a credit for the unused portion of the current cycle is calculated on every change, upgrade or downgrade alike. If that credit exceeds the new cycle charge, the remainder is added to the subscription’s credit balance. These credits are specific to that subscription and will only be used to offset future recurring payments of the same subscription
• With difference_immediately, the net is always the exact price difference. For downgrades, the excess is stored as subscription-scoped credit, the same as prorated_immediately
• The full_immediately option bypasses credit calculations and charges the complete new plan amount
• The do_not_bill option applies the change immediately but defers billing to the next renewal date, which is preserved

​

Charge Processing

• The immediate charge initiated upon plan change usually completes processing in less than 2 minutes
• If this immediate charge fails for any reason, the subscription is automatically placed on hold until the issue is resolved

​

On-Demand Subscriptions

​

Key Things to Know About Subscription Billing

​

Related API Reference