請求データのクエリ

Billing は、相互に連携する複数のコンポーネントで構成され、複数のテーブルのさまざまな側面の請求データを使用して、1 回限りの請求書や定期請求に対応します。主要なテーブルである subscriptions、invoices をはじめ、Billing 固有のテーブルはすべて、スキーマの Billing セクションにあります。

請求データをさらに調べるには、prices、products、coupons など、サブスクリプションや請求書のコンポーネントを示すその他のテーブルも利用できます。また、customers テーブルは Billing の基本的部分であり、レポート作成に必要なデータが収録されています。

サブスクリプション

subscriptions テーブルの各行は、個別の Subscription (サブスクリプション) オブジェクトに関するデータを示します。API でも、Stripe ダッシュボード内でも、同じ情報を取得できます。アカウントで作成するすべてのサブスクリプションに関するレポートを作成できます。

現在のサブスクリプション登録者についてのレポートを作成する際には、このテーブルから開始することをお勧めします。このテーブルは、他の関連テーブルに結合できるため、データをさらに詳細に調べることができます。

以下の例では、未払いとしてマークされたサブスクリプションと、その顧客の利用可能な連絡先情報のリストを取得します。

顧客

Customer (顧客) オブジェクトに関するデータは、customers テーブルに収録されています (これは、Billing テーブルグループには含まれません)。一般に請求ベースのレポートの一部として使用され、多数のテーブルと結合できます。保存された決済情報を使用して支払いを作成する場合にも利用できます。

次の例では、現在トライアル期間中のサブスクリプションの顧客のリストを取得します。各顧客の ID とメールアドレスの両方が取得されます。

商品と価格

商品は、顧客がサブスクリプションで購入できるアイテムを記述します。価格は商品に関連付けられており、コスト、請求期間、通貨を設定します。 subscriptions テーブルのデータを表示するときは、subscription_items と結合できます。さらに、アイテムの price_product_id を使用して、products.id に結合できます。

以下の例では、有効なサブスクリプションのリストを、商品名とその明細書表記とともに返します。

段階制料金

サブスクリプションで段階が設定された価格を使用している場合は、price_tiers テーブルで各段階に固有のデータを取得できます。たとえば、最初の段階の最大数量と使用されるユニット金額を含む、サブスクリプションの初期段階を把握するには、次のクエリを参照してください。

請求書

invoices テーブルには、個別の Invoice (請求書) オブジェクトに関するデータが収録されます。サブスクリプションのそれぞれから、顧客が支払うべき金額を示す請求書が反復的に生成されます。これにはサブスクリプションに必要な金額のほかに、追加で Invoice Item (請求書アイテム) が (ラインアイテムとして) 作成されている場合はそれらも自動的に含められます。

請求書は、個々の (Invoice) Line Items ((請求書) ラインアイテム) から構成されます。これらのラインアイテムは、顧客に対して請求されるサブスクリプションと、その請求書 に対して作成および適用される請求書アイテムを表します。請求書の内訳を調べてラインアイテムのそれぞれを分析するには、invoice_line_items テーブルを使用します。

このテーブルの source_id 列には、そのラインアイテムに対応するサブスクリプション (例: sub_XBppPnzdLrEcoGn) または請求書アイテム (例: ii_oaYg0MHTVCbp0gp) の ID が記載されます。source_type 列では、そのラインアイテムがサブスクリプションと請求書アイテムのいずれを表しているかが示されます。

他の外部キーとは異なり、invoice_line_items テーブルの subscription 列は、必ず入力されるとは限りません。対応する請求書アイテムがサブスクリプションである場合は、この列がブランクになります (その ID はすでに source_id 列に表示されています)。

請求書アイテム

請求書アイテムに関するデータは、invoice_items テーブルに示されます。一般に請求書アイテムは、次の請求サイクルの開始時に次回の請求書に適用される追加金額 (または差し引き金額) の指定に使用されます。請求書アイテムは、たとえば月間使用量を超えた顧客に請求する必要がある場合や、次回の請求書で未使用分のサービスのクレジットを提供する必要がある場合に作成します。

次の例では、特定のサブスクリプションのすべての請求書と関連する支払い ID を取得します。

請求書の合計と割引

請求書の小計は、割引適用前のサブスクリプション、請求書アイテム、および請求書の比例配分 (日割り / 秒割り計算) のすべての金額を表します。請求書の合計は割引および税の適用後の金額を表します。

invoice.total = invoice.subtotal - discount + invoice.tax

割引額を請求書に表示するための列はありません。代わりに、ラインアイテムの割引額を集計することでこれを計算できます。以下のクエリは、請求書、その期間の開始日と終了日、請求書の合計割引額のリストを返します。

請求書の日付と期間の処理

サブスクリプションの請求書は事前に請求されるため、顧客は請求サイクルの開始時に支払いを行います。これは、ラインアイテムの period 値で表されます。たとえば、月次のサブスクリプションを利用している顧客は、毎月始めに請求されます。 cancel_at_period_end を選択すると、サブスクリプションは月末まで有効であり、その後サブスクリプションは終了します。

