# 料金プランによる高度な従量課金を導入

使用状況と継続課金に基づいて顧客に請求します。

さまざまな料金コンポーネントを 1 つの料金プランにグループ化して、複数の請求戦略を組み合わせた複雑な料金モデルを実装できます。たとえば、従量課金のレートカード、継続支払いのライセンス手数料、継続クレジット付与の割り当てのサービスアクションを含む料金プランを作成できます。顧客が登録すると、Stripe は設定した頻度ですべての継続コンポーネントに自動的に登録して請求します。

サポートされる価格モデルは以下のとおりです：

- 従量課金
- トップアップによるリアルタイムのクレジットバーンダウンモデル (初期金額を使用量に応じて段階的に消費)
- 定額手数料と超過料金

> 料金プランは[プライベートプレビュー](https://docs.stripe.com/release-phases.md)であり、すべての Stripe ユーザーに一般提供が開始される前に、機能と組み込みパスが変更される可能性があります。アクセスをリクエストするには、からお問い合わせください。

## Before you begin

- 料金プランは `/v2` API エンドポイントを使用しています。[/v2 および /v1 ネームスペースの詳細をご確認ください](https://docs.stripe.com/api-v2-overview.md)。
- [サンドボックス](https://docs.stripe.com/sandboxes.md)を使用して料金プランの導入をテストします。`/v2` API でテスト環境を使用することはできません。

このガイドの [ガイド付き API (ブループリント)](https://dashboard.stripe.com/test/workbench/blueprints/usage-based-billing?code-pane-shown=true) バージョンをダッシュボードで使用することもできます。

## 料金プランを作成

Stripe ダッシュボードまたは API を使用して、料金体系モデルの関連するすべての請求コンポーネントを含む料金プランを作成します。

料金プランごとに、以下を設定します。

- **通貨**: 料金プランのすべてのコンポーネントの通貨を指定します。
- **価格に税金を含める**: 価格に税金を含めるか (内税)、請求書の小計に税金を含めるか (外税) するかを指定します。詳細は [Billing の内税と外税](https://docs.stripe.com/billing/taxes/tax-rates.md#inclusive-vs-exclusive-tax)をご覧ください。
- **メタデータ**: オプションで料金プランに独自のメタデータを追加します。

通貨と税金のパラメーターを設定したら、プランの関連コンポーネントを定義します。どのコンポーネントを含めるかは、料金体系モデルによって異なります。このガイドでは、3 つのコンポーネント ((レートカード、ライセンス手数料、およびサービスアクション) のすべてについて説明します。たとえば、従量課金とトップアップによるリアルタイムクレジットバーンダウンにはレートカードのみが必要で、定額手数料と超過分にはレートカードとライセンス手数料が必要で、超過分のある継続クレジットにはレートカードとサービスアクションが必要です。

#### ダッシュボード

### 料金プランを作成する

1. [料金プラン](https://dashboard.stripe.com/test/pricing-plans)ページで、**料金プランを作成** をクリックします。
1. 料金プランエディタで以下を実行します。
   - 表示名、通貨、および税金の動作を指定します。
   - (オプション) **Advanced settings** (詳細設定) で、説明、固有の検索キー、メタデータを指定します。
1. **続行**をクリックします。

### レートカードを追加

1. 料金プランエディターで、+ と **料金表 (Rate card)** をクリックします。
1. レートカードエディタで以下を実行します。
   - 表示名を指定します。
   - サービス期間を指定します。
   - (オプション) **Advanced settings** (詳細設定) で、検索キーとメタデータを指定します。
1. **続行**をクリックします。

### レートカードにレートを関連付ける

1. レートエディターで以下を実行します。
   - 従量制項目の表示名を指定します (`Hypernian tokens` など)。
   - 既存の **メーター** を選択するか、+ をクリックして新しいメーターを作成します。
   - **価格タイプ**: **固定レート**、[数量](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#volume-based-pricing)、または[段階制](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#graduated-pricing)を選択します。たとえば、Hypernian は固定レートを使用します。
     - **Sell as** (販売方法) で、個人ユニットまたはユニットのパッケージグループを選択します。たとえば、AI 企業がトークンを `100` ユニットのパッケージとして、パッケージあたり `0.04 USD` で販売する場合があります。
     - パッケージの場合は、 **パッケージあたりのユニット数** を入力します。
     - **パッケージの端数** を切り上げるか切り捨てるかを選択します。切り上げた場合、110 ユニットを使用するユーザーには 0.08 USD が請求されます。
     - **パッケージ価格**を入力します。
   - (オプション) **詳細設定** で、 **商品の税コード** ([税コードの詳細](https://docs.stripe.com/tax/tax-codes.md))、 **ユニットラベル** 、 **ルックアップキー** 、 **メタデータ** の指定などの、従量課金アイテムのオプション設定をしてください。料金にメタデータを追加することもできます。
1. **完了**をクリックします。
1. (オプション) + **料金の追加** をクリックして、料金表 (課金ルールセット) に料金を追加します。

### ライセンス料金を追加

1. 料金プランエディターで、+ と **ライセンス料** をクリックします。
1. ライセンス手数料エディターで以下を実行します。
   - ライセンス項目の表示名を指定します。
   - サービス期間を指定します。
   - **価格タイプ**: の選択: **固定レート** 、[数量ベース](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#volume-based-pricing)、または[段階制](https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing.md#graduated-pricing)を選択します。例えば、ユニットあたり `50.00 USD` のようにします。
   - (オプション) **詳細設定** で、 **商品の税コード** ([税コードの詳細](https://docs.stripe.com/tax/tax-codes.md))、 **ユニットラベル** 、 **ルックアップキー** 、 **メタデータ** の指定などの、ライセンスアイテムのオプション設定をしてください。料金にメタデータを追加することもできます。
1. **完了**をクリックします。

### サービスアクションを追加する

1. 料金プランエディターで、+ と **クレジット付与** をクリックします。
1. 継続クレジット付与エディターで以下を実行します。
   - クレジット付与の表示名を指定します。
   - サービス期間を指定します。
   - クレジット額を指定します。
   - (オプション) **詳細設定** で、 **アプリケーション** や **ルックアップキー** の指定など、定期的なクレジット付与を設定してください。
1. **完了**をクリックします。

料金プランの設定が完了したら **料金プランの作成** をクリックします。

#### API

### 料金プランを作成する

[料金プラン](https://docs.stripe.com/api/v2/pricing-plans.md?api-version=preview) を作成する際は、表示名と通貨を指定し、税金処理を指定します ([税金処理と料金表](https://docs.stripe.com/tax/subscriptions/rate-card-tax-codes-tax-behavior.md#set-a-default-tax-behavior-recommended) の詳細をご確認ください)。

```curl
curl -X POST https://api.stripe.com/v2/billing/pricing_plans \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "display_name": "Pro Pricing Plan",
    "currency": "usd",
    "tax_behavior": "exclusive"
  }'
```

料金プランリクエストを送信すると、Stripe は有効な `Pricing Plan` オブジェクトを返します。新しい顧客を無効な料金プランに登録することはできません。

```json
{
  "id": "bpp_test_61SjPwyNGx88hyuOg16SjPfE4ZSQFjWjdqlzQfWMCH1E",
  "object": "v2.billing.pricing_plan",
  "active": true,
  "created": "2025-06-14T21:52:04.000Z",
  "currency": "usd",
  "description": null,
  "display_name": "Pro Pricing Plan",
  "latest_version": "bppv_test_123",
  "live_version": "bppv_test_123",
  "lookup_key": null,
  "metadata": {},
  "tax_behavior": "exclusive"
}
```

### レートカードを追加

料金プランにレートカードを関連付けて、使用量に基づいて顧客に請求するには、レートカードを作成し、表示名、通貨、サービス間隔、税金処理を指定します。

```curl
curl -X POST https://api.stripe.com/v2/billing/rate_cards \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "display_name": "Hypernian",
    "service_interval": "month",
    "service_interval_count": 1,
    "currency": "usd",
    "tax_behavior": "exclusive"
  }'
```

### メーターを作成する

```curl
curl https://api.stripe.com/v1/billing/meters \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "display_name=Hypernian tokens" \
  -d event_name=hypernian_tokens \
  -d "default_aggregation[formula]=sum" \
  -d "customer_mapping[event_payload_key]=stripe_customer_id" \
  -d "customer_mapping[type]=by_id" \
  -d "value_settings[event_payload_key]=value"
```

### 従量制項目を作成する

メーターを作成したら、LLM モデルやトークン使用量のティアなど、顧客が支払う特定の項目を表す従量制項目を作成します。

```curl
curl -X POST https://api.stripe.com/v2/billing/metered_items \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "display_name": "Hypernian tokens",
    "meter": "{{METER_ID}}",
    "lookup_key": "hypernian_tokens"
  }'
```

### メーターにレートを関連付ける

従量制項目を作成したら、メーターにレートを関連付けます。

```curl
curl -X POST https://api.stripe.com/v2/billing/rate_cards/{{RATE_CARD_ID}}/rates \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "metered_item": "{{METERED_ITEM_ID}}",
    "unit_amount": "5"
  }'
```

### 料金プランにレートカードを関連付ける

レートを作成したら、料金プランにレートカードを関連付けます。

```curl
curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "type": "rate_card",
    "rate_card": {
        "id": "{{RATE_CARD_ID}}",
        "version": "{{RATE_CARD_VERSION}}"
    },
    "metadata": {
        "existing_key": "updated_value",
        "new_key": "new value"
    }
  }'
```

### ライセンス料金を追加

ライセンス料金は固定の継続決済であり、前払い手数料の請求に使用できます。

まず、ライセンス項目を作成します。

```curl
curl -X POST https://api.stripe.com/v2/billing/licensed_items \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "display_name": "Pricing Plan Licensed Item"
  }'
```

次に、ライセンス料金を作成します。

```curl
curl -X POST https://api.stripe.com/v2/billing/license_fees \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "display_name": "E2E License",
    "licensed_item": "{{LICENSED_ITEM_ID}}",
    "unit_amount": "50000",
    "service_interval": "month",
    "service_interval_count": 1,
    "currency": "usd",
    "tax_behavior": "exclusive"
  }'
```

最後に、ライセンス料金を料金プランに関連付けます。

```curl
curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "type": "license_fee",
    "license_fee": {
        "id": "{{LICENSE_FEE_ID}}",
        "version": "{{LICENSE_FEE_VERSION}}"
    },
    "lookup_key": "monthly-fee-component",
    "metadata": {
        "existing_key": "updated_value",
        "new_key": "new value"
    }
  }'
```

### サービスアクションを追加する

継続クレジット付与などの新しいコンポーネントを料金プランに追加できます。[クレジットバーンダウン料金体系モデル](https://docs.stripe.com/subscriptions/pricing-models/usage-based-pricing.md#credit-burndown)を使用している場合は、継続クレジット付与を使用します。サービスアクションを使うと、顧客に継続クレジットを提供でき、利用量に応じた料金など特定の課金対象アイテムの請求額を相殺できます。

サービスアクションを作成する際は、以下を設定します。

- 金額
- 請求の頻度
- 該当する請求対象アイテム

サービス期間の終了時に期限切れになる 10 USD の月次クレジット付与を作成するには、以下の手順に従います。

```curl
curl -X POST https://api.stripe.com/v2/billing/service_actions \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "service_interval": "month",
    "service_interval_count": 1,
    "type": "credit_grant",
    "lookup_key": "credit grant 28",
    "credit_grant": {
        "name": "Credit grant 28",
        "expiry_config": {
            "type": "end_of_service_period"
        },
        "applicability_config": {
            "scope": {
                "price_type": "metered"
            }
        },
        "amount": {
            "type": "monetary",
            "monetary": {
                "value": 1000,
                "currency": "usd"
            }
        }
    }
  }'
```

料金プランにサービスアクションを紐付けます。

```curl
curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "type": "service_action",
    "service_action": {
        "id": "{{SERVICE_ACTION_ID}}"
    },
    "lookup_key": "credit-grant-28",
    "metadata": {
        "existing_key": "updated_value",
        "new_key": "new value"
    }
  }'
```

### 料金プランを有効にする

料金体系モデルに関連するコンポーネントを追加したら、そのバージョンの料金プランを有効化します。プランの有効化後は、[顧客に登録](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#subscribe)することができます。

```curl
curl -X POST https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}} \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "live_version": "latest"
  }'
```

## 顧客を料金プランに登録する

料金プランを設定後、顧客をサブスクライブできます。[Stripe がホストするページまたは組み込みコンポーネントを決済 UI](https://docs.stripe.com/payments/checkout.md) として、[Checkout セッション API](https://docs.stripe.com/api/checkout/sessions.md) を使用して、サブスクリプションを作成できます (Checkout セッションでは顧客も作成されます)。API を使用して、料金プランのサブスクリプションを直接作成することもできます。ダイレクト API 方式を使用する場合は、[顧客](https://docs.stripe.com/api/customers/create.md)、[回収設定](https://docs.stripe.com/api/v2/billing-settings/collection-settings/create.md?api-version=preview)、[請求ケイデンス](https://docs.stripe.com/api/v2/billing/cadences/create.md?api-version=preview)、[請求インテント](https://docs.stripe.com/api/v2/billing-intents/intents/create.md?api-version=preview) を作成して、料金プランのサブスクリプションを作成する必要があります。

#### Stripe ホスト型ページ

[Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) を使用して、顧客の決済ページを作成します。顧客が **登録** をクリックすると、Checkout Session は [Customer](https://docs.stripe.com/api/customers.md) オブジェクト (セッションに顧客 ID を指定しなかった場合) と料金プランサブスクリプションを作成します。`checkout_items` に複数のアイテムがある場合、各アイテムに料金プランサブスクリプションが作成されます。

ここでは、決済における料金プラン全体の例をご紹介します。
![料金プラン例](https://b.stripecdn.com/docs-statics-srv/assets/checkout_pricing_plan_example.2156a15535345b113c30e7efabe72867.png)

Stripe Checkout に表示される料金プラン

### 非公開ベータ期間中の Checkout セッションの制限

プライベートプレビュー中:

- 最大 5 つの [checkout_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items)をまで指定することができます。
- 使用できるのは、カード、Link、Apple Pay、Google Pay のみです。
- [請求サイクルの起点](https://docs.stripe.com/billing/subscriptions/billing-cycle.md)を指定して渡すことはできません。
- [税率](https://docs.stripe.com/billing/taxes/tax-rates.md)は適用できず、代わりに自動税額計算のみ使用できます。
- 割引は使用できません。
- 顧客の[サブスクリプションを](https://docs.stripe.com/payments/checkout/limit-subscriptions.md) 1 つに制限することはできません。
- [Connect](https://docs.stripe.com/connect.md) は使用できません。
- [オプション項目](https://docs.stripe.com/payments/checkout/optional-items.md)や[クロスセル](https://docs.stripe.com/payments/checkout/cross-sells.md)は追加できません。

[advanced-ubb-private-preview@stripe.com](mailto:advanced-ubb-private-preview@stripe.com) までご連絡いただければ、早期にアクセスし、製品に関するフィードバックやリクエストを共有することができます。

料金プランで [Checkout セッションを作成](https://docs.stripe.com/api/checkout/sessions/create.md)するには、[checkout_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items) 配列に[type](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items-type) を `pricing_plan_subscription_item` に設定し、`pricing_plan_subscription_item` 設定を含むオブジェクトを含めます。ではなく `checkout_items` を `line_items`の代わりに使用する場合は、[mode](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-mode) を指定する必要はありません。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2025-09-30.preview;checkout_product_catalog_preview=v1" \
  -d customer={{CUSTOMER_ID}} \
  -d "checkout_items[0][type]=pricing_plan_subscription_item" \
  -d "checkout_items[0][pricing_plan_subscription_item][pricing_plan]={{PRICING_PLAN_ID}}" \
  -d success_url={{SUCCESS_URL}}
```

料金プランにライセンス料が含まれている場合は、ライセンス料の数量を含める必要があります。

ライセンス手数料コンポーネント ID を取得します。

```curl
curl https://api.stripe.com/v2/billing/pricing_plans/{{PRICING_PLAN_ID}}/components \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-09-30.preview"
```

ライセンス手数料コンポーネント ID を使用して Checkout Session を作成します。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2025-09-30.preview;checkout_product_catalog_preview=v1" \
  -d customer={{CUSTOMER_ID}} \
  -d "checkout_items[0][type]=pricing_plan_subscription_item" \
  -d "checkout_items[0][pricing_plan_subscription_item][pricing_plan]={{PRICING_PLAN_ID}}" \
  -d "checkout_items[0][pricing_plan_subscription_item][component_configurations][{{LICENSE_COMPONENT_ID}}][type]=license_fee_component" \
  -d "checkout_items[0][pricing_plan_subscription_item][component_configurations][{{LICENSE_COMPONENT_ID}}][license_fee_component][quantity]=1"
```

このページには料金プランの詳細が表示され、顧客の支払い情報が収集されます。顧客がセッションを完了すると、料金プランのサブスクリプションが作成され、顧客は `success_url` に指定した URL にリダイレクトされます。[Checkout でのリダイレクト動作のカスタマイズの詳細](https://docs.stripe.com/payments/checkout/custom-success-page.md)をご確認ください。

#### 埋め込みコンポーネント

料金プランの決済ページの外観をより詳細に制御するには、[組み込みコンポーネント](https://docs.stripe.com/payments/quickstart-checkout-sessions.md) と Checkout Session API を使用できます。組み込みコンポーネントの [Session](https://docs.stripe.com/js/custom_checkout/session_object) オブジェクトは、[session.orderSummaryItems](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-orderSummaryItems) で料金プランの詳細を公開し、料金プラン、ライセンス料金、料金表の注文サマリーを表示できるようにします。

サーバー上で Checkout Session を作成する際には、引き続き同じ`checkout_items` パラメータを使用する必要があります。

### 非公開ベータ期間中の Checkout セッションの制限

プライベートプレビュー中:

- 最大 5 つの [checkout_items](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-checkout_items)をまで指定することができます。
- 使用できるのは、カード、Link、Apple Pay、Google Pay のみです。
- [請求サイクルの起点](https://docs.stripe.com/billing/subscriptions/billing-cycle.md)を指定して渡すことはできません。
- [税率](https://docs.stripe.com/billing/taxes/tax-rates.md)は適用できず、代わりに自動税額計算のみ使用できます。
- 割引は使用できません。
- 顧客の[サブスクリプションを](https://docs.stripe.com/payments/checkout/limit-subscriptions.md) 1 つに制限することはできません。
- [Connect](https://docs.stripe.com/connect.md) は使用できません。
- [オプション項目](https://docs.stripe.com/payments/checkout/optional-items.md)や[クロスセル](https://docs.stripe.com/payments/checkout/cross-sells.md)は追加できません。

[advanced-ubb-private-preview@stripe.com](mailto:advanced-ubb-private-preview@stripe.com) までご連絡いただければ、早期にアクセスし、製品に関するフィードバックやリクエストを共有することができます。

### 製品カタログのベータヘッダーを使用する

発行可能なキーでフロントエンドの Stripe インスタンスを初期化する際、`custom_checkout_product_catalog_1`ベータヘッダーを渡します。

```js
const stripe = Stripe(
  '<<YOUR_PUBLISHABLE_KEY>>',{betas: ['custom_checkout_product_catalog_1']},
);
```

```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<<YOUR_PUBLISHABLE_KEY>>", {betas: ['custom_checkout_product_catalog_1'],
});
```

#### API

API を使用して直接[顧客を作成](https://docs.stripe.com/api/customers/create.md)し、次に[請求間隔を作成](https://docs.stripe.com/api/v2/billing-cadences/cadences/create.md?api-version=preview)します。顧客のデフォルトの決済手段に自動的に請求することも、請求書を送信して手動で支払ってもらうことも可能です。

顧客および請求期間を作成したら、[料金プランのサブスクリプション](https://docs.stripe.com/api/v2/billing-intents/intents/create.md?api-version=preview) を作成できます。

デフォルトでは、顧客が保存した決済方法に自動的に請求されます。請求書を送るには、`collection_method` を `send_invoice` にして[回収設定](https://docs.stripe.com/api/v2/billing-settings/collection-settings/create.md?api-version=preview)を作成します。それからそのケイデンスを作成する際に集金設定を渡してください。

## 顧客の使用状況を記録する

顧客をレートカードで構成される料金プランに登録した後は、従量制イベントを送信し、顧客のサービス利用状況を記録します。

#### ダッシュボード

1. [料金プランのサブスクリプション](https://dashboard.stripe.com/test/pricing-plans/subscriptions)タブに移動します。
1. 使用量を記録するサブスクリプションをクリックします。
1. **表示**を選択して基本料金プランコンポーネントを表示し、使用状況を追加するレートカードに移動します。
1. 使用量を記録する項目の行にあるオーバーフローメニュー (⋯) をクリックし、**メーターの詳細を表示**をクリックします。
1. メーターの詳細ページで、**+ 使用量を追加**をクリックし、**使用量を手動で入力**を選択します。
1. **使用量の追加**ダイアログで、次の操作を行います。
   - 顧客を選択します。
   - 使用量の**値**を入力します。
   - **タイムスタンプ**の日付を選択します。
1. **送信**をクリックします。

#### API

[メーターイベントを](https://docs.stripe.com/api/billing/meter-event.md)使用して、メーターの[顧客使用量](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage.md)を記録します。請求期間の終了時に、Stripe は報告された使用量を請求します。

従量課金をテストするには、Stripe ダッシュボードまたは API を使用してメーターイベントを送信します。API を使用するときは、`payload` 内で顧客 ID と使用状況の値を指定します。料金プラン導入テストの詳細は[こちら](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#test-the-integration)でご確認ください。

```curl
curl https://api.stripe.com/v1/billing/meter_events \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d event_name=hypernian_tokens \
  -d "payload[stripe_customer_id]={{CUSTOMER_ID}}" \
  -d "payload[value]=25"
```

## 請求書プレビューを作成する

プレビュー請求書を作成して、顧客の請求書のプレビューを確認します。プレビューには、さまざまな料金プランのコンポーネントに対応する該当の明細項目が含まれます。

#### ダッシュボード

1. [料金プランのサブスクリプション](https://dashboard.stripe.com/test/pricing-plan/subscriptions)タブに移動します。
1. 請求書をプレビューするサブスクリプションをクリックします。
1. 下にスクロールして**次回の請求書**セクションを確認します。プレビュー請求書には、指定された日に顧客に請求されるサブスクリプション金額が表示され、対応するメーター項目、ライセンス項目、クレジットが反映されています。

#### API

```curl
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2025-12-15.clover" \
  -d billing_cadence=bc_test_61SrjnScUwT6mNskZ16SjPfE4ZSQFjWjdqlzQfWMCVnM
```

```json
{"hosted_invoice_url": "example.com/invoice",
  "invoice_pdf": null,
  "billing_reason": "manual",
  "collection_method": "charge_automatically",
  "created": 1680644467,
  "currency": "usd",
  "custom_fields": null,
  "customer": "cus_NeZwdNtLEOXuvB",
  "customer_address": null,
  "customer_email": "jennyrosen@example.com",
  "customer_name": "Jenny Rosen",
  "customer_phone": null,
  "customer_shipping": null,
  "customer_tax_exempt": "none",
  "customer_tax_ids": [],
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "due_date": null,
  "ending_balance": null,
  "footer": null,
  "from_invoice": null,
  "last_finalization_error": null,
  "latest_revision": null,
  "lines": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines"
  },
  "id": "upcoming_in_1MtHbELkdIwHu7ixl4OzzPMv",
  "object": "invoice",
  "account_country": "US",
  "account_name": "Stripe Docs",
  "account_tax_ids": null,
  "amount_due": 0,
  "amount_paid": 0,
  "amount_overpaid": 0,
  "amount_remaining": 0,
  "amount_shipping": 0,
  "application": null,
  "application_fee_amount": null,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "automatic_tax": {
    "enabled": false,
    "status": null
  },
  "livemode": false,
  "metadata": {},
  "next_payment_attempt": null,
  "number": null,
  "on_behalf_of": null,
  "parent": null,
  "payment_settings": {
    "default_mandate": null,
    "payment_method_options": null,
    "payment_method_types": null
  },
  "period_end": 1680644467,
  "period_start": 1680644467,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "receipt_number": null,
  "shipping_cost": null,
  "shipping_details": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "status": "draft",
  "status_transitions": {
    "finalized_at": null,
    "marked_uncollectible_at": null,
    "paid_at": null,
    "voided_at": null
  },
  "subtotal": 0,
  "subtotal_excluding_tax": 0,
  "test_clock": null,
  "total": 0,
  "total_discount_amounts": [],
  "total_excluding_tax": 0,
  "total_taxes": [],
  "webhooks_delivered_at": 1680644467
}
```

## サービスイベントを監視する

料金プランサブスクリプションは、サービスと回収の状態が変わるたびにイベント通知を送信します。

これらのイベントをリッスンし、それらを使用してビジネスロジックを構築します。

| イベント                                                                       | 説明                                                                                |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `v2.billing.pricing_plan_subscription.servicing_activated`                 | サブスクリプションのサービスがアクティブになったとき、最初のサービス期間が開始されたとき、または一時停止していたサブスクリプションが再開されたときに送信されます。 |
| `v2.billing.pricing_plan_subscription.servicing_paused`                    | Stripe がサブスクリプションのサービスを一時停止したときに送信されます。                                           |
| `v2.billing.pricing_plan_subscription.servicing_canceled`                  | 顧客または Stripe によってサブスクリプションのサービスがキャンセルされた場合に送信されます。                                |
| `v2.billing.pricing_plan_subscription.collection_current`                  | サブスクリプションの決済回収が最新の状態になり、すべての決済が処理されたときに送信されます。                                    |
| `v2.billing.pricing_plan_subscription.collection_awaiting_customer_action` | 決済回収で顧客アクション (3DS 認証など) が必要な場合に送信されます。                                            |
| `v2.billing.pricing_plan_subscription.collection_paused`                   | Stripe がサブスクリプションの決済回収を一時停止したときに送信されます。                                           |

これらの [v2 イベント](https://docs.stripe.com/api/v2/core/events.md?api-version=preview)を処理するには、[Event Destination](https://docs.stripe.com/api/v2/core/event_destinations.md?api-version=preview) を設定し、Webhook エンドポイントを指定します。次のいずれかを実行できます。

- [Workbench](https://docs.stripe.com/workbench/event-destinations.md) で Event Destination を作成します。
- [Stripe API を使用](https://docs.stripe.com/api/v2/core/event_destinations.md?api-version=preview)してイベント送信先を作成します。

送信先を作成したら、次のイベントを処理するように Webhook エンドポイントを設定します。

```ruby
require 'stripe'

post '/v2_webhook_endpoint' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    status 400
    return
  end

  client = Stripe::StripeClient.new("<<YOUR_SECRET_KEY>>")

  case event.type
  when 'v2.billing.pricing_plan_subscription.servicing_activated'
    # Servicing becomes active, either when the first service period starts
    # or when a paused subscription resumes.
    subscription_id = event.related_object.id
    subscription = client.v2.billing.pricing_plan_subscriptions
      .retrieve(subscription_id)

    # Look up your user in the database using the metadata passed into
    # Checkout Session create
    user_id = subscription.metadata["my_user_id"]
    user = User.find_by_id(user_id)

    # Fill in your logic here:
    mark_subscription_active(user, subscription)
  when 'v2.billing.pricing_plan_subscription.servicing_paused'
    # Stripe pauses the subscription's servicing.
    subscription_id = event.related_object.id
    subscription = client.v2.billing.pricing_plan_subscriptions
      .retrieve(subscription_id)

    # Look up your user in the database using the metadata passed into
    # Checkout Session create
    user_id = subscription.metadata["my_user_id"]
    user = User.find_by_id(user_id)

    # Fill in your logic here:
    mark_subscription_paused(user, subscription)
  when 'v2.billing.pricing_plan_subscription.servicing_canceled'
    # Servicing is canceled, either by the customer or by Stripe.
    subscription_id = event.related_object.id
    subscription = client.v2.billing.pricing_plan_subscriptions
      .retrieve(subscription_id)

    # Look up your user in the database using the metadata passed into
    # Checkout Session create
    user_id = subscription.metadata["my_user_id"]
    user = User.find_by_id(user_id)

    # Fill in your logic here:
    mark_subscription_canceled(user, subscription)
  end

  status 200
end
```

## 組み込みをテストする

以下の手順に従って、実装をテストします。

- [サンドボックスを作成する](https://docs.stripe.com/sandboxes/dashboard/manage.md#create-a-sandbox)を参照してください。
- サンドボックスに、テスト用の料金プランと少なくとも 1 つの基礎となる料金構成要素を作成してください。
- [テストカード](https://docs.stripe.com/testing.md)を使用して、成功した支払いと失敗した支払いをシミュレートします。
- 使用状況をシミュレーションする[テストメーターイベント](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#create-meter)を作成します。
- [Simulations](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md) を使用して請求処理をシミュレーションします。

> #### 過去の時点にテストクロックを作成しない
> 
> 料金プランのサブスクリプション用にテストクロックを作成する場合は、必ず未来の日付でクロックを作成してください。過去の日付でクロックを作成すると、請求金額が正しく表示されません。

UNIX タイムスタンプでテストクロックを作成します。

```curl
curl https://api.stripe.com/v1/test_helpers/test_clocks \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d frozen_time=1577836800
```

テストクロックの ID をメモします。次に、クロックを使用してテスト顧客を作成します。

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "email=test@example.com" \
  -d test_clock={{TEST_CLOCK_ID}}
```

請求プロファイルの作成

```curl
curl -X POST https://api.stripe.com/v2/billing/profiles \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "customer": "{{CUSTOMER_ID}}"
  }'
```

請求期間を作成して、顧客に請求書を発行するタイミングを定義します。ID を保存します。

```curl
curl -X POST https://api.stripe.com/v2/billing/cadences \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "payer": {
        "billing_profile": "{{BILLING_PROFILE_ID}}"
    },
    "billing_cycle": {
        "type": "month",
        "interval_count": 3
    },
    "settings": {
        "collection": {
            "id": "{{COLLECTION_SETTINGS_ID}}"
        }
    }
  }'
```

テスト顧客の[料金プランサブスクリプション](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-plans.md#subscribe)を作成します。

[請求インテント](https://docs.stripe.com/api/v2/billing-intents/intents/create.md?api-version=preview)を作成し、料金プランサブスクリプションのステータスを追跡します。まず、請求インテントのドラフトを作成します。インテントの ID を保存してください

```curl
curl -X POST https://api.stripe.com/v2/billing/intents \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "currency": "usd",
    "cadence": "{{CADENCE_ID}}",
    "actions": [
        {
            "type": "subscribe",
            "subscribe": {
                "type": "pricing_plan_subscription_details",
                "pricing_plan_subscription_details": {
                    "pricing_plan": "{{PRICING_PLAN_ID}}",
                    "pricing_plan_version": "{{PRICING_PLAN_VERSION}}"
                }
            }
        }
    ]
  }'
```

次に、請求インテントを予約します。

```curl
curl -X POST https://api.stripe.com/v2/billing/intents/{{BILLING_INTENT_ID}}/reserve \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview"
```

次に、その請求インテントを確定して料金プランのサブスクリプションを有効にし、プランと請求頻度に従って顧客に請求を行います(コレクション設定を `automatic` に設定している場合、インテントを確定するには成功した [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) が必要です。コレクション設定を `send_invoice` に設定している場合は、Payment Intent を渡す必要はありません)。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1000 \
  -d currency=usd \
  -d customer={{CUSTOMER_ID}} \
  -d payment_method=pm_card_visa \
  -d "return_url=example.com" \
  -d confirm=true
```

テスト用に、`payment_method` を「pm_card_visa」に設定してみましょう。

```curl
curl -X POST https://api.stripe.com/v2/billing/intents/{{BILLING_INTENT_ID}}/commit \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "payment_intent": "{{PAYMENT_INTENT_ID}}"
  }'
```

サブスクリプションによって生成された請求書を支払います。請求書の支払い後、使用量をシミュレートしてクロックを進めると、翌月の請求がトリガーされます。Checkout を使用している場合は、返された Checkout セッションの `url` をブラウザーで開き、[テストカード](https://docs.stripe.com/testing.md#use-test-cards)を使用して支払いを完了します。

テスト用の使用量を記録します。

```curl
curl -X POST https://api.stripe.com/v2/billing/meter_events \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "event_name": "hypernian_tokens",
    "payload": {
        "stripe_customer_id": "{{CUSTOMER_ID}}",
        "value": "100"
    }
  }'
```

テストクロックの凍結時間を 1 か月進めます。この例では、テストクロックの現在のタイムスタンプは `1577836800` です。月を追加するには、`30 * 24 * 60 * 60`、または `2592000` 秒を追加します。今から 1 か月後の新しいタイムスタンプは `1580428800` です。

```curl
curl https://api.stripe.com/v1/test_helpers/test_clocks/{{TEST_CLOCK_ID}}/advance \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d frozen_time=1580428800
```

## Optional: 税金を徴収する

税金を自動的に徴収するには、[checkout_items](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-checkout_items) を含む [Checkout セッションを作成](https://docs.stripe.com/api/checkout/sessions/create.md)し、`automatic_tax.enabled` を true に設定します。

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2025-09-30.preview;checkout_product_catalog_preview=v1" \
  -d customer={{CUSTOMER_ID}} \
  -d "checkout_items[0][type]=pricing_plan_subscription_item" \
  -d "checkout_items[0][pricing_plan_subscription_item][pricing_plan]={{PRICING_PLAN_ID}}" \
  -d success_url={{SUCCESS_URL}} \
  -d "automatic_tax[enabled]=true"
```

このページには料金プランの詳細が表示され、顧客の支払い情報が収集されます。顧客はセッションを完了すると、`success_url`に指定された URL にリダイレクトされます。

## Optional: カスタマーポータルを設定します

[カスタマーポータル](https://docs.stripe.com/customer-management/activate-no-code-customer-portal.md) を設定することで、顧客にセルフサービス機能を提供できます。

現在、カスタマーポータルを料金プランのサブスクリプションで使用することは読み取り専用です。顧客は、料金プランの請求サブスクリプションのキャンセル、プランの変更、決済手段の更新を行うことはできません。現時点では、ダッシュボードからのみカスタマーポータルセッションを設定できます。

料金プランのサブスクリプションでカスタマーポータルを使用すると、顧客は以下を確認できます。

- サブスクリプションプラン (提供しているハイブリッドプランの詳細を含む)。
- 月末に請求される金額を把握するのに役立つ次回の請求書。
- 対象のサブスクリプションに登録されている決済手段。
- 請求された過去の請求書。
- 請求情報。