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

課金スケジュール API

課金スケジュール APIを使用すると、定期課金スケジュールを一括で作成・管理できます。このAPIは大量操作向けに設計されており、CSVファイルをアップロードして複数のスケジュールを一度に作成し、既存のスケジュールを一括で一時停止、再開、削除できます。

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

関連エンドポイント​

概要​

課金スケジュール APIは、定期課金を管理するための一括操作を提供します：

  • CSV アップロード - 単一のCSVファイルから数百から数千の課金スケジュールを作成
  • 進捗監視 - 一括作成ジョブのステータスをリアルタイムで追跡
  • ステータスレポート - 各スケジュールの成功/失敗ステータスを含む詳細レポートをダウンロード
  • 一括一時停止 - 複数のアクティブなスケジュールを同時に一時停止
  • 一括再開 - 複数の一時停止中のスケジュールを一度に再開
  • 一括削除 - 複数のスケジュールを単一の操作で完全に削除

一般的なユースケース​

  • 別のプラットフォームからのサブスクリプション顧客の移行
  • 大規模な顧客ベースに対する定期支払いの設定
  • 季節的なスケジュール管理（休日のための一時停止/再開）
  • 解約した顧客のスケジュールの一括キャンセル
  • 企業顧客向けの定期課金の初期設定

一括作成の仕組み​

  1. 顧客とスケジュールの詳細を含むCSVファイルを準備
  2. CSVファイルをアップロードして一括作成ジョブを作成
  3. recurring_idを使用してジョブの進捗を監視
  4. ステータスレポートをダウンロードして結果を確認し、エラーを処理
  5. 成功したスケジュールは自動的に実行を開始

CSVファイル形式​

スケジュールを一括作成する際、CSVファイルには以下のカラムを含める必要があります：

カラム必須説明
customer_keyはい顧客行の一意の識別子（追跡用）
customerはいカードが紐付けられた顧客ID (cust_*)
cardいいえ課金する特定のカードID（指定しない場合はデフォルトを使用）
amountはい最小通貨単位での課金額
descriptionいいえ各課金の説明
everyはい頻度の乗数（例：毎月の場合は1）
periodはい時間単位：day、week、またはmonth
days_of_month条件付き課金日（monthの期間で必須）
start_dateいいえスケジュール開始日 (YYYY-MM-DD)
end_dateいいえスケジュール終了日 (YYYY-MM-DD)

CSVの例​

customer_key,customer,card,amount,description,every,period,days_of_month,start_date,end_date
sub_001,cust_test_abc123,,100000,Monthly premium plan,1,month,1,2025-02-01,2026-01-31
sub_002,cust_test_def456,card_test_xyz789,50000,Basic subscription,1,month,15,2025-02-01,
sub_003,cust_test_ghi012,,200000,Enterprise plan,1,month,1;15,2025-02-01,2025-12-31

認証​

すべての課金スケジュール APIエンドポイントは、シークレットキーを使用した認証が必要です。

一括操作の制限​

操作制限
CSVファイルサイズ最大10MB
CSV当たりのスケジュール数最大10,000行
一括一時停止/再開/削除当たりのスケジュールID数最大100 ID
同時一括作成ジョブ数アカウント当たり5件

ジョブステータスのライフサイクル​

一括作成ジョブは以下のステータスを経て進行します：

  1. pending - ジョブはキューに入り、開始を待っています
  2. processing - ジョブはアクティブにスケジュールを作成中
  3. completed - ジョブ完了（個別の結果についてはレポートを確認）
  4. failed - ジョブで致命的なエラーが発生

エラー処理​

一括作成エラー​

一括作成ジョブは回復力を持つよう設計されています。個別の行が失敗した場合：

  • ジョブは残りの行の処理を続行
  • 失敗した行はステータスレポートに記録
  • レポートをダウンロードして行ごとの具体的なエラーメッセージを確認

一般的なCSVエラー​

エラー説明解決方法
invalid_customer顧客IDが見つかりません顧客が存在し、カードが紐付けられていることを確認
invalid_cardカードが見つからないか期限切れ有効なカードIDを使用するか、削除してデフォルトを使用
invalid_amount金額がゼロまたは負の値正の整数の金額を指定
invalid_period無効な期間の値day、week、またはmonthを使用
missing_days_of_month月次期間に必須日を指定（例：1または1;15）

一括一時停止/再開/削除エラー​

エラー説明解決方法
schedule_not_found1つ以上のスケジュールIDが無効すべてのスケジュールIDが存在することを確認
invalid_statusスケジュールが操作に不適切な状態現在のスケジュールステータスを確認
too_many_idsリクエスト当たりの最大ID数を超過複数のリクエストに分割（最大100）

ベストプラクティス​

1. アップロード前にCSVを検証​

CSVファイルで以下を確認：

  • 正しいカラムヘッダー
  • 有効な顧客ID
  • 適切な日付形式（YYYY-MM-DD）
  • 整数としての金額値（小数ではなく）

2. ジョブの進捗を監視​

監視エンドポイントを定期的にポーリング：

// 完了まで5秒ごとに確認
const checkStatus = async (recurringId) => {
  const status = await getJobStatus(recurringId);
  if (status.state === 'completed') {
    return await downloadReport(recurringId);
  }
  setTimeout(() => checkStatus(recurringId), 5000);
};

3. 部分的な失敗を処理​

常にステータスレポートをダウンロードして確認：

  • 失敗した行を個別に、または新しいCSVでリトライ
  • 調査のためにエラーをログに記録
  • 必要に応じて影響を受けた顧客に通知

4. 一意の顧客キーを使用​

ステータスレポートで行を簡単に識別し、結果をシステムに照合できるように、意味のあるcustomer_key値を含めます。

関連リソース​