メインコンテンツへスキップ

API Reference - Events Ingestion

使用状況イベントの取り込みに関する完全なAPIドキュメントにアクセスし、イベント取り込みのリクエストとレスポンスを対話的にテストできます。

API Reference - Meters Creation

メーター作成に関する完全なAPIドキュメントを参照し、メーター作成のリクエストとレスポンスを対話的にテストできます。

​
メーターの作成

メーターは、請求目的のために使用イベントがどのように集約され、測定されるかを定義します。 メーターを作成する前に、使用追跡戦略を計画します：
  • 追跡したい使用イベントを特定する
  • イベントをどのように集約するかを決定する（カウント、合計など）
  • 特定のユースケースに対するフィルタリング要件を定義する

​
ステップバイステップのメーター作成

使用メーターを設定するためのこの包括的なガイドに従ってください：
1

Configure Basic Information

メーターの基本情報を設定します。
​
Meter Name
string
必須
追跡対象を明確に示す説明的な名前を選択してください。例: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”
​
Description
string
このメーターが何を測定するかを詳細に説明してください。例: “Counts each POST /v1/orders request made by the customer”
​
Event Name
string
必須
このメーターをトリガーするイベント識別子を指定します。例: “token”, “api.call”, “storage.usage”, “compute.session”
イベント名は使用状況イベントで送信する内容と完全に一致しなければなりません。イベント名は大文字小文字を区別します。
2

Configure Aggregation Settings

メーターがイベントから使用量をどのように計算するかを定義します。
​
Aggregation Type
string
必須
イベントの集計方法を選択してください:
受信したイベントの数を単純にカウントします。ユースケース：APIコール、ページビュー、ファイルアップロード計算: イベントの総数
​
Over Property
string
集計対象となるイベントメタデータのプロパティ名。
合計、最大、または最後の集計タイプを使用する場合、このフィールドは必須です。
​
Measurement Unit
string
必須
レポートや請求書に表示する単位ラベルを定義します。例: “calls”, “GB”, “hours”, “tokens”
3

Configure Event Filtering (Optional)

メーターに含めるイベントを制御する基準を設定します。
イベントフィルタリングでは、どのイベントが使用量計算に寄与するかを決定する高度なルールを作成できます。テストイベントの除外、ユーザーティアによるフィルタリング、特定のアクションに注力する場合に役立ちます。
イベントフィルタリングを有効にするイベントフィルタリングを有効にするを切り替えて、条件付きイベント処理をアクティブにします。フィルターロジックを選択複数の条件がどのように評価されるかを選択します：
すべての条件が真である場合にのみイベントがカウントされます。複数の厳格な基準を同時に満たす必要がある場合にこのオプションを使用してください。例: user_tier = "premium" AND endpoint = "/api/v2/users" を満たすAPIコールをカウントします。
フィルター条件の設定
1

Add Condition

「Add condition」をクリックして新しいフィルタールールを作成します。
2

Configure Property Key

イベントメタデータのプロパティ名を指定します。
3

Select Comparator

利用可能な演算子から選択してください:
  • equals - 完全一致
  • not equals - 除外フィルター
  • greater than - 数値比較
  • greater than or equals - 数値比較（包含）
  • less than - 数値比較
  • less than or equals - 数値比較（包含）
  • contains - 文字列に部分文字列を含む
  • does not contain - 文字列の除外フィルター
4

Set Comparison Value

比較対象の値を設定します。
5

Add Groups

「Add Group」を使用して、複雑なロジックのために追加の条件グループを作成します。
フィルターされたプロパティは、条件が正しく機能するためにイベントメタデータに含める必要があります。必要なプロパティが欠けているイベントはカウントから除外されます。
4

Create Meter

メーター構成を確認し、「Create Meter」をクリックしてください。
メーターが使用状況イベントの受信および集計に対応できるようになりました。

​
製品にメーターをリンクする

メーターを作成したら、使用量ベースの請求を有効にするために製品にリンクする必要があります。このプロセスは、メーターの使用データを顧客請求の価格ルールに接続します。 メーターを製品にリンクすることで、使用追跡と請求の間の接続が確立されます：
  • 製品は価格ルールと請求動作を定義します
  • メーターは請求計算のための使用データを提供します
  • 複数のメーターを単一の製品にリンクして複雑な請求シナリオを実現できます

​
製品設定プロセス

使用データを請求可能な料金に変換するために、製品設定を適切に構成します：
1

Choose Usage-Based Billing Product Type

製品作成または編集ページに移動し、製品タイプとして「Usage-Based」を選択してください。
2

Select Associated Meter

「Associated Meter」をクリックして、側面からメーター選択パネルを開きます。このパネルで、この製品の使用状況を追跡するメーターを構成できます。
3

Add Your Meter

メーター選択パネルでは:
  1. メーターを追加をクリックして、利用可能なメーターを表示します
  2. ドロップダウンリストから作成したメーターを選択します
  3. 選択したメーターが製品設定に表示されます
4

Configure Price Per Unit

