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

​

前提条件

• 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 Response

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

​

Webhooks

​

Subscription Event Types

1. subscription.active — Subscription が有効化された
2. subscription.updated — Subscription のフィールドが変更された
3. subscription.on_hold — 更新または plan-change の charge に失敗した
4. subscription.failed — Subscription の作成に失敗した（terminal。顧客は再 subscription が必要）
5. subscription.renewed — recurring charge に成功した
6. subscription.past_due — 更新に失敗し、grace period が開始された。顧客は past_due_ends_at まで access を維持する
7. subscription.plan_changed — plan が upgrade、downgrade、または変更された
8. subscription.cancelled — Subscription がキャンセルされた
9. subscription.expired — Subscription が契約期間の終了に達した

​

Payment Scenarios

1. subscription.active: mandate が承認され、subscription が有効化されます。
2. payment.succeeded: 最初の charge を確認します。checkout から 2〜10 分以内 に発生します。

1. Trial 開始時（checkout）: payment method が承認されると subscription.active が発生します。この時点では recurring charge は発生しません。 最初の実際の charge は trial 終了まで延期されます。
2. Trial 終了時: recurring amount が請求され、payment.succeeded と subscription.renewed を同時に受信します。

• subscription.renewed: 各 billing cycle で更新 payment が引き落とされると発生し、常に payment.succeeded とともに送信されます。更新された next_billing_date も含まれます。

1. Subscription Failure

• subscription.failed - mandate の作成に失敗したため、Subscription の作成に失敗しました。
• payment.failed - payment の失敗を示します。

2. Subscription On Hold

• subscription.on_hold - 更新 payment または plan change charge の失敗により、Subscription が on hold になります。ビジネスに grace period がある場合、更新の失敗によって Subscription はまず past_due（subscription.past_due）に移行し、grace period の終了時にのみ on_hold（または grace period の設定に応じて cancelled）へ移行します。Subscription States を参照してください。
• Subscription が on hold になると、payment method が更新されるまで自動的に更新されません。

​

subscription.failed と subscription.on_hold

​

Handling Subscription On Hold

​

Subscription が On Hold になるタイミング

• 更新 payment の失敗: 資金不足、カードの有効期限切れ、または bank decline により自動更新 charge に失敗した
• Plan change charge の失敗: plan の upgrade/downgrade 中に発生した即時 charge に失敗した
• Payment method authorization の失敗: recurring charge に対して payment method を承認できない

​

On Hold の Subscription の再有効化

1. 未払い残額の charge を作成
2. charge の invoice を生成
3. 新しい payment method で payment を処理
4. payment 成功時に subscription を active state へ再有効化

// 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 の例

​

Subscription Plan の変更

​

Proration Options

​

1. prorated_immediately

• 現在の billing cycle の未使用部分を、残り時間に応じて prorate して credit します。credit の対象は base plan、quantity、add-on です
• その後、新しい plan、quantity、add-on で full cycle を charge します。charge 自体は proration されません
• 即時 charge の純額 =（新しい cycle 全額）-（残りの割合 × 古い cycle 全額）。credit の方が大きい場合、差額は subscription-scoped credit として将来の更新に保持されます
• trial period 中は、ユーザーを直ちに新しい plan に切り替え、顧客にすぐ charge します

​

2. full_immediately

• 前の cycle に対する credit なしで、新しい plan の subscription amount 全額を顧客に charge します
• upgrade と downgrade のどちらでも、顧客は新しい plan の価格全額を最初から支払います
• 古い plan の残り時間にかかわらず全額を charge したい場合に便利です

​

3. difference_immediately

• 顧客は古い plan の価格と新しい plan の価格の差額のみを支払います
• 金額は cycle のいつ変更したかに左右されません。同じ upgrade であれば、1 日目でも 29 日目でも費用は同じです
• upgrade の場合、顧客には差額が直ちに charge されます。例: $30/月 → $80/月 = $50 を即時 charge
• downgrade の場合、価格差は subscription-scoped credit として保存され、将来の更新に自動適用されます。例: $50/月 → $20/月 = $30 を credit として保存

​

4. do_not_bill

• plan の変更を直ちに適用しますが、変更時には何も charge しません。新しい plan、quantity、add-on はすぐに使用できます
• 現時点で charge されないため、upgrade では現在の cycle の残り期間、高い plan を無料で利用できます。downgrade は、すでに支払った cycle の未使用部分に対する credit なしで直ちに適用されます
• do_not_bill によって付与された add-on は、請求されていなかったため、後の plan change で credit されません。その後の変更では、新しい add-on quantity の全額が請求されます
• 更新された plan（および quantity/add-on）は次回の予定された更新で請求され、元の billing date は維持されます

​

Behavior

• この API を呼び出すと、Dodo Payments は選択した proration option に基づいて直ちに charge を開始します
• prorated_immediately では、upgrade と downgrade のどちらでも、変更のたびに現在の cycle の未使用部分に対する credit が計算されます。その credit が新しい cycle の charge を上回る場合、残額は subscription の credit balance に追加されます。この credit はその subscription 専用であり、同じ subscription の将来の recurring payment を相殺するためにのみ使用されます
• difference_immediately では、純額は常に正確な価格差になります。downgrade の場合、超過分は prorated_immediately と同様に subscription-scoped credit として保存されます
• full_immediately option は credit の計算を行わず、新しい plan amount 全額を charge します
• do_not_bill option は変更を直ちに適用しますが、billing を次回の更新日まで延期します。更新日は維持されます

​

Charge Processing

• plan change 時に開始された即時 charge は、通常 2 分未満で処理を完了します
• この即時 charge が何らかの理由で失敗すると、問題が解決するまで Subscription は自動的に on hold になります

​

On-Demand Subscriptions

​

Subscription Billing で知っておくべき重要事項

​

関連 API Reference