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

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

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

curl https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}}/usage_records \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X POST \
  -d quantity=100 \
  -d timestamp=1733946561 \
  -d action=increment

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

• 使用量記録を作成する前に、お客様のビジネスロジックを作成する必要があります。顧客のレコードをデータベースから引き出し、顧客の Stripe サブスクリプションアイテム ID と一日の使用量を抽出します。サブスクリプションアイテム ID を保存していない場合は、サブスクリプションを取得して、subscription items (サブスクリプションアイテム) を確認します。
• 遅延やその他の問題が発生した場合に使用量が複数回報告されないように、冪等キーを使用します。
• timestamp は、現在の請求期間内である必要があります。それ以外の場合は、コールが失敗します。
• action パラメーターのデフォルト値は increment です。この値は、価格が aggregate_usage=sum で設定され、お客様が使用発生時に使用量を書き込み、それを最新の timestamp とともに Stripe に渡すことを前提としています。
• action パラメーターの set 値は、ご自身で使用量を集計し、料金を aggregate_usage=last_during_period または aggregate_usage=last_ever で設定する場合に対応します。
• The usage reporting endpoint is rate-limited, and the Stripe API has a rate limit of 100 calls per second per account. We can increase this to 200 calls per second per account, on request. If you have a service that you expect to exceed this limit, consider “bundling” your product into amounts. For example, if you charge per 1000 requests, consider basing your product on “per 1000 transactions” and send 1 usage record per 1000.

クロックドリフト

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

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

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

現在の使用量を取得する

現行の期間の合計使用量を取得するには、サブスクリプションの次回の請求書を取得します。使用量は、請求書アイテムの quantity として subscription_item に表示されます。処理に若干の遅延が生じることがあるため、使用量の合計値に最新の数量が反映されていない場合があります。

curl -G https://api.stripe.com/v1/invoices/upcoming \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d subscription={{SUBSCRIPTION_ID}}