メインコンテンツへスキップ
バージョン: 最新版

スケジュールAPI

スケジュールAPIを使用すると、定期支払いと自動送金をスケジュールで作成・管理できます。

利用可能なエンドポイント​

関連エンドポイント​

概要​

スケジュールは自動化された繰り返し操作を可能にします：

  • 繰り返し課金 - スケジュールに従って顧客に自動課金
  • 繰り返し送金 - 受取人への自動送金
  • 柔軟な頻度 - 日次、週次、月次のスケジュール
  • 実行追跡 - スケジュールの各実行を追跡

一般的なユースケース​

  • サブスクリプション課金（月額/年額課金）
  • マーケットプレイスベンダーへのスケジュール支払い
  • 定期寄付
  • 会員費
  • 自動コミッション支払い

スケジュールの仕組み​

  1. 頻度（日次、週次、月次）を指定してスケジュールを作成
  2. スケジュールは指定された間隔で自動実行
  3. 各実行は「occurrence」（実行）を作成
  4. occurrenceは作成された実際の課金または送金にリンク
  5. スケジュールのステータスと実行結果を監視

認証​

すべてのスケジュールAPIエンドポイントはシークレットキーによる認証が必要です。

スケジュール頻度​

スケジュールは以下の頻度をサポートしています：

頻度説明ユースケース例
daily指定時刻に毎日実行日次支払い
weekly指定曜日に週1回実行週次サブスクリプション
monthly指定日に月1回実行月次課金

スケジュールステータスのライフサイクル​

スケジュールは以下のステータスを経由します：

  1. active - スケジュールは実行中で、スケジュール通りに実行されます
  2. suspended - スケジュールは一時停止中（再開可能）
  3. deleted - スケジュールは永久に無効化
  4. completed - スケジュールは終了日に達しました

実行（Occurrences）​

スケジュールが実行されるたびに、occurrence（実行）が作成されます。実行には独自のステータスがあります：

  • scheduled - 実行は実行待ちキューに入っています
  • running - 実行は現在処理中
  • successful - 実行は正常に完了
  • failed - 実行は失敗（決済拒否、残高不足など）
  • skipped - 実行はスキップされました（例：スケジュールが一時停止中）

ベストプラクティス​

1. 失敗した実行の処理​

すべてのスケジュールされた操作が成功するわけではありません。以下のWebhookハンドラーを実装してください：

  • schedule.occurrence.failed - 失敗した支払い/送金の処理
  • schedule.occurrence.successful - 成功した操作の追跡

2. スケジュールの健全性監視​

スケジュールのステータスと最近の実行を定期的に確認してください：

  • 高い失敗率は顧客の支払い問題を示している可能性があります
  • 一時停止されたスケジュールは再アクティブ化されるまで実行されません

3. 終了日の設定​

固定期間のサブスクリプションにはend_dateを設定してください：

{
  "period": "month",
  "end_date": "2027-12-31"
}

4. メタデータの使用​

サブスクリプションの詳細をメタデータに保存して、簡単に検索できるようにしてください：

{
  "metadata": {
    "plan": "premium",
    "customer_id": "cust_123",
    "subscription_id": "sub_456"
  }
}

制限事項​

  • 最小スケジュール間隔：1日
  • アカウントあたりの最大アクティブスケジュール数：制限についてはサポートにお問い合わせください
  • 作成後のスケジュールは編集できません（削除して再作成が必要）
  • 失敗した実行は自動的に再試行されません

エラー処理​

スケジュールを使用する際の一般的なエラー：

エラーコード説明解決策
invalid_frequency無効なperiod値daily、weekly、monthlyを使用
invalid_start_date開始日が過去将来の日付を使用
insufficient_balance送金のための残高不足スケジュール実行前に資金を追加
invalid_recipient受取人が見つからないか非アクティブ受取人が存在することを確認

関連リソース​