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

APIリファレンス - イベント取り込み

使用イベントを取り込むための完全なAPIドキュメントにアクセスし、イベント取り込みリクエストとレスポンスをインタラクティブにテストします。

APIリファレンス - メーター作成

メーターを作成するための完全なAPIドキュメントを探索し、メーター作成リクエストとレスポンスをインタラクティブにテストします。

​
メーターの作成

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

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

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

基本情報の設定

メーターの基本的な詳細を設定します。
​
メーター名
string
required
このメーターが追跡する内容を特定する明確で説明的な名前を選択します。例：“トークン”, “APIコール”, “ストレージ使用量”, “計算時間”
​
説明
string
このメーターが測定する内容の詳細な説明を提供します。例：“顧客によって行われた各POST /v1/ordersリクエストをカウントします”
​
イベント名
string
required
このメーターをトリガーするイベント識別子を指定します。例：“token”, “api.call”, “storage.usage”, “compute.session”
イベント名は、使用イベントで送信する内容と正確に一致する必要があります。イベント名は大文字と小文字を区別します。
2

集約設定の構成

メーターがイベントから使用量を計算する方法を定義します。
​
集約タイプ
string
required
イベントをどのように集約するかを選択します：
受信したイベントの数を単純にカウントします。ユースケース：APIコール、ページビュー、ファイルアップロード計算：イベントの総数
​
プロパティに対して
string
集約するイベントメタデータからのプロパティ名。
合計、最大、または最新の集約タイプを使用する場合、このフィールドは必須です。
​
測定単位
string
required
レポートや請求で表示するための単位ラベルを定義します。例：“コール”, “GB”, “時間”, “トークン”
3

イベントフィルタリングの設定（オプション）

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

条件を追加

条件を追加をクリックして、新しいフィルタールールを作成します。
2

プロパティキーの構成

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

比較子を選択

使用可能な演算子から選択します：
  • equals - 完全一致
  • not equals - 除外フィルター
  • greater than - 数値比較
  • greater than or equals - 数値比較（包括的）
  • less than - 数値比較
  • less than or equals - 数値比較（包括的）
  • contains - 文字列が部分文字列を含む
  • does not contain - 文字列除外フィルター
4

比較値を設定

比較のためのターゲット値を設定します。
5

グループを追加

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

メーターを作成

メーターの構成を確認し、メーターを作成をクリックします。
メーターは、使用イベントを受信して集約する準備が整いました。

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

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

​
製品設定プロセス

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

使用量ベースの請求製品タイプを選択

製品作成または編集ページに移動し、製品タイプとして使用量ベースを選択します。
2

関連メーターを選択

関連メーターをクリックして、サイドからメーター選択パネルを開きます。このパネルでは、この製品の使用を追跡するメーターを構成できます。
3

メーターを追加

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

単位あたりの価格を設定

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

無料のしきい値を設定（オプション）

請求が始まる前の無料使用許可を構成します。
​
無料のしきい値
number
顧客が有料使用計算が始まる前に消費できる無料単位の数。動作方法：
  • 無料のしきい値：100単位
  • 単位あたりの価格：$0.50
  • 顧客の使用量：250単位
  • 計算： (250 - 100) × 0.50=∗∗0.50 = **75.00**請求
無料のしきい値は、フリーミアムモデル、トライアル期間、または顧客にプランに含まれる基本的な許可を提供するのに最適です。
無料のしきい値は各請求サイクルに適用され、顧客に毎月または請求スケジュールに応じて新しい許可が与えられます。
6

設定を保存

メーターと価格設定の構成を確認し、変更を保存をクリックして設定を確定します。
製品は使用量ベースの請求に設定され、顧客の測定された消費に基づいて自動的に請求されます。
次に何が起こるか：
  • メーターに送信された使用イベントは追跡され、集約されます
  • 請求計算は自動的に価格ルールを適用します
  • 顧客は各請求サイクル中の実際の消費に基づいて請求されます
製品ごとに最大10のメーターを追加できることを忘れないでください。これにより、APIコール、ストレージ、計算時間、カスタムメトリックなど、複数の次元にわたる洗練された使用追跡が可能になります。

​
使用イベントの送信

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

​
イベント構造

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

​
使用イベントAPIの例

イベントAPIを使用して、構成されたメーターに使用イベントを送信します： 
const response = await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_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
        }
      }
    ]
  })
});

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

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

​
概要分析

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

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

異なる期間にわたる主要な使用統計を追跡します：
​
現在の月
metric
現在の請求期間の使用アクティビティを表示し、月ごとの消費パターンを理解するのに役立ちます。
​
全期間
metric
追跡を開始して以来の累積使用統計を表示し、長期的な成長の洞察を提供します。
時間期間セレクターを使用して、異なる月の使用を比較し、季節的な傾向や成長パターンを特定します。

​
メーター数量チャート

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

​
イベント分析

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

​
イベント情報表示

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

​
顧客分析

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

​
利用可能なデータ列

​
顧客メール
string
識別のための顧客のメールアドレス。
​
サブスクリプションID
string
顧客のサブスクリプションの一意の識別子。
​
無料のしきい値
number
請求が適用される前に顧客のプランに含まれる無料単位の数。
​
単位あたりの価格
currency
無料のしきい値を超えた使用の単位あたりのコスト。
​
最後のイベント
timestamp
顧客の最も最近の使用イベントのタイムスタンプ。
​
合計価格
currency
使用量ベースの請求に対して顧客に請求された合計金額。
​
消費単位
number
顧客が消費した単位の合計数。
​
請求可能単位
number
無料のしきい値を超え、請求される単位の数。

​
テーブル機能

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

​
集約の例

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

​
集約タイプの理解

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

​
実用的な実装例

これらの例は、各集約タイプの実際のアプリケーションを示し、サンプルイベントと期待される結果を示します。
シナリオ：APIリクエストの総数を追跡メーター設定：
  • イベント名：api.call
  • 集約タイプ：カウント
  • 測定単位：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
  • 集約タイプ：合計
  • プロパティに対して：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
  • 集約タイプ：最大
  • プロパティに対して：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が有効でアクティブであることを確認します
  • イベントのタイムスタンプが最近のもので、正しくフォーマットされているか確認します
一般的な原因：
  • プロパティ名がイベントメタデータのキーと一致しない
  • メタデータ値が誤ったデータ型（文字列対数値）である
  • 必要なメタデータプロパティが欠けている
解決策：
  • メタデータキーがプロパティ設定と正確に一致することを確認します
  • イベント内の文字列の数値を実際の数値に変換します
  • 各イベントにすべての必要なプロパティを含めます
一般的な原因：
  • フィルタープロパティ名がイベントメタデータと一致しない
  • データ型に対して誤った比較子（文字列対数値）
  • 文字列比較における大文字小文字の区別
解決策：
  • プロパティ名が正確に一致することを再確認します
  • データ型に適した比較子を使用します
  • 文字列をフィルタリングする際の大文字小文字の区別を考慮します