Skip to main content

​
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.
You cannot mix subscription products with one-time products in the same checkout session.
  • Node.js SDK
  • Python SDK
  • REST API
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

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:
  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.
For reliable subscription lifecycle management, we recommend tracking these subscription events.

​
Payment Scenarios

Successful Payment Flow When a payment succeeds, you’ll receive the following webhooks:
  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)
Payment Failure Scenarios
  1. Subscription Failure
  • subscription.failed - Subscription creation failed due to failure to create a mandate.
  • payment.failed - Indicates failed payment.
Best Practice: To simplify implementation, we recommend primarily tracking subscription events for managing the subscription lifecycle.

​
Sample Subscription event payload

PropertyTypeRequiredDescription
business_idstringYesThe unique identifier for the business
timestampstringYesThe timestamp of when the event occurred (not necessarily the same as when it was delivered)
typestringYesThe type of event. See Event Types
dataobjectYesThe 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. Contact support to enable this feature.
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: For subsequent charges, use the POST /subscriptions/charge endpoint and specify the amount to charge the customer for that transaction.
For a complete, step-by-step guide—including request/response examples, safe retry policies, and webhook handling—see the On-Demand Subscriptions Guide.