# 請求する使用量を記録する

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

> 従量課金の仕組みを更新しました。更新前のドキュメントをお探しの場合は、[レガシーの従量課金について](https://docs.stripe.com/docs/billing/subscriptions/usage-based-legacy.md)をご覧ください。
> 
> [移行](https://docs.stripe.com/billing/subscriptions/usage-based-legacy/migration-guide.md)の方法をご確認ください。

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

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

#### curl

```bash
curl https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}}/usage_records \
  -u <<YOUR_SECRET_KEY>>: \
  -X POST \
  -d quantity=100 \
  -d timestamp=1776224085 \
  -d action=increment
```

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

- 使用量記録を作成する前に、お客様のビジネスロジックを作成する必要があります。顧客のレコードをデータベースから引き出し、顧客の Stripe サブスクリプションアイテム ID と一日の使用量を抽出します。サブスクリプションアイテム ID を保存していない場合は、サブスクリプションを取得して、[subscription items (サブスクリプションアイテム)](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-items) を確認します。
- 遅延やその他の問題が発生した場合に使用量が複数回報告されないように、[冪等キー](https://docs.stripe.com/api/idempotent_requests.md)を使用します。
- `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 は保証していません。

## 現在の使用量を取得する

現行の期間の合計使用量を取得するには、サブスクリプションの[プレビュー請求書を作成](https://docs.stripe.com/api/invoices/create_preview.md)します。使用状況は、`サブスクリプション項目`の[subscription_item](https://docs.stripe.com/api.md#invoiceitems)の`数量`として反映されます。処理に若干の遅延が生じることがあるため、使用量の合計値に最新の数量が反映されていない場合があります。

```curl
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d subscription={{SUBSCRIPTION_ID}}
```