Subscription Integration Guide

​

Prerequisites

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

​

API Integration

​

Checkout Sessions

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

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

​

Webhooks

​

订阅事件类型

1. subscription.active - 订阅成功激活。
2. subscription.updated - 订阅对象已更新（任何字段更改时触发）。
3. subscription.on_hold - 由于续订失败导致订阅被暂停。
4. subscription.failed - 创建授权失败时订阅创建失败。
5. subscription.renewed - 订阅已为下一个计费周期续订。

​

支付场景

1. subscription.active：mandate 已获授权，订阅已激活。
2. payment.succeeded：确认首次扣款。预计在结账后的 2–10 分钟内收到。

1. 试用期开始时（结账）： payment method 获得授权后，subscription.active 触发。此时不会收取 recurring charge。 首次实际扣款会推迟到试用期结束。
2. 试用期结束时： 系统会收取 recurring amount，您会同时收到 payment.succeeded 和 subscription.renewed。

• subscription.renewed：每个 billing cycle 在扣除续订款项时触发，始终与 payment.succeeded 同时触发。它还会携带更新后的 next_billing_date。

1. 订阅失败

• subscription.failed - 由于创建 mandate 失败，订阅创建失败。
• payment.failed - 表示付款失败。

2. 订阅暂停

• subscription.on_hold - 由于续订付款失败或计划变更扣款失败，订阅被暂停。
• 订阅暂停后，在 payment method 更新之前不会自动续订。

​

subscription.failed 与 subscription.on_hold

​

处理暂停的订阅

​

订阅暂停的情况

• 续订付款失败：由于余额不足、卡片过期或银行拒绝，自动续订扣款失败
• 计划变更扣款失败：升级或降级计划期间的即时扣款失败
• payment method 授权失败：payment method 无法获得 recurring charges 的授权

​

从暂停状态重新激活订阅

1. 为剩余应付款创建扣款
2. 为该扣款生成 invoice
3. 使用新的 payment method 处理付款
4. 付款成功后，将订阅重新激活为 active 状态

// 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 with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { 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,
    payment_method={"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

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

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.'
  });
}

​

Subscription event payload 示例

​

更改订阅计划

​

Proration 选项

​

1. prorated_immediately

• 根据当前 billing cycle 的剩余时间计算按比例分摊的金额
• 仅向客户收取新旧计划之间的差额
• 在试用期内，这会立即将用户切换到新计划，并立即向客户收费

​

2. full_immediately

• 向客户收取新计划的完整 subscription amount
• 忽略之前计划的剩余时间或 credits
• 适用于您希望重置 billing cycle，或无论 proration 如何都收取完整金额的情况

​

3. difference_immediately

• 升级时，立即向客户收取两个计划金额之间的差额。
• 例如，如果当前计划为 30 Dollars，客户升级到 80 Dollars，则会立即收取 $50。
• 降级时，当前计划的未使用金额会添加为 internal credit，并自动用于抵扣未来的订阅续订费用。
• 例如，如果当前计划为 50 Dollars，客户切换到 20 Dollars 的计划，则剩余的 $30 会记为 credit，并用于下一个 billing cycle。

​

4. do_not_bill

• 立即应用计划变更，但在变更时不会收取任何费用。
• 更新后的计划（以及 quantity/add-ons）会在下一次计划续订时计费，并且会保留原 billing date。

​

行为

• 调用此 API 时，Dodo Payments 会根据您选择的 proration 选项立即发起扣款
• 如果计划变更为降级，并且您使用 prorated_immediately，系统会自动计算 credits 并将其添加到订阅的 credit balance 中。这些 credits 专属于该订阅，只会用于抵扣同一订阅未来的 recurring payments
• full_immediately 选项会跳过 credit calculations，并收取新计划的完整金额

​

扣款处理

• 计划变更时发起的即时扣款通常会在 2 分钟内完成处理
• 如果即时扣款因任何原因失败，订阅会自动进入暂停状态，直到问题得到解决

​

按需订阅

​

关于订阅计费的关键事项

​

相关 API 参考