Subscription Integration

Dodo Payments Subscription Integration

Implement recurring billing with trials, plan changes, and on-demand charging. Subscriptions are created through Checkout Sessions, managed via the subscriptions API, and monitored through webhooks.

When to use this skill

• Building a subscription product with recurring billing and trials
• Handling plan upgrades, downgrades, and migrations mid-cycle
• Implementing on-demand/off-session charging with mandates
• Managing failed payments and dunning recovery
• Building a customer self-service portal for subscription management

Core Concepts

Subscription lifecycle: The eight subscription statuses are pending, active, past_due, on_hold, paused, cancelled, failed, and expired. A trialing subscription reports active; subscription.renewed is an event, not a status. A failed renewal moves a subscription to past_due (only if you configured a grace period; access is kept) or on_hold (access revoked); both are recoverable. paused is a deliberate freeze by you or the customer. failed is terminal and only happens when initial creation fails. Cancellation sets it to cancelled or schedules it to become expired at period end.

Checkout Sessions: The recommended path for creating subscriptions. A single-use hosted checkout that collects payment and customer data, then creates the subscription server-side.

Proration: When a customer changes plans mid-cycle, Dodo calculates credits or charges based on the time remaining. Proration mode controls whether the customer is billed immediately, credited, or neither.

Mandates: Authorization to charge a customer's payment method repeatedly (for subscriptions) or on-demand (for usage-based billing). Created during Checkout, can be updated if payment fails.

Creating a Subscription

Via Checkout Session (Recommended)

import DodoPayments from 'dodopayments';

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

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_monthly_plan', quantity: 1 }
  ],
  subscription_data: {
    trial_period_days: 14, // Optional
  },
  customer: {
    email: 'subscriber@example.com',
    name: 'Jane Doe',
  },
  return_url: 'https://yoursite.com/success',
});

// Redirect user to session.checkout_url
console.log('Redirect to:', session.checkout_url);

The customer completes payment on the hosted checkout. On success, Dodo creates the subscription and fires the subscription.active webhook.

With Add-ons

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_pro_monthly',
      quantity: 1,
      addons: [
        { addon_id: 'adn_extra_seats', quantity: 3 }
      ]
    }
  ],
  subscription_data: {
    trial_period_days: 7,
  },
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/success',
});

Subscription Lifecycle & Status

past_due only occurs if you enable a grace period; without one, a failed renewal goes straight to on_hold.

Trial period: If trial_period_days is set, the subscription enters active immediately but charges nothing until the trial ends. The first charge occurs on the trial end date.

Subscription Methods

Retrieve

const subscription = await client.subscriptions.retrieve('sub_xxxxx');
console.log(subscription.status, subscription.next_billing_date);

Pause and Resume

Pause and resume run through status on the update endpoint. Send it on its own: combining paused/active with any other field is rejected with 422.

// Pause: renewals stop, access is revoked, next_billing_date shifts by the pause length
await client.subscriptions.update('sub_xxxxx', { status: 'paused' });

// Resume
await client.subscriptions.update('sub_xxxxx', { status: 'active' });

Pausing emits subscription.paused; resuming emits subscription.unpaused. Customer self-service pause in the portal is opt-in (Settings → Subscriptions → Allow Subscription Pause).

Update Payment Method

When a subscription is on_hold due to failed payment, the customer can update their payment method. This automatically charges any outstanding dues.

await client.subscriptions.updatePaymentMethod('sub_xxxxx', {
  payment_method: {
    type: 'existing',
    payment_method_id: 'pm_new_method',
  },
});

Success emits payment.succeeded followed by subscription.active.

List Usage History (Metered Subscriptions)

const history = await client.subscriptions.retrieveUsageHistory('sub_xxxxx', {
  page_size: 50,
  page_number: 0,
});

Retrieve Credit Usage

const creditUsage = await client.subscriptions.retrieveCreditUsage('sub_xxxxx');
console.log('Subscription:', creditUsage.subscription_id);

for (const item of creditUsage.items) {
  console.log(item.credit_entitlement_name, item.balance); // balance is a string
}

Plan Changes (Upgrades & Downgrades)

Change Plan

await client.subscriptions.changePlan('sub_xxxxx', {
  product_id: 'pdt_higher_tier',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  on_payment_failure: 'prevent_change',
});

Proration modes:

Payment failure handling:

• prevent_change: Keep the old plan if the charge fails.
• apply_change: Apply the new plan even if payment fails (subscription may become on_hold).

Scheduling: effective_at defaults to 'immediately'. Pass effective_at: 'next_billing_date' to schedule the change (typical for downgrades) - nothing is charged now, the customer keeps the current plan until the period ends, and the pending change appears on the subscription as scheduled_change (cancel it with cancelChangePlan).

await client.subscriptions.changePlan('sub_xxxxx', {
  product_id: 'pdt_lower_tier',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  effective_at: 'next_billing_date',
});

Plan changes are rejected while the subscription is past_due. Settle the renewal debt first.

Preview Plan Change

Show the customer a quote before committing:

const preview = await client.subscriptions.previewChangePlan('sub_xxxxx', {
  product_id: 'pdt_new_plan',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
});

console.log('Effective at:', preview.immediate_charge.effective_at);
console.log('Line items:', preview.immediate_charge.line_items);
console.log('Summary:', preview.immediate_charge.summary);
console.log('New plan:', preview.new_plan);

Cancel a Scheduled Plan Change

await client.subscriptions.cancelChangePlan('sub_xxxxx');

Cancellation

Immediate Cancellation

await client.subscriptions.update('sub_xxxxx', {
  status: 'cancelled',
});

Access is revoked immediately.

Cancel at Period End

await client.subscriptions.update('sub_xxxxx', {
  cancel_at_next_billing_date: true,
});

The subscription remains active until the next billing date, then transitions to expired. The subscription.cancelled webhook includes cancel_at_next_billing_date: true and next_billing_date so you know when to revoke access.