Dodo Payments Subscription Integration

Reference: docs.dodopayments.com/developer-resources/subscription-integration-guide

Implement recurring billing with trials, plan changes, and usage-based pricing.

Quick Start

1. Create Subscription Product

In the dashboard (Products → Create Product):

• Select "Subscription" type

• Set billing interval (monthly, yearly, etc.)

• Configure pricing

2. Create Checkout Session

import DodoPayments from 'dodopayments';

const client = new DodoPayments({

  bearerToken: process.env.DODO_PAYMENTS_API_KEY,

});

const session = await client.checkoutSessions.create({

  product_cart: [

    { product_id: 'prod_monthly_plan', quantity: 1 }

  ],

  subscription_data: {

    trial_period_days: 14, // Optional trial

  },

  customer: {

    email: 'subscriber@example.com',

    name: 'Jane Doe',

  },

  return_url: 'https://yoursite.com/success',

});

// Redirect to session.checkout_url

3. Handle Webhook Events

// subscription.active - Grant access

// subscription.cancelled - Schedule access revocation

// subscription.renewed - Log renewal

// payment.succeeded - Track payments

Subscription Lifecycle

┌─────────────┐     ┌─────────┐     ┌────────┐

│   Created   │ ──▶ │  Trial  │ ──▶ │ Active │

└─────────────┘     └─────────┘     └────────┘

                                         │

                    ┌────────────────────┼────────────────────┐

                    ▼                    ▼                    ▼

              ┌──────────┐        ┌───────────┐        ┌───────────┐

              │ On Hold  │        │ Cancelled │        │  Renewed  │

              └──────────┘        └───────────┘        └───────────┘

                    │                    │

                    ▼                    ▼

              ┌──────────┐        ┌───────────┐

              │  Failed  │        │  Expired  │

              └──────────┘        └───────────┘

Webhook Events

Event

When

Action

subscription.active

Subscription starts

Grant access

subscription.updated

Any field changes

Sync state

subscription.on_hold

Payment fails

Notify user, retry

subscription.renewed

Successful renewal

Log, send receipt

subscription.plan_changed

Upgrade/downgrade

Update entitlements

subscription.cancelled

User cancels

Schedule end of access

subscription.failed

Mandate creation fails

Notify, retry options

subscription.expired

Term ends

Revoke access

Implementation Examples

Full Subscription Handler

// app/api/webhooks/subscription/route.ts

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

import { prisma } from '@/lib/prisma';

export async function POST(req: NextRequest) {

  const event = await req.json();

  const data = event.data;

  switch (event.type) {

    case 'subscription.active':

      await handleSubscriptionActive(data);

      break;

    case 'subscription.cancelled':

      await handleSubscriptionCancelled(data);

      break;

    case 'subscription.on_hold':

      await handleSubscriptionOnHold(data);

      break;

    case 'subscription.renewed':

      await handleSubscriptionRenewed(data);

      break;

    case 'subscription.plan_changed':

      await handlePlanChanged(data);

      break;

    case 'subscription.expired':

      await handleSubscriptionExpired(data);

      break;

  }

  return NextResponse.json({ received: true });

}

async function handleSubscriptionActive(data: any) {

  const {

    subscription_id,

    customer,

    product_id,

    next_billing_date,

    recurring_pre_tax_amount,

    payment_frequency_interval,

  } = data;

  // Create or update user subscription

  await prisma.subscription.upsert({

    where: { externalId: subscription_id },

    create: {

      externalId: subscription_id,

      userId: customer.customer_id,

      email: customer.email,

      productId: product_id,

      status: 'active',

      currentPeriodEnd: new Date(next_billing_date),

      amount: recurring_pre_tax_amount,

      interval: payment_frequency_interval,

    },

    update: {

      status: 'active',

      currentPeriodEnd: new Date(next_billing_date),

    },

  });

  // Grant access

  await prisma.user.update({

    where: { id: customer.customer_id },

    data: {

      subscriptionStatus: 'active',

      plan: product_id,

    },

  });

  // Send welcome email

  await sendWelcomeEmail(customer.email, product_id);

}

async function handleSubscriptionCancelled(data: any) {

  const { subscription_id, customer, cancelled_at, cancel_at_next_billing_date } = data;

  await prisma.subscription.update({

    where: { externalId: subscription_id },

    data: {

      status: 'cancelled',

      cancelledAt: new Date(cancelled_at),

      // Keep access until end of billing period if cancel_at_next_billing_date

      accessEndsAt: cancel_at_next_billing_date

        ? new Date(data.next_billing_date)

        : new Date(),

    },

  });

  // Send cancellation email

  await sendCancellationEmail(customer.email, cancel_at_next_billing_date);

}

