Subscription Integration Guide

​

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

If you don’t have an account yet, you can get your business approved by contacting the founder or by filling out this form.

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

​

API Integration

​

Payment Links

Dodo Payments supports two types of payment links:

​

1. Static Payment Links

Detailed Guide

​

2. Dynamic Payment Links

Created via API call or our SDK with customer details. Here’s an example:

There are two APIs for creating dynamic payment links:

• Subscription Payment Link API - API reference
• One-time Payment Link API - API reference

The guide below focuses on subscription payment link creation.

For detailed instructions on integrating one-time products, refer to this One-time Integration Guide.

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});

async function main() {
const subscription = await client.subscriptions.create({
billing: { city: 'city', country: 'IN', state: 'state', street: 'street', zipcode: 89789 },
customer: { customer_id: 'customer_id' },
product_id: 'product_id',
payment_link: true,
return_url: 'https://example.com/success',
quantity: 1,
});

console.log(subscription.subscription_id);
}

main();

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
});

async function main() {
const subscription = await client.subscriptions.create({
billing: { city: 'city', country: 'IN', state: 'state', street: 'street', zipcode: 89789 },
customer: { customer_id: 'customer_id' },
product_id: 'product_id',
payment_link: true,
return_url: 'https://example.com/success',
quantity: 1,
});

console.log(subscription.subscription_id);
}

main();

import os
from dodopayments import DodoPayments

client = DodoPayments(
  bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
)
subscription = client.subscriptions.create(
  billing={
      "city": "city",
      "country": "IN",
      "state": "state",
      "street": "street",
      "zipcode": 54535,
  },
  customer={
      "customer_id": "customer_id"
  },
  product_id="product_id",
  quantity=1,
  payment_link: true,
  return_url: 'https://example.com/success',
)
print(subscription.subscription_id)

package main

import (
"context"
"fmt"

"github.com/dodopayments/dodopayments-go"
"github.com/dodopayments/dodopayments-go/option"
)

func main() {
client := dodopayments.NewClient(
  option.WithBearerToken("My Bearer Token"), // defaults to os.LookupEnv("DODO_PAYMENTS_API_KEY")
)
subscription, err := client.Subscriptions.New(context.TODO(), dodopayments.SubscriptionNewParams{
  Billing: dodopayments.F(dodopayments.SubscriptionNewParamsBilling{
    City: dodopayments.F("city"),
    Country: dodopayments.F(dodopayments.CountryCodeIn),
    State: dodopayments.F("state"),
    Street: dodopayments.F("street"),
    Zipcode: dodopayments.F(int64(65787)),
  }),
  Customer: dodopayments.F[dodopayments.SubscriptionNewParamsCustomerUnion](dodopayments.SubscriptionNewParamsCustomerAttachExistingCustomer{
    CustomerID: dodopayments.F("customer_id"),
  }),
  ProductID: dodopayments.F("product_id"),
  Quantity: dodopayments.F(int64(1)),
})
if err != nil {
  panic(err.Error())
}
fmt.Printf("%+v\n", subscription.SubscriptionID)
}

import { NextRequest, NextResponse } from "next/server";      

export async function POST(request: NextRequest) {
try {
const body = await request.json();
const { formData, cartItems } = paymentRequestSchema.parse(body);

const response = await fetch(`${process.env.NEXT_PUBLIC_DODO_TEST_API}/subscriptions`, {
method: "POST",
headers: {
  "Content-Type": "application/json",
  Authorization: `Bearer ${process.env.DODO_API_KEY}`, // Replace with your API secret key generated from the Dodo Payments Dashboard
},
body: JSON.stringify({
  billing: {
    city: formData.city,
    country: formData.country,
    state: formData.state,
    street: formData.addressLine,
    zipcode: parseInt(formData.zipCode),
  },
  customer: {
    email: formData.email,
    name: `${formData.firstName} ${formData.lastName}`,
    phone_number: formData.phoneNumber || undefined,
  },
  payment_link: true,
  product_id: id,
  quantity: 1,
  return_url: process.env.NEXT_PUBLIC_RETURN_URL,
}),
});

if (!response.ok) {
const errorData = await response.json().catch(() => null);
return NextResponse.json(
  { error: "Payment link creation failed", details: errorData },
  { status: response.status }
);
}

const data = await response.json();
return NextResponse.json({ paymentLink: data.payment_link });
} catch (err) {
console.error("Payment error:", err);
return NextResponse.json(
{
  error: err instanceof Error ? err.message : "An unknown error occurred",
},
{ status: 500 }
);
}
}

​

API Response

The following is an example of the response:

{
  "client_secret": "<string>",
  "customer": {
    "customer_id": "<string>",
    "email": "<string>",
    "name": "<string>"
  },
  "metadata": {},
  "payment_link": "<string>",
  "recurring_pre_tax_amount": 1,
  "subscription_id": "<string>"
}

Redirect the customer to payment_link.

​

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.renewal 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.

​

Sample Subscription event payload

​

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.

​

Behavior

• When you invoke this API, Dodo Payments immediately initiates a charge, which includes proration based on the new plan.
• If the plan change is a downgrade, 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.
• During a trial period, selecting prorated_immediately will immediately switch the user to the new plan, charging the customer right away.

​

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.

​

Data Object

The data object contains the following properties:

​

Enums

​

Time Intervals

Both payment_frequency_interval and subscription_period_interval accept the following values:

• Day
• Week
• Month
• Year

​

Status

The status field can have the following values:

• pending - Initial state
• active - Subscription is active
• on_hold - Temporarily on hold
• renewed - New Billing Cycle started
• paused - Paused by user or system
• cancelled - Subscription has been cancelled
• failed - Payment or other failure
• expired - Subscription has expired

​

Event Types

​

Subscription Events

• subscription.active
• subscription.on_hold
• subscription.paused
• subscription.cancelled
• subscription.failed
• subscription.expired
• subscription.plan_changed