Subscription Integration Guide

​

Prerequisites

• A Dodo Payments merchant account
• API credentials (API key and webhook secret key) from the dashboard

​

API Integration

​

Checkout Sessions

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});

async function main() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'prod_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();

​

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 successfully activated.
2. subscription.on_hold - Subscription is put on hold due to failed renewal.
3. subscription.failed - Subscription creation failed during mandate creation.
4. subscription.renewed - Subscription is renewed for the next billing period.

​

Payment Scenarios

1. subscription.active - Indicates subscription activation
2. payment.succeeded - Confirms the initial payment:
   • For immediate billing (0 trial days): Expect within 2-10 minutes
   • For trial days: whenever that ends
3. subscription.renewed - Indicates payment deduction and renewal for next cycle. (Basically, whenever payment gets deducted for subscription products, you will get subscription.renewed webhook along with payment.succeeded)

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.
• When a subscription goes on hold, it will not renew automatically until the payment method is updated.

​

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, {
  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
}

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  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

• Calculates the prorated amount based on the remaining time in the current billing cycle
• Charges the customer only for the difference between the old and new plan
• 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
• Ignores any remaining time or credits from the previous plan
• Useful when you want to reset the billing cycle or charge the full amount regardless of proration

​

3. difference_immediately

• When upgrading, the customer is immediately charged the difference between the two plan amounts.
• For example, if the current plan is 30 Dollars and the customer upgrades to an 80 Dollars, they are charged $50 instantly.
• When downgrading, the unused amount from the current plan is added as internal credit and automatically applied to future subscription renewals.
• For example, if the current plan is 50 Dollars and the customer switches to a 20 Dollars plan, the remaining $30 is credited and used toward the next billing cycle.

​

Behavior

• When you invoke this API, Dodo Payments immediately initiates a charge based on your selected proration option
• If the plan change is a downgrade and you use prorated_immediately, credits will be automatically calculated and 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
• The full_immediately option bypasses credit calculations and charges the complete new plan amount

​

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