async function handleSubscriptionOnHold(data: any) {

  const { subscription_id, customer } = data;

  await prisma.subscription.update({

    where: { externalId: subscription_id },

    data: { status: 'on_hold' },

  });

  // Notify user about payment issue

  await sendPaymentFailedEmail(customer.email);

}

async function handleSubscriptionRenewed(data: any) {

  const { subscription_id, next_billing_date } = data;

  await prisma.subscription.update({

    where: { externalId: subscription_id },

    data: {

      status: 'active',

      currentPeriodEnd: new Date(next_billing_date),

    },

  });

}

async function handlePlanChanged(data: any) {

  const { subscription_id, product_id, recurring_pre_tax_amount } = data;

  await prisma.subscription.update({

    where: { externalId: subscription_id },

    data: {

      productId: product_id,

      amount: recurring_pre_tax_amount,

    },

  });

  // Update user entitlements based on new plan

  await updateUserEntitlements(subscription_id, product_id);

}

async function handleSubscriptionExpired(data: any) {

  const { subscription_id, customer } = data;

  await prisma.subscription.update({

    where: { externalId: subscription_id },

    data: { status: 'expired' },

  });

  // Revoke access

  await prisma.user.update({

    where: { id: customer.customer_id },

    data: {

      subscriptionStatus: 'expired',

      plan: null,

    },

  });

}

Subscription with Trial

const session = await client.checkoutSessions.create({

  product_cart: [

    { product_id: 'prod_pro_monthly', quantity: 1 }

  ],

  subscription_data: {

    trial_period_days: 14,

  },

  customer: {

    email: 'user@example.com',

    name: 'John Doe',

  },

  return_url: 'https://yoursite.com/welcome',

});

Customer Portal for Self-Service

Allow customers to manage their subscription:

// Create portal session

const portal = await client.customers.createPortalSession({

  customer_id: 'cust_xxxxx',

  return_url: 'https://yoursite.com/account',

});

// Redirect to portal.url

Portal features:

• View subscription details

• Update payment method

• Cancel subscription

• View billing history

On-Demand (Usage-Based) Subscriptions

For metered/usage-based billing:

Create Subscription with Mandate

const session = await client.checkoutSessions.create({

  product_cart: [

    { product_id: 'prod_usage_based', quantity: 1 }

  ],

  customer: { email: 'user@example.com' },

  return_url: 'https://yoursite.com/success',

});

Charge for Usage

// When usage occurs, create a charge

const charge = await client.subscriptions.charge({

  subscription_id: 'sub_xxxxx',

  amount: 1500, // $15.00 in cents

  description: 'API calls for January 2025',

});

Track Usage Events

// payment.succeeded - Charge succeeded

// payment.failed - Charge failed, implement retry logic

Subscriptions with Credit Entitlements

Attach credit entitlements to subscription products to grant credits each billing cycle:

Setup

• Create a credit entitlement (Dashboard → Products → Credits)

• Create/edit a subscription product

• In Entitlements section, click Attach next to Credits

• Configure: credits per cycle, trial credits, proration, low balance threshold

Checkout with Credits

// Product has credit entitlement attached (e.g., 10,000 AI tokens/month)

const session = await client.checkoutSessions.create({

  product_cart: [

    { product_id: 'prod_pro_with_credits', quantity: 1 }

  ],

  subscription_data: {

    trial_period_days: 14, // Trial credits can differ from regular amount

  },

  customer: { email: 'user@example.com' },

  return_url: 'https://yoursite.com/success',

});

Credit Lifecycle per Cycle

Each billing cycle:

• New credits issued — credit.added webhook fires

• Usage deducts credits — Automatically via meters or manually via API

• Cycle ends — Unused credits expire or roll over based on settings

• Overage handled — Forgiven, billed, or carried as deficit

Handle Credit Webhooks in Subscription Context

case 'credit.added':

  // Credits issued with subscription renewal

  await syncCreditBalance(data.customer_id, data.credit_entitlement_id, data.balance_after);

  break;

case 'credit.balance_low':

  // Notify customer or suggest upgrade

  await sendLowBalanceAlert(data.customer_id, data.credit_entitlement_name, data.available_balance);

  break;