メーターで追跡される使用量単位ごとの価格を設定します。
​
Price Per Unit
number
必須
メーターで測定された各単位に対していくら請求するかを定義します。例: 単位あたり$0.50 を設定すると次のようになります:
  • 1,000 単位消費 = 1,000 × 0.50=0.50 = 500.00 が請求される
  • 500 単位消費 = 500 × 0.50=0.50 = 250.00 が請求される
  • 100 単位消費 = 100 × 0.50=0.50 = 50.00 が請求される
5

Set Free Threshold (Optional)

課金が開始される前に無料使用枠を設定します。
​
Free Threshold
number
有料使用量の計算が始まる前に顧客が無償で消費できる単位数。仕組み:
  • 無料しきい値: 100 単位
  • 単位あたりの価格: $0.50
  • 顧客使用量: 250 単位
  • 計算: (250 - 100) × 0.50=∗∗0.50 = **75.00** が請求されます
無料しきい値はフリーミアムモデル、トライアル期間、またはプランに含まれる基本の許容量に最適です。
無料しきい値は各請求サイクルに適用され、顧客には毎月または請求スケジュールに応じて再度許容量が与えられます。
6

Save Configuration

メーターと料金設定を確認し、「Save Changes」をクリックして設定を確定します。
製品は従量課金制で構成され、測定された使用量に応じて自動的に顧客に課金されます。
今後の流れ:
  • メーターに送られた使用イベントが追跡および集計されます
  • 料金計算が設定した価格ルールを自動適用します
  • 顧客は各請求期間の実際の使用量に応じて課金されます
製品ごとに最大10個のメーターを追加でき、APIコール、ストレージ、コンピュート時間、カスタムメトリクスなど複数の次元で高度な使用状況追跡が可能です。

​
使用イベントの送信

メーターが構成されたら、アプリケーションから使用イベントを送信して顧客の使用を追跡できます。

​
イベント構造

各使用イベントには、次の必須フィールドが含まれている必要があります：
​
event_id
string
必須
この特定のイベントに対する一意の識別子。すべてのイベント間で一意である必要があります。
​
customer_id
string
必須
この使用状況が帰属するDodo Paymentsの顧客ID。
​
event_name
string
必須
メーター構成に一致するイベント名。イベント名が適切なメーターをトリガーします。
​
timestamp
string
イベントが発生したISO 8601形式のタイムスタンプ。指定がない場合は現在時刻が使用されます。
​
metadata
object
フィルタリングや集計に使用する追加のプロパティ。メーターで「Over Property」やフィルタ条件として参照している値を含めてください。

​
使用イベントAPIの例

イベントAPIを使用して、構成されたメーターに使用イベントを送信します： 
const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [
      {
        event_id: "api_call_1234",
        customer_id: "cus_atXa1lklCRRzMicTqfiw2", 
        event_name: "api.call",
        timestamp: new Date().toISOString(),
        metadata: {
          endpoint: "/v1/orders",
          method: "POST",
          response_size: 1024
        }
      }
    ]
  })
});

​
使用量ベースの請求分析

包括的な分析ダッシュボードを使用して、使用量ベースの請求データを監視および分析します。顧客の消費パターン、メーターのパフォーマンス、請求の傾向を追跡して、価格戦略を最適化し、使用行動を理解します。

​
概要分析

概要タブは、使用量ベースの請求パフォーマンスの包括的なビューを提供します：

​
アクティビティメトリクス

異なる期間にわたる主要な使用統計を追跡します：
​
Current Month
metric
現在の請求期間の使用状況アクティビティを表示し、月次の消費パターンを把握できます。
​
All Time
metric
追跡開始以来の累積使用統計を表示し、長期的な成長の洞察を提供します。
期間セレクターを使用して異なる月の使用状況を比較し、季節的なトレンドや成長パターンを特定します。

​
メーター数量チャート

時間経過による使用傾向を紫のグラデーションで表示するメーター数量チャート
メーター数量チャートは、次の機能を持つ使用傾向を視覚化します：
  • 時系列ビジュアライゼーション：日、週、または月にわたる使用パターンを追跡
  • 複数メーターサポート：異なるメーターのデータを同時に表示
  • 傾向分析：使用のスパイク、パターン、成長軌道を特定
チャートは使用量と選択した期間に応じて自動的にスケーリングし、小さな変動から大きな使用状況の変化まで明確に可視化します。

​
イベント分析

イベント名、ID、ページネーションコントロールを表示するイベント表
イベントタブは、個々の使用イベントに対する詳細な可視性を提供します：

​
イベント情報表示

イベントテーブルは、次の列を持つ個々の使用イベントの明確なビューを提供します：
  • イベント名：使用イベントを生成した特定のアクションまたはトリガー
  • イベントID：各イベントインスタンスの一意の識別子
  • 顧客ID：イベントに関連付けられた顧客
  • タイムスタンプ：イベントが発生した時刻
このビューでは顧客ベース全体の個別使用イベントを追跡・監視でき、請求計算と使用傾向の透明性を提供します。

​
顧客分析

顧客タブは、次の情報を持つ顧客使用データの詳細なテーブルビューを提供します：

​
利用可能なデータ列

