# クレジットベースの料金体系モデルを設定する

事前購入クレジットのチャージを顧客に請求します。

クレジットを使用すると、従量制の製品全体で固定の金額の使用量を提供できます。このモデルは、使用量に収益を直接合わせながら、事前に予測可能な金額を顧客に提供したい場合に適しています。たとえば、画像とクラウドストレージを処理する API を販売している場合、顧客は月の初めにクレジットの 100 USD を購入できます。API 使用量とクラウドストレージの任意の組み合わせを、その金額まで支出でき、使用量の 100 USD を超えた場合は、月末にいずれかのサービスに対して超過料金を支払います。

クレジットはメーターごとに無差別に適用されます。従量制のさまざまな製品 (100 API リクエスト、3GB のストレージなど) に特定の制限を設定するには、[定額手数料と超過](https://docs.stripe.com/billing/subscriptions/usage-based-v1/use-cases/flat-fee-and-overages.md) 料金モデルを使用します。

## 作成する内容

本ガイドでは、LLM を提供する Hypernian という架空の会社の次のサブスクリプションを構築します。顧客には次の料金が請求されます。

| クレジット  | 手数料    |
| ------ | ------ |
| ユーザーごと | 10 USD |

| 使用状況   | 手数料              |
| ------ | ---------------- |
| 入力トークン | トークンあたり 0.03 USD |
| 出力トークン | トークンあたり 0.05 USD |

## メーターを作成する

メーターは、請求期間中のメーターイベントの集計方法を指定します。メーターイベントは、顧客がシステムで実行するすべてのアクション (API リクエストなど) を表します。メーターは、価格に関連付けられ、請求内容の基礎となります。

Hypernian の例では、メーターイベントは、顧客がクエリで使用する入力トークンと出力トークンの数です。メーターは、1か月間のトークンの合計です。この例では。トークンタイプごとにメーターを作成します。

Stripe ダッシュボードまたは API を使用して[メーターを設定](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure.md)できます。Stripe CLI で API を使用してメーターを作成するには、[Stripe CLI を始める](https://docs.stripe.com/stripe-cli.md) を参照してください。

#### ダッシュボード

1. [メーター](https://dashboard.stripe.com/test/meters) ページで、**メーターを作成** をクリックします。
1. **メーターを作成** ページで、以下を実行します。
   - **メーター名** に、表示するメーターの名前と整理目的で入力します。Hypernian の例には、「Hypernian 入力トークン」と入力します。
   - **イベント名** に、Stripe に使用状況を報告するときにメーターイベントに表示する名前を入力します。Hypernian の例には、「hypernian_input_tokens」と入力します。
   - ドロップダウンで **集計方法** を設定します。
     - Hypernian の例では、 **合計** を選択します。これにより、報告れた *値が合計* され (この例では、顧客が使用するトークンの数)、請求する使用量が決定されます。
     - 報告されたイベントの_数_に基づいて **カウント** を選択し、請求します。
     - **最終** を選択して、報告された_最終値_に基づいて請求します。
     - プレビューペインを使用して、使用状況例イベントを設定し、集計方法を確認します。
   - **メーターを作成** をクリックします。
   - 出力トークンのメーターを作成するには、前の手順を繰り返し、メーター名を「Hypernian Output Tokens」に設定し、イベント名を「hypernian_output_tokens」に設定します。
   - (オプション) **詳細設定** で、使用状況データにタグ付けする **ディメンション** を指定します。セグメント固有のアラートをきめ細かく生成したり、属性の組み合わせに基づいて使用状況を細かく価格設定したりするには、分析とレポート作成用に入力されたディメンションを使用して使用状況データを送信します。ディメンションの例としては、LLM モデル、トークンタイプ、地域、イベントタイプなどがあります。

#### API

```curl
curl https://api.stripe.com/v1/billing/meters \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "display_name=Hypernian Input tokens" \
  -d event_name=hypernian_input_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"
```

出力トークンのメーターを作成するには、以下の値を指定して前のステップを繰り返します。

```curl
curl https://api.stripe.com/v1/billing/meters \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "display_name=Hypernian Output tokens" \
  -d event_name=hypernian_output_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"
```

## 料金体系モデルを作成する

Stripe ダッシュボードまたは API を使用して、[商品](https://docs.stripe.com/api/products.md) とその料金オプションを含む [料金体系モデル](https://docs.stripe.com/products-prices/pricing-models.md) を作成します。[価格](https://docs.stripe.com/api/prices.md) は、単価、通貨、請求期間を定義します。

Hypernian の例では、それぞれ月単位での従量課金ベースの 2 つの製品を作成します。前の手順で作成したメーターを使用します。

#### ダッシュボード

1. [商品カタログ](https://dashboard.stripe.com/products?active=true) ページで、**商品を作成** をクリックします。
1. **商品を追加** ページで、以下を実行します。
   - **名前** に、製品の名前を入力します。Hypernian の例には、`Hypernian` と入力します。
   - (オプション) **説明** には、[Checkout](https://docs.stripe.com/payments/checkout.md)、[カスタマーポータル](https://docs.stripe.com/customer-management.md)、[見積もり](https://docs.stripe.com/quotes.md) に表示する説明を追加します。
   - **継続** を選択します。
   - **請求期間** で、**その他の料金体系オプション** を選択します。
1. **価格を追加** ページで、以下を実行します。
   - **料金体系モデルを選択** で、**従量制** を選択します。
   - 料金体系を選択:
     - Hypernian の例では、 **単位ごと** を選択します。**価格** で、 **金額** を `0.03 USD`。
     - **メーター** で、作成したメーターを選択し、ドロップダウンから Hypernian 入力トークンを選択します。
     - **請求期間** で、**月次** を選択します。
   - **メーター** で、作成したメーターを選択します。Hypernian の例では、ドロップダウンから **Hypernian 入力トークン** を選択します。
   - 適切な **請求期間** を選択します。Hypernian の例では、 **月次** を選択します。
   - **次へ** をクリックします。
1. 前の手順を繰り返して、価格が `0.05 USD` の「Hypernian output usage」という製品を作成します。同じ月次請求期間で **Hypernian output token meter** に添付します。

#### API

入力使用状況の段階制料金の商品と価格を作成します。

```curl
curl https://api.stripe.com/v1/products \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "description=Input usage fee for Hypernian" \
  -d "name=Hypernian Input Usage"
```

```curl
curl https://api.stripe.com/v1/prices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "product={{PRODUCT_ID}}" \
  -d currency=usd \
  -d billing_scheme=per_unit \
  -d "recurring[interval]=month" \
  -d "recurring[interval_count]=1" \
  -d "recurring[usage_type]=metered" \
  -d "recurring[meter]={{METER_ID}}" \
  -d unit_amount_decimal=3
```

出力使用状況の段階制料金の商品と価格を作成します。

```curl
curl https://api.stripe.com/v1/products \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "description=Ouput usage fee for Hypernian" \
  -d "name=Hypernian Output Usage"
```

```curl
curl https://api.stripe.com/v1/prices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "product={{PRODUCT_ID}}" \
  -d currency=usd \
  -d billing_scheme=per_unit \
  -d "recurring[interval]=month" \
  -d "recurring[interval_count]=1" \
  -d "recurring[usage_type]=metered" \
  -d "recurring[meter]={{METER_ID}}" \
  -d unit_amount_decimal=5
```

## 顧客を作成する

導入で [customer-configured Accounts](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) を使用している場合は、コード例内の `Customer` とイベント参照を、対応する Accounts v2 API リファレンスに置き換えてください。詳細については、[Account オブジェクトで顧客を表す](https://docs.stripe.com/connect/use-accounts-as-customers.md)をご覧ください。

次に、*顧客* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) を作成します。

#### ダッシュボード

1. [顧客](https://dashboard.stripe.com/test/customers) ページで、**顧客を追加** をクリックします。
1. **顧客を作成** ページで、以下を実行します。
   - **名前** に、顧客の名前を入力します。Hypernian の例には、`Jenny Rosen` と入力します。
   - (オプション) 顧客のメールアドレスと説明を追加します。
   - **顧客を追加** をクリックします。

#### API

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "name=Jenny Rosen"
```

## 顧客に請求クレジットを付与する

Stripe ダッシュボードまたは API を使用して、顧客のクレジット付与を作成します。

> #### クレジットは請求期間の終了時に消費されます。
> 
> このバージョンの従量課金では、請求期間の終了時に請求書が作成されるとクレジットが消費されます。現在プライベートプレビューで提供されている [高度な従量課金](https://docs.stripe.com/billing/subscriptions/usage-based/advanced/compare.md) を使用すると、リアルタイムで消費されるクレジット付与を設定できます。プライベートプレビューに [登録](mailto:advanced-ubb-private-preview@stripe.com) して、詳細をご覧ください。

請求クレジットは、[メーター価格](https://docs.stripe.com/api/prices/object.md#price_object-recurring-meter)にリンクする [サブスクリプション](https://docs.stripe.com/api/invoices/object.md#invoice_object-subscription) の項目にのみ適用されます。[使用状況レコード API](https://docs.stripe.com/api/usage_records.md) はサポートされません。

#### ダッシュボード

1. [顧客](https://dashboard.stripe.com/test/customers) ページで、顧客名を選択します。
1. 顧客ページの **クレジット付与** でプラス (**+**) 記号をクリックします。
1. **新しいクレジット付与** ページで、以下を実行します。

- **名前** には、クレジット付与の名前を入力します。
- **金額** に、クレジット付与の金額を指定します。Hypernian の例には、10 と入力します。
- (オプション) **発効日** で、クレジットを付与する日付を指定します。
- (オプション) **有効期限** で、クレジットの有効期限が切れる日付 (ある場合) を指定します。
- (オプション) **優先度** で、このクレジット付与の優先度を指定します。
- (オプション) **利用資格** で、このクレジット付与が適用される従量制価格のリストを指定します。
- **クレジット付与を作成** をクリックします。

#### API

```curl
curl https://api.stripe.com/v1/billing/credit_grants \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -d "name=Credit grant" \
  -d "applicability_config[scope][price_type]=metered" \
  -d category=paid \
  -d "amount[type]=monetary" \
  -d "amount[monetary][value]=1000" \
  -d "amount[monetary][currency]=usd"
```

## サブスクリプションを作成する

[サブスクリプション](https://docs.stripe.com/api/subscriptions.md) を使用すると、顧客を特定の価格に関連付けて、継続的な金額を請求することができます。

Stripe ダッシュボードまたは API を使用して、顧客、商品、従量制価格を含むサブスクリプションを作成します。

Hypernian の例では、Hypernian 入力トークン製品と Hypernian 出力トークン製品の両方のサブスクリプションを作成し、Jenny Rosen に毎月請求します。

> 1 つの従量制料金を複数のサブスクリプションに関連付けることができます。
> 
> `billing_mode=flexible` サブスクリプションを作成すると、従量制の項目は最初の請求書から除外されます。これは、請求書に以前の使用状況がないためです。Stripe は、サブスクリプションが以前に発生した使用状況で遡及されている場合、または保留中の請求書項目が存在する場合にのみ請求書を作成します。`billing_mode=classic` サブスクリプションを作成すると、Stripe は従量制サブスクリプション項目ごとにゼロの金額の請求書の項目を生成します。

#### ダッシュボード

1. [サブスクリプション](https://dashboard.stripe.com/test/subscriptions) ページで、**テストサブスクリプションを作成** をクリックします。
1. **テスト用サブスクリプションを作成** ページで、以下を実行します。
   - **顧客**で顧客の名前を選択します。Hypernian の例では、**Jenny Rosen** を選択します。
   - **商品** で、価格を選択します。Hypernian の例では、 **Hypernian 入力使用量** と **Hypernian 出力使用量** で価格を選択します。
   - (オプション) 必要に応じて、サブスクリプションの詳細と設定を変更します。
   - **テスト用サブスクリプションを作成** をクリックします。

#### API

顧客の詳細ページで顧客 ID を確認できます。価格 ID を確認するには、各商品の詳細ページに移動して、**価格**のオーバーフローメニュー (⋯) をクリックします。**価格 ID をコピー**を選択します。

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -d "items[0][price]={{INPUT_PRICE_ID}}" \
  -d "items[1][price]={{OUTPUT_PRICE_ID}}"
```

## テストのメーターイベントを送信

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

Stripe ダッシュボードまたは API を使用して、メーターイベントを送信し、従量課金をテストできます。API を使用する場合は、顧客 ID と `payload` の値を指定します。

メーターイベントを送信した後、ダッシュボードの [メーター](https://dashboard.stripe.com/test/meters) ページでメーターに関する使用状況の詳細を確認できます。

#### ダッシュボード

1. [メーター](https://dashboard.stripe.com/test/meters) ページで、メーター名を選択します。Hypernian の例では、 **Hypernian 入力トークン** を選択します。
1. メーターページで、**使用量を追加** > **使用量を手動で入力** をクリックします。
1. **使用量を追加** ページで、以下を実行します。
   - **Customer** ドロップダウンから、対象の顧客を選択します。
   - **値** に、サンプル値を入力します。Hypernian の例には、`3000` と入力します。
   - **送信** をクリックします。

#### API

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

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

[プレビュー請求書を作成](https://docs.stripe.com/api/invoices/create_preview.md) して、メーター価格や使用量などの詳細を含む顧客の請求書のプレビューを表示します。

#### ダッシュボード

1. [サブスクリプション](https://dashboard.stripe.com/test/subscriptions) ページで、サブスクリプションを選択します。Hypernian の例では、 **Jenny Rosen** のサブスクリプションを選択します。

1. サブスクリプションの詳細ページで、**次回の請求書** セクションまで下にスクロールします。プレビューの請求書には、指定した日付に顧客に請求するサブスクリプションの金額が表示されます。

1. **すべての請求書を表示** をクリックすると、次のような請求書の詳細を確認できます。

   - 顧客
   - 請求方法
   - 作成日
   - 関連付けられたサブスクリプション
   - サブスクリプションの詳細 (使用量とメーター価格)
   - 請求金額

   Stripe はメーターイベントを非同期に処理するため、以降の請求書には、最近受信したメーターイベントが即時に反映されない可能性があります。

#### API

```curl
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "subscription={{SUBSCRIPTION_ID}}"
```

## 請求クレジットを請求書に適用する

請求書が確定すると、Stripe は該当するすべての請求クレジットを自動的に適用します。クレジット付与の利用可能な残高は、請求書に適用された請求クレジットの金額に基づいて更新されます。

請求書に適用される請求クレジットの金額は、Stripe ダッシュボードで確認できます。

1. [顧客](https://dashboard.stripe.com/test/customers) ページで、顧客名を選択します。
1. 顧客ページの **請求書** で、請求書を選択します。
1. 請求書ページの **小計** で、**適用されたクレジット付与** の項目を探します。

## 利用可能な請求クレジット残高を取得する

Stripe ダッシュボードまたは API を使用して、顧客の利用可能な請求クレジット残高を確認します。API を使用する場合は、[クレジット残高サマリー](https://docs.stripe.com/api/billing/credit-balance-summary/retrieve.md) エンドポイントを取得します。

#### ダッシュボード

1. [顧客](https://dashboard.stripe.com/test/customers) ページで、顧客名を選択します。
1. 顧客ページの **クレジット付与** で、請求書に適用できるクレジット付与のリストを見つけます。クレジット付与の [available_balance](https://docs.stripe.com/api/billing/credit-balance-summary/object.md#billing_credit_balance_summary_object-balances-available_balance) は、**利用可能** 列で確認できます。

#### API

```curl
curl -G https://api.stripe.com/v1/billing/credit_balance_summary \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -d "filter[type]=applicability_scope" \
  -d "filter[applicability_scope][price_type]=metered"
```

## クレジット付与の取引を一覧表示する

Stripe ダッシュボードまたは API を使用して、特定のクレジット付与または顧客の取引を確認します。API を使用する場合は、[クレジット残高取引](https://docs.stripe.com/api/billing/credit-balance-transaction/list.md) エンドポイントを呼び出します。

#### ダッシュボード

1. [顧客](https://dashboard.stripe.com/test/customers) ページで、顧客名を選択します。
1. 顧客ページの **クレジット付与** で、クレジット付与を選択します。
1. クレジット取引残高の詳細を表示する。

#### API

```curl
curl -G https://api.stripe.com/v1/billing/credit_balance_transactions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -d credit_grant={{CREDIT_GRANT_ID}}
```

## Optional: クレジット付与に資金を追加する

Stripe ダッシュボードまたは API を使用して、顧客から決済を徴収する 1 回限りの [請求書](https://docs.stripe.com/invoicing.md) を作成します。API を使用するときは、`invoice.paid` [webhook](https://docs.stripe.com/webhooks.md) をリッスンし、顧客に請求クレジットを付与します。

#### ダッシュボード

1. [顧客](https://dashboard.stripe.com/test/customers) ページで、顧客名を選択します。
1. 顧客ページで、**請求書を作成** をクリックします。
1. 指示に従って[請求書を作成](https://docs.stripe.com/invoicing/dashboard.md)します。

#### API

```curl
curl https://api.stripe.com/v1/invoices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -d "description=credit purchase" \
  -d collection_method=charge_automatically
```

```curl
curl https://api.stripe.com/v1/invoiceitems \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -d "description=billing credits purchase" \
  -d unit_amount_decimal=1000 \
  -d currency=usd \
  -d invoice={{INVOICE_ID}}
```

```curl
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/finalize \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d auto_advance=true
```

## Optional: カスタム期間の使用量を取得

[メーターイベントサマリー](https://docs.stripe.com/api/billing/meter-event-summary.md) を使用して、カスタム期間の合計使用状況を取得します。メーターイベントのサマリーは、メーターによって定義される集計式を基に、期間中の顧客の使用状況を集計して返します。

Hypernian の例では、メーターイベントの概要は、特定の顧客、メーター、および時間枠のトークンの合計を返します。

Stripe はメーターイベントを非同期に処理するため、メーターイベントサマリーには、最近受信したメーターイベントが即時に反映されない可能性があります。

```curl
curl -G https://api.stripe.com/v1/billing/meters/{{METER_ID}}/event_summaries \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -d start_time=1717249380 \
  -d end_time=1717249440
```