サブスクリプション統合ガイド

​

前提条件

• Dodo Paymentsのマーチャントアカウント
• ダッシュボードの Developer → API Keys にあるAPI key。DODO_PAYMENTS_API_KEY に保存します
• Developer → Webhooks にあるwebhook secret。DODO_PAYMENTS_WEBHOOK_KEY に保存します
• Products で作成したサブスクリプションプロダクトが少なくとも1つ

​

API連携

​

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レスポンス

{
  "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 — 定期請求に成功した
6. subscription.past_due — 更新に失敗し、猶予期間が開始された。顧客はpast_due_ends_atまでアクセスを維持する
7. subscription.plan_changed — プランがアップグレード、ダウングレード、または変更された
8. subscription.cancelled — サブスクリプションがキャンセルされた
9. subscription.expired — サブスクリプションが契約期間の終了に達した

​

支払いシナリオ

1. subscription.active：mandateが承認され、サブスクリプションが有効になります。
2. payment.succeeded：初回請求を確認します。チェックアウトから 2～10分以内 に発生します。

1. trial開始時（チェックアウト時）： 支払い方法が承認されるとsubscription.activeが発生します。この時点では定期請求は行われません。 最初の実際の請求はtrial終了まで延期されます。
2. trial終了時： 定期料金が請求され、payment.succeededをsubscription.renewed と同時に受信します。

• subscription.renewed：各請求サイクルで更新料金が引き落とされると発生し、常に payment.succeededと同時に送信されます。更新されたnext_billing_dateも含まれます。

1. サブスクリプションの失敗

• subscription.failed - mandateの作成に失敗したため、サブスクリプションの作成に失敗しました。
• payment.failed - 支払いの失敗を示します。

2. サブスクリプションの保留

• subscription.on_hold - 更新支払いまたはプラン変更の請求に失敗したため、サブスクリプションが保留になります。ビジネスに猶予期間がある場合、更新の失敗によってサブスクリプションはまずpast_due（subscription.past_due）に移行し、猶予期間が終了した場合のみon_hold（または猶予期間の設定に応じてcancelled）に移行します。Subscription Statesを参照してください。
• サブスクリプションが保留になると、支払い方法が更新されるまで自動更新されません。

​

subscription.failedとsubscription.on_holdの違い

​

保留中のサブスクリプションの処理

​

サブスクリプションが保留になるタイミング

• 更新支払いの失敗：残高不足、カードの有効期限切れ、銀行による拒否などにより、自動更新の請求に失敗した
• プラン変更の請求の失敗：プランのアップグレードまたはダウングレード時の即時請求に失敗した
• 支払い方法の承認の失敗：定期請求の支払い方法を承認できない

​

保留中のサブスクリプションの再有効化

1. 未払い残額の請求を作成
2. 請求に対するinvoiceを生成
3. 新しい支払い方法で支払いを処理
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.'
  });
}

​

サブスクリプションイベントペイロードの例

​

サブスクリプションプランの変更

​

日割り計算オプション

​

1. prorated_immediately

• 残り時間に応じて現在の請求サイクルの未使用分を日割り計算し、クレジットします。クレジットは基本プラン、数量、アドオンを対象とします
• その後、新しいプラン、数量、アドオンで1サイクル分全額を請求します。請求自体は日割り計算されません
• 即時請求の正味額 = （新しいサイクルの全額）－（残りの割合 × 古いサイクルの全額）。クレジットの方が大きい場合、差額はサブスクリプションに紐付くクレジットとして将来の更新に使用されます
• trial期間中はユーザーが直ちに新しいプランへ切り替わり、顧客に即時請求されます

​

2. full_immediately

• 前のサイクルに対するクレジットなしで、新しいプランのサブスクリプション料金全額を請求します
• アップグレードでもダウングレードでも、顧客は新しいプラン料金全額を最初から支払います
• 古いプランの残り時間に関係なく全額を請求したい場合に便利です

​

3. difference_immediately

• 顧客は古いプラン料金と新しいプラン料金の差額のみを支払います
• 金額はサイクル内の変更時期に左右されません。同じアップグレードなら1日目でも29日目でも費用は同じです
• アップグレード時は差額が直ちに請求されます。例：$30/月 → $80/月 = $50を即時請求
• ダウングレード時は料金差額がサブスクリプションに紐付くクレジットとして保存され、将来の更新に自動適用されます。例：$50/月 → $20/月 = $30をクレジットとして保存

​

4. do_not_bill

• プラン変更を直ちに適用しますが、変更時には何も請求しません。新しいプラン、数量、アドオンはすぐに利用できます
• 今は請求されないため、アップグレードでは現在のサイクルの残り期間、高いプランを無料で利用できます。ダウングレードは、すでに支払ったサイクルの未使用分をクレジットせず、直ちに適用されます
• do_not_billで付与されたアドオンは請求されていないため、後のプラン変更時にクレジットされません。その後の変更では新しいアドオン数量が全額請求されます
• 更新されたプラン（および数量/アドオン）は次回予定の更新時に請求され、元の請求日は維持されます

​

動作

• このAPIを呼び出すと、選択した日割り計算オプションに基づいて、Dodo Paymentsが直ちに請求を開始します
• prorated_immediatelyでは、アップグレードとダウングレードのどちらでも、変更のたびに現在のサイクルの未使用分に対するクレジットが計算されます。クレジットが新しいサイクルの請求額を超える場合、残額はサブスクリプションのクレジット残高に追加されます。このクレジットはそのサブスクリプション専用で、同じサブスクリプションの将来の定期支払いとの相殺にのみ使用されます
• difference_immediatelyでは、正味額は常に正確な料金差額になります。ダウングレードでは、余剰分がprorated_immediatelyと同様にサブスクリプション専用クレジットとして保存されます
• full_immediatelyオプションではクレジット計算を行わず、新しいプランの全額を請求します
• do_not_billオプションでは変更を直ちに適用しますが、請求は維持された次回更新日まで延期されます

​

請求処理

• プラン変更時に開始された即時請求は、通常2分未満で処理が完了します
• この即時請求が何らかの理由で失敗すると、問題が解決するまでサブスクリプションは自動的に保留になります

​

オンデマンドサブスクリプション

​

サブスクリプション請求について知っておくべき主なこと

​

関連APIリファレンス