​
Customer Email
string
顧客の識別のためのメールアドレス。
​
Subscription ID
string
顧客のサブスクリプションに対する一意の識別子。
​
Free Threshold
number
課金が発生する前にプランに含まれる無料単位数。
​
Price Per Unit
currency
無料しきい値を超えた使用量の単位あたりの費用。
​
Last Event
timestamp
顧客の最新の使用イベントのタイムスタンプ。
​
Total Price
currency
使用量ベースの請求で顧客に請求された合計金額。
​
Consumed Units
number
顧客が消費した単位数の合計。
​
Chargeable Units
number
無料しきい値を超えて課金対象となる単位数。

​
テーブル機能

  • 列フィルタリング：“列を編集”機能を使用して、特定のデータ列を表示/非表示にします
  • リアルタイム更新：使用データは最新の消費メトリクスを反映します

​
集約の例

さまざまな集約タイプがどのように機能するかの実用的な例を示します：

​
集約タイプの理解

異なる集約タイプは、異なる請求シナリオに対応します。使用量を測定し、請求する方法に基づいて適切なタイプを選択します。

​
実用的な実装例

これらの例は、各集約タイプの実際のアプリケーションを示し、サンプルイベントと期待される結果を示します。
シナリオ: APIリクエストの合計を追跡メーター構成:
  • イベント名: api.call
  • 集計タイプ: Count
  • 測定単位: calls
サンプルイベント：
{
  "events": [
    {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
  ]
}
結果: 顧客に3回分の呼び出しが請求されました
シナリオ: 転送された総バイト数に基づいて請求メーター構成:
  • イベント名: data.transfer
  • 集計タイプ: Sum
  • Over Property: bytes
  • 測定単位: GB
サンプルイベント：
{
  "events": [
    {
      "event_id": "transfer_1",
      "customer_id": "cus_123", 
      "event_name": "data.transfer",
      "metadata": {"bytes": 1073741824}
    },
    {
      "event_id": "transfer_2",
      "customer_id": "cus_123",
      "event_name": "data.transfer", 
      "metadata": {"bytes": 536870912}
    }
  ]
}
結果: 顧客に1.5 GBの転送量が請求されました
シナリオ: 同時接続ユーザー数の最大値に基づいて請求メーター構成:
  • イベント名: concurrent.users
  • 集計タイプ: Max
  • Over Property: count
  • 測定単位: users
サンプルイベント：
{
  "events": [
    {
      "event_id": "peak_1",
      "customer_id": "cus_123",
      "event_name": "concurrent.users", 
      "metadata": {"count": 15}
    },
    {
      "event_id": "peak_2",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 23}
    },
    {
      "event_id": "peak_3",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 18}
    }
  ]
}
結果: 顧客に最大同時ユーザー23人が課金されました

​
イベントフィルタリングの例

特定のエンドポイントへのAPIコールのみをカウント:フィルター構成:
  • プロパティ: endpoint
  • 比較演算子: equals
  • 値: /v1/orders
サンプルイベント：
{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}
結果: フィルター条件に一致するイベントのみがカウントされ、異なるエンドポイントのイベントは無視されます。

​
トラブルシューティング

使用量ベースの請求の実装に関する一般的な問題を解決し、正確な追跡と請求を確保します。

​
一般的な問題

ほとんどの使用量ベースの請求の問題は、次のカテゴリに分類されます：
  • イベントの配信と処理の問題
  • メーター設定の問題
  • データ型とフォーマットのエラー
  • 顧客IDと認証の問題

​
デバッグ手順

使用量ベースの請求をトラブルシューティングする際は：
  1. イベント分析タブでイベントの配信を確認します
  2. メーター設定がイベント構造と一致しているか確認します
  3. 顧客IDとAPI認証を検証します
  4. フィルタリング条件と集約設定を確認します

​
解決策と修正

よくある原因:
  • イベント名がメーター構成と完全に一致していない
  • イベントフィルタリング条件がイベントを除外している
  • 顧客IDがDodo Paymentsアカウントに存在しない
  • イベントタイムスタンプが現在の請求期間外である
解決策:
  • イベント名のつづりと大文字小文字を確認する
  • フィルタ条件を確認・テストする
  • 顧客IDが有効かつアクティブであることを確認する
  • イベントタイムスタンプが最新で正しくフォーマットされているか確認する
よくある原因:
  • Over Property名がイベントメタデータのキーと一致していない
  • メタデータ値のデータ型が間違っている（文字列 vs 数値）
  • 必須のメタデータプロパティが欠けている
解決策:
  • メタデータキーがOver Property設定と完全に一致していることを確認する
  • 文字列として渡されている数値を実際の数値に変換する
  • すべてのイベントに必要なプロパティを含める
よくある原因:
  • フィルタプロパティ名がイベントメタデータと一致していない
  • データ型（文字列 vs 数値）に対して誤った比較演算子を使用している
  • 文字列比較における大文字小文字の区別
解決策:
  • プロパティ名が正確に一致していることを再確認する
  • データ型に適した比較演算子を使用する
  • 文字列をフィルタリングする際に大文字小文字を考慮する