請求する使用量を記録するレガシー

顧客の使用量を記録し、報告する方法をご紹介します。

注

従量課金の仕組みを更新しました。更新前のドキュメントをお探しの場合は、レガシーの従量課金についてをご覧ください。

移行の方法をご確認ください。

各請求期間では、期間全体にわたり使用量を Stripe に報告して、正しい金額が顧客に請求されるようにします。顧客の使用量の記録に自社のシステムを使用して、サブスクリプションの使用量情報を Stripe に提供することができます。

サブスクリプションアイテム、使用数量、タイムスタンプとともに使用量記録を作成して、Stripe と使用量情報を共有します。使用状況の報告頻度はお客様が決定できます。たとえば、有効な従量課金サブスクリプションに対して、それぞれ特定の間隔 (例: 24 時間ごと) でコードを実行できます。請求期間の終了時に、Stripe は合計料金を自動的に計算し、その期間内のすべての使用量に対する請求書を発行します。

使用量記録のベストプラクティス

使用量記録を作成する前に、お客様のビジネスロジックを作成する必要があります。顧客のレコードをデータベースから引き出し、顧客の Stripe サブスクリプションアイテム ID と一日の使用量を抽出します。サブスクリプションアイテム ID を保存していない場合は、サブスクリプションを取得して、subscription items (サブスクリプションアイテム) を確認します。
遅延やその他の問題が発生した場合に使用量が複数回報告されないように、冪等キーを使用します。
timestamp は、現在の請求期間内である必要があります。それ以外の場合は、コールが失敗します。
action パラメーターのデフォルト値は increment です。この値は、価格が aggregate_usage=sum で設定され、お客様が使用発生時に使用量を書き込み、それを最新の timestamp とともに Stripe に渡すことを前提としています。
action パラメーターの set 値は、ご自身で使用量を集計し、料金を aggregate_usage=last_during_period または aggregate_usage=last_ever で設定する場合に対応します。
使用量報告エンドポイントにはレート制限があり、Stripe API のレート制限はアカウントごとに 1 秒あたり 100 コールです。リクエストに応じて、これをアカウントごとに 1 秒あたり 200 コールに増やすことが可能です。この制限を超えると予想されるサービスがある場合は、商品を一定量に「まとめる」ことをご検討ください。たとえば、1,000 件のリクエスト単位で請求している場合は、商品の基準を「1,000 件の取引単位」にして、使用量記録が 1,000 件に 1 回だけ送信されるようにします。

クロックドリフト

現在の請求期間以外の使用量を報告するとエラーが発生します。ただし、サーバーと Stripe のシステム間のクロックドリフトを考慮して、Stripe はデフォルトの集計モード (aggregate_usage = sum) に短い猶予期間を設けています。ほかの集計モードではすべて、timestamp が現在期間内に存在する必要があります。

各請求期間の最初の数分間に、前の期間の最後の数分間に発生した使用量を報告できます。前の期間の請求書が確定されていない場合、Stripe はその請求書に使用量を追加します。確定後であれば、その使用量は現行期間の請求になります。猶予期間の終了後は、前の請求期間の使用量を報告することはできません。

請求期間外の使用量の報告では猶予期間を使用しないでください。猶予期間は、発生の可能性のあるクロックドリフトの考慮のみを目的とするもので、Stripe は保証していません。

現在の使用量を取得する

現在の期間の合計使用量を取得するには、サブスクリプションの請求書のプレビューを作成できます。使用量は、subscription_item の請求書の項目の quantity として反映されます。処理には若干の遅延が生じることがあるため、使用量の合計値に最新の数量が反映されていない場合があります。