Subscription Integration Guide - Dodo Payments Documentation

Prerequisites

To integrate the Dodo Payments API, you’ll need:

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

For a more detailed guide on the prerequisites, check this section.

API Integration

Checkout Sessions

Use Checkout Sessions to sell subscription products with a secure, hosted checkout. Pass your subscription product in product_cart and redirect customers to the returned checkout_url.

Mixed Checkout: You can combine subscription products with one-time products in the same checkout session. This enables use cases like setup fees with subscriptions, hardware bundles with SaaS, and more. See the Checkout Sessions guide for examples.

Node.js SDK
Python SDK
REST API

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: '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();

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": "prod_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: 'prod_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

The following is an example of the response:

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

Redirect the customer to checkout_url.

Webhooks

When integrating subscriptions, you’ll receive webhooks to track the subscription lifecycle. These webhooks help you manage subscription states and payment scenarios effectively. To set up your webhook endpoint, please follow our Detailed Integration Guide.

Subscription Event Types

The following webhook events track subscription status changes:

subscription.active - Subscription is successfully activated.
subscription.updated - Subscription object was updated (fires on any field change).
subscription.on_hold - Subscription is put on hold due to failed renewal.
subscription.failed - Subscription creation failed during mandate creation.
subscription.renewed - Subscription is renewed for the next billing period.

For reliable subscription lifecycle management, we recommend tracking these subscription events.

Use subscription.updated to get real-time notifications about any subscription changes, keeping your application state in sync without polling the API.

Payment Scenarios

Successful Payment Flow When a payment succeeds, you’ll receive the following webhooks:

subscription.active - Indicates subscription activation
payment.succeeded - Confirms the initial payment:
- For immediate billing (0 trial days): Expect within 2-10 minutes
- For trial days: whenever that ends
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)

Payment Failure Scenarios

Subscription Failure

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

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.

Best Practice: To simplify implementation, we recommend primarily tracking subscription events for managing the subscription lifecycle.

Handling Subscription On Hold

When a subscription enters on_hold state, you need to update the payment method to reactivate it. This section explains when subscriptions go on hold and how to handle them.

When Subscriptions Go On Hold

A subscription is placed on hold when:

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

Subscriptions in on_hold state will not renew automatically. You must update the payment method to reactivate the subscription.

Reactivating Subscriptions from On Hold

To reactivate a subscription from on_hold state, use the Update Payment Method API. This automatically:

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

Handle subscription.on_hold webhook

When you receive a subscription.on_hold webhook, update your application state and notify the customer:

// 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 payment method

When the customer is ready to update their payment method, call the Update Payment Method API:

// 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
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    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

You can also use an existing payment method ID if the customer has saved payment methods:

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

Monitor webhook events

After updating the payment method, monitor for these webhook events:

payment.succeeded - The charge for remaining dues was successful
subscription.active - The subscription has been reactivated

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

Property	Type	Required	Description
`business_id`	string	Yes	The unique identifier for the business
`timestamp`	string	Yes	The timestamp of when the event occurred (not necessarily the same as when it was delivered)
`type`	string	Yes	The type of event. See Event Types
`data`	object	Yes	The main data payload. See Data Object

Changing Subscription Plans

You can upgrade or downgrade a subscription plan using the change plan API endpoint. This allows you to modify the subscription’s product, quantity, and handle proration.

Change Plan API Reference

For detailed information about changing subscription plans, please refer to our Change Plan API documentation.

Proration Options

When changing subscription plans, you have two options for handling the immediate charge:

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

Choose your proration option carefully: Use prorated_immediately for fair billing that accounts for unused time, or full_immediately when you want to charge the complete new plan amount regardless of the current billing cycle.

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

On-demand subscriptions let you charge customers flexibly, not just on a fixed schedule. This feature is available for all accounts.

To create an on-demand subscription: To create an on-demand subscription, use the POST /subscriptions API endpoint and include the on_demand field in your request body. This allows you to authorize a payment method without an immediate charge, or set a custom initial price. To charge an on-demand subscription: Pour les charges suivantes, utilisez l’endpoint POST /subscriptions//charge et spécifiez le montant à facturer au client pour cette transaction.

For a complete, step-by-step guide—including request/response examples, safe retry policies, and webhook handling—see the On-Demand Subscriptions Guide.

Create Subscription

API reference for creating subscription products and managing subscription lifecycle

Change Subscription Plan

API reference for upgrading, downgrading, or changing subscription plans with proration options

Update Payment Method

API reference for updating payment methods and reactivating on-hold subscriptions

Patch Subscription

API reference for updating subscription details and configuration

Pour facturer un abonnement à la demande : Pour les charges ultérieures, utilisez le point de terminaison POST /subscriptions//charge et spécifiez le montant à facturer au client pour cette transaction.

Pour un guide complet, étape par étape—y compris des exemples de requêtes/réponses, des politiques de nouvelle tentative sûres, et la gestion des webhooks—voir le Guide des Abonnements à la Demande.

Référence API Connexe

Create Subscription

Référence API pour créer des produits d’abonnement et gérer le cycle de vie de l’abonnement

Change Subscription Plan

Référence API pour mettre à niveau, rétrograder ou changer les plans d’abonnement avec des options de prorata

Update Payment Method

Référence API pour mettre à jour les méthodes de paiement et réactiver les abonnements en attente

Patch Subscription

Référence API pour mettre à jour les détails et la configuration de l’abonnement

​Prerequisites

​API Integration

​Checkout Sessions

​API Response

​Webhooks

​Subscription Event Types

​Payment Scenarios

​Handling Subscription On Hold

​When Subscriptions Go On Hold

​Reactivating Subscriptions from On Hold

​Sample Subscription event payload

​Changing Subscription Plans

Change Plan API Reference

​Proration Options

​1. prorated_immediately

​2. full_immediately

​3. difference_immediately

​Behavior

​Charge Processing

​On-Demand Subscriptions

​Related API Reference

Create Subscription

Change Subscription Plan

Update Payment Method

Patch Subscription

​Référence API Connexe

Create Subscription

Change Subscription Plan

Update Payment Method

Patch Subscription

Prerequisites

API Integration

Checkout Sessions

API Response

Webhooks

Subscription Event Types

Payment Scenarios

Handling Subscription On Hold

When Subscriptions Go On Hold

Reactivating Subscriptions from On Hold

Sample Subscription event payload

Changing Subscription Plans

Proration Options

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

Behavior

Charge Processing

On-Demand Subscriptions

Related API Reference

Référence API Connexe