課金使用状況 API

大事なThe Billing Usage API is in Early Access. Interactive API reference documentation will be available when the API is generally released on June 10, 2026.

Billing Usage API を使用すると、毎月の請求書の背後にある同じ請求データにプログラムでアクセスできます。オンデマンドでコストを照会し、結果を独自のシステムに統合し、自動レポートパイプラインを構築します。

Billing Usage API は、次の必要がある場合に使用します。

コストレポートパイプラインの自動化
請求データを独自のダッシュボードまたは財務システムに統合する
オンデマンドでアカウント階層全体にわたるクエリ
前期比分析のための月レベルでのコストの集計

請求データへのアクセス方法を選択する

NTT CPaaS は、Web インターフェイスの 財務レポート と、プログラムによるアクセス用の Billing Usage API の 2 つのサーフェスを通じて、同じ請求グレードのデータを公開します。ワークフローに合ったオプションを選択します。

機能	財務報告	課金使用状況 API
アクセス	Webインターフェイス(1回限りまたは繰り返し)	オンデマンド、非同期
時間粒化	月次合計、オプションの日の内訳	日または月
キャンペーン参照でフィルタ	いいえ (寸法としてのみ使用可能)	はい
名前解決	キャンペーン名とテンプレート名を表示します	ID のみ
エクスポート形式	XLSX、CSV	JSON (コールバック)
スケジュール設定	定期 (月次)	オンデマンドのみ

Webインタフェースオプションについては、財務諸表を参照してください。

仕組み

Billing Usage API は、非同期の要求/応答パターンを使用します。クエリを送信すると、処理が完了すると、NTT CPaaS がサーバー上のコールバック URL に結果を配信します。

Submit a request
フィルター、集計ディメンション、サーバーを指す callbackUrl を使用して /billing/1/usage/query に POST します。

Receive a request ID
API はすぐに requestId を返します。処理は非同期に実行されるため、サーバーを待つ必要はありません。

Receive results at your callback URL
処理が完了すると、NTT CPaaSは結果をJSONとしてcallbackUrlにPOSTします。処理時間は、クエリの複雑さと日付範囲によって異なります。

アクセスと可用性

Billing Usage APIを使用するには、次のものが必要です。

billing:usage:view スコープを持つ APIキー。「 API 認証を参照してください。
コールバック URL: クエリの完了時に NTT CPaaS POST が生成されるサーバー上のパブリックに到達可能なエンドポイント。

デフォルトでは、結果には、アカウント、関連するサブアカウント、および会社の下のすべてのアカウントのデータが含まれます。このクロスアカウントビューは、請求構造を反映しています。サブアカウントユーザーには、自分のデータのみが表示されます。アカウント階層と可視性を参照してください。

大事なThe Billing Usage API is not available for legacy account setups. This is a structural limitation; it cannot be enabled on request. If you are unsure whether your account uses a legacy setup, contact your account manager.

カバレッジ

請求カテゴリコードの完全なリストについては、請求データリファレンスの「カテゴリ](/billing-usage-api/billing-data-reference#categories)」を参照してください。

データのファイナライズ

大事なData for the current month is provisional and may change until finalized on the 5th of the following month. Integrate finalized data only into financial or billing systems.

当月の請求データは、月が終わるまで暫定的です。合計は、請求書が発行される 翌月 5 日 に確定するまで変更される場合があります。

当月のデータは、次の理由で変更される可能性があります。

遅れた交通記録
遡及的な数量ベースの割引
価格調整

API レスポンスには、クエリ内の各請求期間のファイナライズステータスを示すmetadata.billingPeriods配列が含まれています。財務計画または請求の目的で請求データを使用する前に、必ず請求書と照合してください。

手記If you are on a fixed WhatsApp MAU subscription plan, only overage charges are visible in the data. Included user counts are not returned.

データスコープ

これらの制約は、すべての請求データサーフェス(財務レポート、請求使用状況 API)に適用されます。

保持期間: 当月および最大 2 か月前
タイムゾーン: UTC。カスタムタイムゾーンはサポートされていません。
マルチデータセンター: データはデータセンターごとに生成され、アクセスされます。データセンター間の集約はサポートされていません。アカウントがホストされている場所を確認するには、アカウントマネージャーまたはサポートにお問い合わせください。
請求書発行の調整: 請求データは、NTT CPaaS 請求書と同じ月次サイクル、通貨形式、請求構造に従います。

アカウント階層と可視性

デフォルトでは、Billing Usage API は、アカウント階層全体 (自分のアカウント、関連するサブアカウント、会社の下のすべてのアカウント) のデータを返します。これは請求構造を反映しています。

サブアカウントユーザーには、自分のアカウントデータのみが表示されます。結果を特定のアカウントに絞り込むには、accountKeysフィルタパラメータを使用します。

課金使用量 API およびメトリック API

Billing Usage API と Metrics API は異なるものを測定し、直接比較することはできません。Billing Usage API は課金されたメッセージのみをカウントし、すべてのチャネルがメッセージごとに課金されるわけではありません (たとえば、RCS は、個々のメッセージごとではなく、会話セッションごとに課金されます)。メトリック API は、請求ステータスに関係なく、すべてのメッセージをカウントします。タイムゾーンの構成により、2 つのクエリ間に異なる期間の境界が生成される場合もあります。

コスト調整には Billing Usage API を使用し、デリバリーとエンゲージメントの分析には Metrics API を使用します。

Related pages

Query billing data
Build your first request, understand filters and aggregation dimensions, and handle the response.

Billing data reference
Look up cost fields, billing categories, traffic types by channel, and all available aggregation dimensions.

Financial reports
View the same billing data through the web interface with scheduling and export options.

請求データのクエリ