# 移行の設計 Stripe の請求オブジェクトを Metronome のアーキテクチャーにマッピングし、製品カタログを設計して、実装パターンを選択します。 既存の顧客を Metronome に移行する前に、以下のように移行を設計します。 1. Stripe の請求オブジェクトを Metronome のアーキテクチャーにマッピングします。 2. 製品カタログを設計します。 3. 実装パターンを選択する。 ## Before you begin まだの場合は、[移行のスコープを設定](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/scope-your-migration.md)してください。 ## Stripe と Metronome の概念のマッピング Metronome の主要なオブジェクトと、それらが Stripe の従量課金の概念にどのように対応しているかを確認してください。 ### Metronome の主要なオブジェクト Metronome では、メータリング (測定対象) とレーティング (請求対象) を分離しています。これにより、イベントのインストルメンテーションを変更せずに料金体系を更新でき、その逆も可能です。 Metronome のオブジェクト階層: Usage Events > Billable Metrics > Products > Rate Cards > Contracts > Invoices。 | 概念 | 説明 | | ---------------- | ------------------------------------------------------------------------------------ | | **Usage Events** | 顧客アクティビティの未処理のレコード (例: 「顧客 X がモデル gpt-5 で 1,500 の入力トークンを使用した」) | | **課金対象メトリクス** | イベントを請求可能な数量に集計するルール。また、グループキー (価格設定や請求書での表示に使用されるプロパティ) を定義する場所でもあります。 | | **Products** | 請求書上の名前付きの項目。従量課金の製品に関する Billable Metrics と 1 対 1 の関係を持ちます | | **レートカード** | 各製品に価格を割り当てる一元化された価格表。単一の Rate Card を多数の顧客間で共有できます | | **Contracts** | Rate Card を参照し、請求期間を定義する顧客固有の契約。オプションでクレジット、コミット、上書きを含めることができます | | **Packages** | Rate Card と Contract の詳細を 1 つの再利用可能なパッケージにエンコードし、新しい顧客全体に適用します (PLG やセルフサーブフローに便利です) | | **請求書** | 使用量に基づいて請求期間ごとに自動生成され、契約に照らして評価されます | ### Stripe と Metronome の請求の概念の比較 | Stripe の基本的な従量課金の概念 | Metronome の概念 | 説明 | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Billing Meter](https://docs.stripe.com/api/billing/meter/object.md) | [Billable Metric](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-billable-metrics) | どちらも集計ルールを定義します。Streaming metrics は SUM、COUNT、MAX、LATEST をサポートします。SQL metrics はさらに UNIQUE (重複のないカウント) をサポートします。複合グループキーにより、多次元の価格設定が可能になります。グループキー、集計タイプ、イベントタイプフィルターは作成後に変更できません。 | | [Meter Event](https://docs.stripe.com/api/billing/meter-event/create.md) | [Usage Event (取り込み)](https://docs.metronome.com/api-reference/usage/ingest-events) | どちらも個々の使用量レコードを表します。Metronome イベントには重複排除のための `transaction_id` が含まれており、豊富なプロパティペイロードをサポートしています。 | | [Price (従量課金)](https://docs.stripe.com/api/prices.md) | [Rate (Rate Card 上)](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-manage-rate-cards) | Stripe Price は、単価とメーターのリンクを定義します。Metronome では、Rate は Rate Card 上の Product の価格設定を定義します。段階制料金体系、多次元価格設定、コミット固有のレートをサポートしています。 | | [Product](https://docs.stripe.com/api/products.md) | [Product](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-products-contracts) | Stripe では、Products により Prices がグループ化されます。Metronome では、Products は Billable Metrics と 1:1 の関係を持ちます。製品タイプ: Usage、Subscription (継続料金)、Composite (他の製品に対する % 請求)、Fixed (1 回限りまたはスケジュール設定済み)。 | | [Subscription](https://docs.stripe.com/api/subscriptions.md) | [Contract](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-products-contracts) | Metronome の Contract はより強力です。レートカードの参照、コミット、クレジット、ディスカウント、上書き、スケジュールが含まれます。 | | [Credit Grant](https://docs.stripe.com/api/billing/credit-grant/object.md) | [Prepaid Commit または Credit](https://docs.metronome.com/api-reference/contracts/create-a-contract) | コミットには請求書のスケジュールがあります (顧客は前払いするか、有効期限時に支払います)。クレジットは無料です (請求書のスケジュールはありません)。どちらも、優先度、有効期限、Contract でのスコープ付きの適用範囲をサポートしています。 | | [Subscription Schedule](https://docs.stripe.com/api/subscription_schedules.md) | [Contract の変更とスケジューリング](https://docs.metronome.com/guides/implement-metronome/migrate-amendments-to-edits) | Metronome は、契約内での価格変更、更新、変更のスケジューリングをネイティブにサポートしています。 | | [請求書](https://docs.stripe.com/api/invoices/object.md) | [請求書](https://docs.metronome.com/guides/invoices/overview) | Metronome は請求書を生成し、支払いを回収するために Stripe にプッシュします。デフォルトでは、請求期間の終了後から確定までに 24 時間の猶予期間が設けられています。 | 詳細については、[Metronome と Stripe の連携の仕組み](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md)をご覧ください。 ## 製品カタログを設計する 既存の Stripe の Meters、Prices、Products を、Metronome の製品カタログを設計するための出発点として使用してください。以下のセクションでは、各オブジェクトタイプについて説明します。 ### 課金対象メトリクス Metronome では 2 種類の課金対象メトリクスが提供されています。 - **Streaming Metrics** (推奨): イベントが到着するとリアルタイムで集計します。ほとんどのユースケースでこれを使用します。 - **SQL Metrics**: 1 日の平均、期間ごとの重複のないカウント、重み付けされた計算式などの複雑な計算に使用します。Streaming metrics で要件を満たせない場合にのみ SQL metrics を使用してください。 設計原則: - **Stripe メーターのセグメントを使用している場合**: Metronome の多次元の価格設定 (複合グループキー) を使用して、複数の Stripe Meters をより少ない Metronome Billable Metrics に統合できるかどうかを評価します。 - **セグメントを使用していない場合**: Metronome Billable Metrics は、同じ集計タイプを持つ既存の Stripe Meters に 1 対 1 でマッピングされる可能性が高くなります。 - **カーディナリティ**: グループキーのカーディナリティが 1,000 に近づいた場合は、Metronome の担当者にお問い合わせください。カーディナリティが高いプロパティ (request_id や上限のない ID など) をグループキーとして追加することは避けてください。 > 作成後にグループキー、集計タイプ、およびイベントタイプフィルターを変更することはできません。課金対象メトリクスを保存する前に、これらを慎重に計画してください。 > > 必要と思われる数より多くのグループキーを含めてください。未使用のグループキーはいつでも無視できますが、後から追加することはできません。将来的にディメンション別に価格を設定または表示する可能性がある場合は、今のうちにグループキーとして含めておきます。 ### 集計タイプのマッピング (Streaming metrics) | Stripe | Metronome | 説明 | | ------------ | --------- | ------------------- | | SUM | SUM | イベント全体で数値プロパティを合計する | | COUNT | COUNT | 一致するイベントをカウントする | | LAST | LATEST | ウィンドウ内の最新の値を取得する | | MAX (レガシーのみ) | MAX | ウィンドウ内の最大値 | ### SQL metrics UNIQUE (重複のないカウント) 集計の場合は、[SQL 課金対象メトリクス](https://docs.metronome.com/guides/implement-metronome/core-concepts/billable-metrics-sql-editor)を使用します。 ### グループキー グループキーによって、何に基づいて価格を設定できるか、および請求書での使用量の内訳が決定されます。これらは SQL の `GROUP BY` 句のようなものであり、プロパティ値に基づいて集約された使用量をバケットに分割します。 グループキーにより、Product で次のダウンストリーム設定が可能になります。 | ダウンストリームの使用 | 機能 | 例 | | ----------- | ---------------- | ----------------------------------------------------------------- | | 価格設定のグループキー | ディメンション値ごとに異なる価格 | `model_name` -> charge 1.50 USD for model-A, 0.30 USD for model-B | | 表示のグループキー | 請求書の項目の内訳 (同じ価格) | `user_id` -> show per-user usage on invoice | 一般的なグループキーの例: - `model_name`: モデルごとの価格設定 (価格設定のグループキー) - `region`: 地域ごとの価格設定 (価格設定のグループキー) - `instance_type`: GPU / インスタンスごとの価格設定 (価格設定のグループキー) - `user_id` : ユーザーごとの請求書の内訳、または Unique 集計を使用したシートベースの請求 (表示のグループキー) - `project_id`: プロジェクトごとの請求書の内訳 (表示のグループキー) Review your Stripe meter segment dimensions. These are your primary candidates for Metronome group keys. Also consider additional properties in your event payload that you’re not currently using for segmentation but might want for future pricing flexibility or invoice presentation. ### Products Metronome Products は、個々のサービス提供内容を表します。 | タイプ | ユースケース | Stripe での同等機能 | | ------------ | ---------------------------------------- | ------------- | | Usage | 消費量に基づく変動料金 (課金対象メトリクスが必要) | 従量課金ベースの料金 | | Subscription | スケジュールに基づく継続的な手数料 (プラットフォーム手数料、シートライセンス) | 継続料金 | | Composite | 他の商品のグループに対するパーセンテージでの請求 | – | | Fixed | 1 回限りまたはスケジュールされた支払い (コミットおよびクレジットに使用) | – | Products の主な設定オプション: - **グループキー**: 価格設定のグループキー (ディメンションごとに異なる価格) または表示のグループキー (請求書の内訳) を割り当てます。これらは、課金対象メトリクスで定義されたグループキーのサブセットである必要があります。 - **数量変換**: たとえば、個々のトークンを送信しますが、請求書には 100 万トークンごとに表示して価格を設定します。 - **丸め変換**: たとえば、秒数を送信しますが、請求書では最も近い分に丸めます。 ### レートカード Rate Card は、すべての Products のレートを含む一元化された価格設定のテンプレートです。各レートカードは、単一の法定通貨で表示されます。標準価格の信頼できる情報源として、単一のレートカードを作成します。レートカードのレートを更新すると、その変更はそれを参照するすべての契約に反映されます。個々の契約での上書きにより、特定の顧客向けのカスタム価格設定を管理します。 Rate Card の機能: - **多次元の価格設定**: 価格設定のグループキーを使用する場合は、ディメンション値ごとにレートを定義します (例: model-A は 1.50 ドル、model-B は 0.30 ドル)。 - **段階制料金体系**: 任意の製品に数量ベースの階層を設定します (例: 最初の 100 万トークンは 1.00 ドル、次の 100 万トークンは 0.80 ドル)。 - **Custom Pricing Units**: 法定通貨ではなくクレジットまたはカスタム単位で請求する場合は、Offering の下の Pricing Units で Custom Pricing Unit を作成し、レートカードで変換を設定します。 - **コミットレート**: 使用量がコミットから差し引かれる際に特別に適用されるレートを設定します。 - **レートの変更**: 新しいレートの開始日を指定してレートを編集します。変更は参照元の契約に反映されます。 ### Invoicing Metronome の[請求書のライフサイクル](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md)は次の手順に従います。 1. **ドラフト**: 請求期間を通じて使用量を蓄積します (Metronome で表示可能)。 2. **猶予期間**: 確定前の請求期間の最後にある 24 時間のウィンドウ (デフォルト)。遅れて到着した使用量データや修正を許可します。 3. **確定済み**: 猶予期間後に Metronome が請求書をロックします。これ以降の変更は許可されません。 4. **請求プロバイダーへの送信**: Metronome は確定した請求書を Stripe に送信します (Stripe の Customer に `InvoiceItem` オブジェクトと `Invoice` を作成します)。 5. **支払い済みまたは失敗**: Stripe が回収を処理します (Smart Retries、Radar、再試行の設定が自動的に適用されます)。 重要な考慮事項: - Stripe Tax、Anrok、または Avalara は、Stripe の請求書の確定時に適用できます。 - 顧客ごとに回収手段 (`charge_automatically` または `send_invoice`) を設定します。 - Metronome ではなく、Stripe ダッシュボードで支払いのステータスを管理します。 - 支払いを条件とするコミットの支払いステータスを監視する Webhook を設定します。 ## 実装パターンを選択する Metronome は Stripe との以下の[実装パターン](https://docs.stripe.com/billing/how-metronome-works-with-stripe.md)をサポートしています。 - **Metronome 単独**: Metronome がすべての請求とメータリングを処理し、確定した請求書を回収のために Stripe に送信します。Stripe Subscriptions から完全に移行する場合に最適です。 **Metronome 単独を選択するケース:** - すべての請求が従量課金制である - Metronome の完全な契約機能とコミット機能を使用する - 登録に Stripe Checkout や Payment Links を必要としない - **Metronome と Stripe Subscriptions の併用**: Stripe Subscriptions は継続課金と定額制の請求を処理し、Metronome は従量課金のメータリングと請求を個別に処理します。どちらも同じ Stripe 顧客に対して請求書を作成します。 **Metronome と Stripe Subscriptions の併用を選択するケース:** - Stripe Subscriptions で定額制またはシートベースの継続支払いがある - 従量課金以外の請求に Checkout、カスタマーポータル、Payment Links を維持する - 従量課金コンポーネントにのみ Metronome を必要とする ## 次のステップ 移行の範囲を定義して設計を行った後、[Metronome を設定](https://docs.stripe.com/billing/subscriptions/usage-based/migrate-to-metronome/set-up.md)します。