case 'credit.deducted':

  // Track consumption for analytics

  await logCreditUsage(data.customer_id, data.amount);

  break;

Plan Changes with Credits

When customers upgrade/downgrade, credit proration can be enabled:

• Proration enabled: Remaining credits are prorated based on time left in cycle

• Proration disabled: Credits continue as-is until next cycle

Plan Changes

Upgrade/Downgrade Flow

// Get available plans

const plans = await client.products.list({

  type: 'subscription',

});

// Change plan

await client.subscriptions.update({

  subscription_id: 'sub_xxxxx',

  product_id: 'prod_new_plan',

  proration_behavior: 'create_prorations', // or 'none'

});

Handling subscription.plan_changed

async function handlePlanChanged(data: any) {

  const { subscription_id, product_id, customer } = data;

  // Map product to features/limits

  const planFeatures = getPlanFeatures(product_id);

  await prisma.user.update({

    where: { externalId: customer.customer_id },

    data: {

      plan: product_id,

      features: planFeatures,

      apiLimit: planFeatures.apiLimit,

      storageLimit: planFeatures.storageLimit,

    },

  });

}

Access Control Pattern

Middleware Example (Next.js)

// middleware.ts

import { NextResponse } from 'next/server';

import type { NextRequest } from 'next/server';

export async function middleware(request: NextRequest) {

  // Check subscription status

  const session = await getSession(request);

  if (!session?.user) {

    return NextResponse.redirect(new URL('/login', request.url));

  }

  const subscription = await getSubscription(session.user.id);

  // Check if accessing premium feature

  if (request.nextUrl.pathname.startsWith('/dashboard/pro')) {

    if (!subscription || subscription.status !== 'active') {

      return NextResponse.redirect(new URL('/pricing', request.url));

    }

    // Check if plan includes this feature

    if (!subscription.features.includes('pro')) {

      return NextResponse.redirect(new URL('/upgrade', request.url));

    }

  }

  return NextResponse.next();

}

React Hook for Subscription State

// hooks/useSubscription.ts

import useSWR from 'swr';

export function useSubscription() {

  const { data, error, mutate } = useSWR('/api/subscription', fetcher);

  return {

    subscription: data,

    isLoading: !error && !data,

    isError: error,

    isActive: data?.status === 'active',

    isPro: data?.plan?.includes('pro'),

    refresh: mutate,

  };

}

// Usage in component

function PremiumFeature() {

  const { isActive, isPro } = useSubscription();

  if (!isActive) {

    return <UpgradePrompt />;

  }

  if (!isPro) {

    return <ProUpgradePrompt />;

  }

  return <ActualFeature />;

}

Common Patterns

Grace Period for Failed Payments

async function handleSubscriptionOnHold(data: any) {

  const gracePeriodDays = 7;

  await prisma.subscription.update({

    where: { externalId: data.subscription_id },

    data: {

      status: 'on_hold',

      gracePeriodEnds: new Date(Date.now() + gracePeriodDays * 24 * 60 * 60 * 1000),

    },

  });

  // Schedule job to revoke access after grace period

  await scheduleAccessRevocation(data.subscription_id, gracePeriodDays);

}

Prorated Upgrades

When upgrading mid-cycle:

// Dodo handles proration automatically

// Customer pays difference for remaining days

await client.subscriptions.update({

  subscription_id: 'sub_xxxxx',

  product_id: 'prod_higher_plan',

  proration_behavior: 'create_prorations',

});

Cancellation with End-of-Period Access

// subscription.cancelled event includes:

// - cancel_at_next_billing_date: boolean

// - next_billing_date: string (when access should end)

if (data.cancel_at_next_billing_date) {

  // Keep access until next_billing_date

  await scheduleAccessRevocation(

    data.subscription_id,

    new Date(data.next_billing_date)

  );

}

Testing

Test Scenarios

• New subscription → subscription.active

• Renewal success → subscription.renewed + payment.succeeded

• Renewal failure → subscription.on_hold + payment.failed

• Plan upgrade → subscription.plan_changed

• Cancellation → subscription.cancelled

• Expiration → subscription.expired

Test in Dashboard

Use test mode and trigger events manually from the webhook settings.

Resources

• Subscription Guide

• On-Demand Subscriptions

• Webhook Events

• Customer Portal

• Credit-Based Billing

• Credit Webhook Events