請求する使用量を API で記録する

Stripe で使用量を記録して、各請求期間の正しい金額を顧客に請求します。使用量を記録するには、まずメーターを設定してから、メーターイベント (メーターに設定されているイベント名、顧客 ID、数値、タイムスタンプ (オプション)) を送信します。

Stripe に使用量を記録する頻度を、発生ごと、一括などで決定できます。Stripe は従量イベントを非同期に処理するため、集計された使用量は従量イベントのサマリーに集約され、次回の請求書には、最近受信した従量イベントが即時に反映されない可能性があります。

メーターイベントを作成する

API を使用して Meter Event (メーターイベント) を作成します。

curl https://api.stripe.com/v1/billing/meter_events \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d event_name=alpaca_ai_tokens \
  -d "payload[value]"=25 \
  -d "payload[stripe_customer_id]"={{CUSTOMER_ID}}

べき等

遅延やその他の問題により各イベントが重複して報告されることを防ぐには、Idempotency Key (べき等キー) を使用します。従量イベントはすべて ID に対応しており、リクエストで ID を指定できます。指定しなかった場合、ID は自動生成されます。

イベントのタイムスタンプ

タイムスタンプは、必ず 35 日前から、5 分後までの範囲で指定してください (5 分間の猶予は、サーバーと Stripe のシステム間のクロックドリフトのために設けられています)。

使用量の値

ペイロードの使用量の数値は、整数値のみを受け付けます。サイクル全体の使用量がマイナスの場合、Stripe では請求書のラインアイテムの使用数量を 0 として申告します。

レート制限

Meter Event (メーターイベント) エンドポイントでは、本番環境で 1 秒あたり 1,000 件の呼び出しが許可され、メーターごとに 1 顧客あたり 1 件の同時呼び出しが許可されます。サービスがこの制限を超える可能性がある場合は、商品を一定の量に「まとめる」ことができます。たとえば、1,000 件のリクエストごとに請求する場合、商品を「1,000 回の取引単位」にまとめて、1,000 回ごとに 1 つの使用記録を送信できます。

サンドボックス環境で行われる meter event および meter event stream エンドポイントの呼び出しは、基本制限にカウントされます。

429 ステータスコードを監視し、指数バックオフスケジュールを使用した再試行メカニズムを実装して、リクエスト量を管理できます。

レート制限の引き上げによる高速処理の取り込み API v2

API v2 では、メーターイベントストリームを使用して、毎秒最大 10,000 件のイベントを Stripe に送信できます。これは本番環境でのみ機能します。

このエンドポイントは、ステートレス認証セッションを使用します。まず、メーターイベントセッションを作成して認証トークンを受け取ります。認証トークンは 15 分間のみ有効であるため、トークンの有効期限が切れたら、新しいメーターイベントセッションを作成する必要があります。

次に、返された認証トークンを使用して、メーターイベントストリームを指定して高スループットのメーターイベントを作成します。

429 ステータスコードを監視し、指数バックオフスケジュールを使用した再試行メカニズムを実装して、リクエスト量を管理できます。

require 'stripe'
require 'date'

class MeterEventManager
  attr_accessor :api_key
  attr_accessor :meter_event_session

  def initialize(api_key)
    @api_key = api_key
    @meter_event_session = nil

メーターイベントエラーを処理する

Stripe は、メーターイベントを非同期的に処理します。エラーが見つかった場合は、次のいずれかの Event (イベント) を作成します。

サンプルのペイロード

{
  "id": "evt_test_65R2GpwDsnmpzihMjdT16R2GDhI4SQdXJGRbvn7JA8mPEm",
  "object": "v2.core.event",
  "created": "2024-08-28T20:54:12.051Z",
  "data": {
    "developer_message_summary": "There is 1 invalid event",
    "reason": {
      "error_count": 1,
      "error_types": [
        {

エラーコード

reason.error_types.code はエラーを引き起こしたエラーカテゴリーを示します。発生する可能性のあるエラーコードは次のとおりです。

• meter_event_customer_not_found
• meter_event_no_customer_defined
• meter_event_dimension_count_too_high
• archived_meter
• timestamp_too_far_in_past
• timestamp_in_future
• meter_event_value_not_found
• meter_event_invalid_value
• no_meter (v1.billing.meter.no_meter_found イベントタイプでのみサポートされています)

イベントのリッスン

Webhook エンドポイントまたは別のタイプのイベント送信先を設定することで、イベントをリッスンできます。

1. Workbench の Webhook タブで新しい送信先の作成をクリックします。または、このテンプレートを使用して、2 つのイベントタイプを事前に選択した状態で Workbench で新しい送信先を設定します。

2. Show Advanced Settings (詳細設定を表示) をクリックして、Thin ペイロードスタイルを選択します。

3. イベントのリストから v1.billing.meter.error_report_triggered と v1.billing.meter.no_meter_found を選択します。

4. イベントを処理するハンドラを作成します。

   Python

   import os
   from stripe import StripeClient
   from stripe.events import V1BillingMeterErrorReportTriggeredEvent
   
   from flask import Flask, request, jsonify
   
   app = Flask(__name__)
   api_key = os.environ.get('STRIPE_API_KEY')
   webhook_secret = os.environ.get('WEBHOOK_SECRET')
   

   35 行すべてを表示する

5. ハンドラをテストします。ハンドラを本番環境にデプロイする前に、Stripe CLI を使用してローカルリスナーを設定し、ローカルマシンにテスト用のイベントを送信します。 --forward-thin-to フラグを使用して thin イベントの転送先の URL を指定し、--thin-events フラグを使用して転送先の thin イベントを指定します。アスタリスク (*) が指定されているすべての thin イベント、または一部の thin イベントはアプリケーションに転送することができます。

   $ stripe listen --forward-thin-to localhost:4242/webhooks --thin-events "*"
   

6. ハンドラに対してテストイベントをトリガーします。トリガー関数を使用して次のコマンドを実行し、テストアカウントのイベントを個別にシミュレーションします。

   $ stripe trigger v1.billing.meter.error_report_triggered --api-key <your-secret-key>
   $ stripe trigger v1.billing.meter.no_meter_found --api-key <your-secret-key>
   

7. Webhook エンドポイントでイベントを処理している場合は、Webhook の署名を確認してエンドポイントを安全に保護し、すべてのリクエストが Stripe から送信されたものであることを検証します。

8. 再処理のため、無効なイベントを修正して再送信します。