請求する使用量を記録する
注
従量課金プロセスを更新しました。以前のガイダンスの情報については、Stripe のレガシーの従量課金のドキュメントをご覧ください。
メーターを設定する
使用量を記録する前に、Meter (メーター) が正しく設定されていることを確認してください。表示名を除き、メーターを変更することはできません。
イベント名
これは、使用量の記録にこのメーターの使用を予定している Meter イベントの名前です。使用量を Stripe に送信する際に、Meter Events (メーターイベント) の event_name
フィールドでこの名前が使用されます。これにより、使用量を適正なメーターで取り込み、集計することができます。イベント名には特定の 1 つのメーターのみを使用できます。
イベントの取り込み
イベントを Stripe に送信する方法を指定します。2 つのオプションがあります。
- 未加工: すべてのメーターイベントをスタンドアロンのイベントとして扱います。同じタイムスタンプで送信される複数のイベントは上書きされず、集計に含められます。何も指定しなかった場合は、これがデフォルトのオプションになります。
- 事前集計 (毎時または毎日): 毎時または毎日のいずれかで、特定の時間間隔で事前集計されたイベントを送信している場合、Stripe は集計対象の毎時または毎日の時間枠内で最新のメーターイベントのみを使用します。同じ毎時または毎日の時間枠内で送信される、新しいイベントで以前のイベントが上書きされます。
集計式
請求期間中の使用量の集計方法を指定します。このパラメーターには以下のオプションが含まれます。
- 合計: 請求期間中のすべての使用量の合計値に基づいて請求します。
- 件数: 請求期間中のすべての使用量の件数に基づいて請求します。
- 最後 (近日対応予定): 請求期間中の最新の使用量記録に基づいて請求します。使用量が報告されなかった場合は、使用量 0 に従って請求します。
- 最大 (近日対応予定): 請求期間内の指定した時間枠 (秒、時、日) の最大値に基づいて請求します。たとえば、請求期間の任意の日にログインしたユーザーの最大数が使用され、「ハイウォーターマーク方式の請求」とも呼ばれます。
ペイロードキーの上書き
イベントペイロードのどのキーが顧客と使用量の数値を表すかを指定します。
- value_settings: このパラメーターを使用して、メーターイベントのペイロードで使用量の数値を参照するキーを定義します。デフォルトのキーは
value
ですが、トークンなど別のキーも指定できます。 - customer_mapping: このパラメーターを使用して、Stripe Customer ID (Stripe 顧客 ID) を参照するイベントペイロード内のキーを定義します。デフォルトのキーは
stripe_customer_id
ですが、customer_id
など別のキーも指定できます。
使用量記録
customer_id
、数値、タイムスタンプ (任意) とともにメーターイベントを作成して、Stripe と使用量情報を共有できます。使用量を報告する頻度は自分で決められます。たとえば、使用量は、発生時に送信することも、バッチ (例: 毎日) で送信することもできます。請求期間の終了時に、Stripe は合計料金を自動的に計算し、その期間内のすべての使用量に対するインボイスを発行します。
Meter Events (メーターイベント)を作成するには、次の手順を使用します。
べき等
べき等キーを使用して、遅延やその他の問題によって使用量の報告が複数回行われるのを防ぎます。それぞれのメーターイベントは identifier (ID) に対応して、リクエストではこれを指定できます (指定しなかった場合、ID は自動生成されます)。
イベントのタイムスタンプ
タイムスタンプは、必ず過去 35 日以内、5 分後以内で指定してください (5 分間の猶予は、サーバーと Stripe のシステム間のクロックドリフトを考慮しています)。
使用量の値
ペイロードの使用量の数値は、正の整数値のみを受け付けます。
小数または負の値の使用をご希望の場合
usage-based-billing@stripe.com にお問い合わせいただくと、実際のユースケースへの理解を深めることができます。
レート制限
レート制限にはご注意ください。Meter Events エンドポイントは、Stripe アカウント 1 件あたり 1 秒間で最大 1,000 回までと、メーターごとに顧客あたり並列で 1 回まで呼び出すことができます。サービスがこの制限を超える可能性がある場合は、商品の量を「バンドルする」ことができます。たとえば、1,000 件のリクエスト単位で請求している場合は、「1,000 回のリクエスト」を商品の基準単位にして、使用量の記録を 1,000 回ごとに 1 回の送信にするようにできます。
429
ステータスコードを監視し、指数バックオフスケジュールを使用した再試行メカニズムを実装して、リクエスト量を管理します。
また、Thundering Herd の影響を回避するために、バックオフスケジュールにランダム性を組み込むことも検討します。
レート制限の拡張をご希望の場合
You can report usage either by dropping it into an S3 bucket or through a bulk endpoint. Learn about recording usage for billing with the S3 connector. For a better understanding of your specific needs and to get early access, reach out to us at usage-based-billing@stripe.com.
ベストプラクティス
ユーザーへの正確な請求には使用量データが不可欠です。システムにはネットワーク障害からの回復能力を確保してください。たとえば、Amazon SQS のような信頼できるキューを使用して Stripe にデータを追加し、必要に応じて再試行できるようにします。
使用量の誤りを修正する
Meter Event Adjustments (メーターイベントのイベントの調整) を使用して、誤って報告されたイベントをキャンセルできます。メーターイベントをキャンセルするには、そのイベントの ID が必要です。
メーターイベントのキャンセルには以下の制限事項があります。
- 過去 24 時間以内に Stripe に送信されたイベントのみをキャンセルできます。
- Stripe がすでに顧客に請求している場合、キャンセルされた使用量の請求調整はサポートされません。
- 確定済みのインボイスにすでに含まれている使用量をキャンセルしても、Stripe はそのインボイスを更新しません。また、キャンセルされた使用量を対象とする新たな修正インボイスも発行しません。