請求書の period_start と period_end の値は、請求書アイテムがいつ作成されたかを表しますが、必ずしも顧客に請求されるサービス期間を完全に表しているわけではありません。たとえば、毎月 1 日に請求を受ける顧客が、15 日にその月間使用量を超えた場合、 顧客に請求される追加費用の請求書アイテムを作成することができます。この請求書アイテムは翌月 1 日に作成される次回の請求書に含まれます。次回の請求書を生成するときは、period_start は前月の 15 日 (追加のラインアイテムが最初に作成された日付) になります。

従量課金ベースの請求

従量課金を使用すると、商品やサービスの使用量に基づいて顧客に請求できます。

請求メーター

Meter オブジェクトは、請求期間中のメーターイベントを集計する方法を指定します。メーターイベントは、顧客がシステムで実行するすべてのアクション (API リクエストなど) を表します。メーターは価格に関連付けられ、請求内容の基礎を形成します。これらのオブジェクトは、billing_meters テーブルから使用できます。

次のクエリは、有効な請求メーターをすべて返します。

請求メーターイベントのサマリー

Billing Meter Event Summary オブジェクトは、指定した期間内の顧客の請求メーターイベントの集計ビューを表します。これは、その期間に顧客が発生した使用量を表します。これらのオブジェクトは、billing_meter_event_summaries テーブルから使用できます。value_grouping_window 列に示されているように、時間ごとのサマリーを使用できます。

次のクエリは、特定の顧客の請求メーターイベントの合計を返します。

請求メーター使用状況分析

Billing Meter 使用状況分析 オブジェクトは、指定された期間における顧客の Billing メーター使用状況の分析サマリーを表します。メーター、ディメンション、テナントでグループ化したり、フィルタリングしたりして、顧客分析ダッシュボードを強化できます。

導入ガイド では、リクエストとレスポンスの形状を説明しています。

この API はパブリックプレビューで利用できます。こちらをクリック でこの API へのアクセスをリクエストできます。

請求メーターの無効なイベント

Billing Meter Invalid Event オブジェクトは、正常に検証されなかった請求メーターイベントを表します。これらのオブジェクトは、billing_meter_invalid_events テーブルから使用できます。関連付けられた billing_meter_invalid_events_payload テーブルには、元のイベントのイベントペイロードが含まれています。

次のクエリは、特定の顧客の無効な請求メーターイベントをすべて返します。

クーポン

Coupon (クーポン) オブジェクトは、サブスクリプションや顧客に適用できる、金額または率による割引を表します。

割引

割引はクーポンの適用であり、Discount オブジェクトで表されます。以下のクエリは、サブスクリプションとそれに関連付けられた割引とクーポンのリストを返します。

プロモーションコード

プロモーションコード は、顧客が引き換え可能なクーポンのコードを表します。以下のクエリは、特定のクーポンに関連するプロモーションコードのリストを提供し、各コードが引き換えられた回数を表示します。

サブスクリプションアイテム変更イベント

subscription_item_change_events テーブルは、月間経常収益 (MRR) に影響するサブスクリプションアイテムおよびサブスクリプションの数量の変更を追跡します。この表を使用して、個人顧客、商品、プランの MRR を計算し、ビジネスモデルのカスタム指標定義を作成し、サブスクリプションの数量の変更を追跡します。

local_event_timestamp and event_timestamp

このテーブルには、次の 2 つのタイムスタンプ列が含まれます。

• event_timestamp: これは UTC タイムスタンプです。
• local_event_timestamp: このタイムスタンプは、お客様のタイムゾーン (通常は、お客様の Stripe アカウントを作成した人物のタイムゾーン) です。

通貨

ここでは、サブスクリプションアイテムの売上処理通貨が、小文字の 3 文字の ISO 通貨コードとして記載されています。通貨は、Stripe がサポートしているものでなければなりません。

mrr_change

mrr_change 列は、サブスクリプション項目の決済通貨の補助単位 (USD の場合はセントなど) の MRR に対するイベントのプラスの影響またはマイナスの影響を示します。

quantity_change

quantity_change 列は、顧客が登録しているサブスクリプションアイテムの数量に関わる、プラスまたはマイナスの変化を表します。

event_type

その他の列

その他の列 (product_id、price_id、customer_id、subscription_id、subscription_item_id) には、サブスクリプションアイテム変更イベントに関連する ID が格納されます。

クエリ例

その他の最新の例については、Sigma サイドバーのクエリテンプレートライブラリーのサブスクリプションセクションをご覧ください。

このテーブルから月間経常収益 (MRR) と有効な登録者の数を計算するには、ウィンドウ関数を使用する必要があります。さらに、異なる通貨を使用する顧客が存在する場合は、外貨為替を計算する必要があります。この計算の目的は、月次の MRR と有効なサブスクリプション登録者の変化を追跡し、新規追加、再有効化、拡大、縮小、解約を区別することです。最終結果は、USD のセントなどの補助通貨単位で表示されます。