Schedules API
Schedules APIを使用すると、スケジュールに基づく定期決済と自動送金を作成および管理できます。
利用可能なエンドポイント
- Schedulesの一覧表示 - GET /schedules
- Scheduleの取得 - GET /schedules/:id
概要
Schedulesは自動化された定期的な操作を可能にします:
- 定期的なチャージ - スケジュールに従って顧客に自動的に請求
- 定期的な送金 - 受取人に自動的に資金を送金
- 柔軟な頻度 - 日次、週次、月次のスケジュール
- 実行追跡 - スケジュールの各実行を追跡
一般的なユースケース
- サブスクリプション請求(月次/年次チャージ)
- マーケットプレイスベンダーへのスケジュール済み支払い
- 定期的な寄付
- 会員費
- 自動手数料支払い
Schedulesの仕組み
- 頻度(日次、週次、月次)を指定してスケジュールを作成
- スケジュールは指定された間隔で自動的に実行されます
- 各実行は「occurrence」を作成します
- Occurrencesは作成された実際のチャージまたは送金にリンクされます
- スケジュールステータスとoccurrence結果を監視します
認証
すべてのSchedule APIエンドポイントは、シークレットキーを使用した認証が必要です。
スケジュール頻度
Schedulesは以下の頻度をサポートします:
| Frequency | Description | ユースケース例 |
|---|---|---|
daily | 指定時刻に毎日実行 | 日次支払い |
weekly | 指定曜日に週1回実行 | 週次サブスクリプション |
monthly | 指定日に月1回実行 | 月次請求 |
スケジュールステータスのライフサイクル
スケジュールは以下のステータスを経て進行します:
active- スケジュールは実行中で、予定通りに実行されますsuspended- スケジュールは一時停止中(再開可能)deleted- スケジュールは永続的に無効化されましたcompleted- スケジュールは終了日に達しました
Occurrences
スケジュールが実行されるたびに、occurrenceが作成されます。Occurrencesには独自のステータスがあります:
scheduled- occurrenceは実行待ちキューに入っていますrunning- occurrenceは現在実行中ですsuccessful- occurrenceは正常に完了しましたfailed- occurrenceは失敗しました(決済拒否、残高不足など)skipped- occurrenceはスキップされました(例: スケジュールが一時停止された)
ベストプラクティス
1. 失敗したOccurrencesを処理する
すべてのスケジュール操作が成功するわけではありません。以下のWebhookハンドラーを実装します:
schedule.occurrence.failed- 失敗した決済/送金を処理schedule.occurrence.successful- 成功した操作を追跡
2. スケジュールの健全性を監視する
スケジュールステータスと最近のoccurrencesを定期的に確認します:
- 高い失敗率は顧客の決済問題を示している可能性があります
- 一時停止されたスケジュールは再開されるまで実行されません
3. 終了日を設定する
期間限定のサブスクリプションの場合、end_dateを設定します:
{
"period": "month",
"end_date": "2027-12-31"
}
4. メタデータを使用する
簡単な検索のためにサブスクリプション詳細をメタデータに保存します:
{
"metadata": {
"plan": "premium",
"customer_id": "cust_123",
"subscription_id": "sub_456"
}
}
制限事項
- 最小スケジュール間隔: 1日
- アカウントあたりの最大アクティブスケジュール数: 制限についてはサポートにお問い合わせください
- スケジュールは作成後に編集できません(削除して再作成する必要があります)
- 失敗したoccurrencesは自動的に再試行されません
エラー処理
スケジュールを使用する際の一般的なエラー:
| Error Code | Description | Solution |
|---|---|---|
invalid_frequency | 無効な期間値 | daily、weekly、またはmonthlyを使用してください |
invalid_start_date | 開始日が過去です | 未来の日付を使用してください |
insufficient_balance | 送金に十分な残高がありません | スケジュール実行前に資金を追加してください |
invalid_recipient | 受取人が見つからないか非アクティブです | 受取人が存在することを確認してください |