# メーターを作成して設定

従量課金のメーターを作成および設定します。

[顧客の使用状況](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage.md) を記録する前に、メーターを作成してから設定する必要があります。メーターの設定後は、表示名を除き変更することができなくなります。

## メーターを作成する

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

Hypernian の例では、メーターイベントは、顧客がクエリで使用するトークンの数です。メーターは、1 か月間のトークンの合計です。

Stripe ダッシュボードまたは API を使用してメーターを設定できます。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_tokens」と入力します。
   - ドロップダウンで **集計方法** を設定します。
     - Hypernian の例では、 **合計** を選択します。これにより、報告れた *値が合計* され (この例では、顧客が使用するトークンの数)、請求する使用量が決定されます。
     - 報告されたイベントの_数_に基づいて **カウント** を選択し、請求します。
     - **最終** を選択して、報告された_最終値_に基づいて請求します。
     - プレビューペインを使用して、使用状況例イベントを設定し、集計方法を確認します。
   - **メーターを作成** をクリックします。
   - (オプション) **詳細設定** で、使用状況データにタグ付けする **ディメンション** を指定します。セグメント固有のアラートをきめ細かく生成したり、属性の組み合わせに基づいて使用状況を細かく価格設定したりするには、分析とレポート作成用に入力されたディメンションを使用して使用状況データを送信します。ディメンションの例としては、LLM モデル、トークンタイプ、地域、イベントタイプなどがあります。

#### API

```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
```

## メーター設定属性

| メーター属性      | 説明                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| イベント名       | メーターを使用して使用状況を記録することを予定しているメーターイベントの名前。使用量を Stripe に送信する際、[メーターイベント](https://docs.stripe.com/api/billing/meter-event/object.md) の `event_name` フィールドでこのイベント名が使用されます。これにより、正しいメーターを記録して使用量を集計することができます。イベント名は特定の 1 つのメーターでのみ使用できます。                                                                                                                                      |
| イベントの取り込み   | Stripe にイベントを送信する方法を指定します。

  - **未加工**: すべてのメーターイベントをスタンドアロンのイベントとして処理します。同じタイムスタンプで送信された複数のイベントは、互いに上書きされず、集計には複数のイベントが含まれます。これは、何も指定しなかった場合のデフォルトのオプションです。
  - **事前集計**: 特定の頻度 (毎時または毎日) でイベントを送信している場合、Stripe はその時間枠内で最近受信したメーターイベントのみを使用します。同じ毎時または毎日の時間枠内で送信される新しいイベントによって以前のイベントは上書きされます。UTC のメーターイベントのタイムスタンプで、時間と日の区切りが指定されます。                                 |
| 集計式         | 請求期間の使用量の集計方法を指定します。

  - **合計**: 請求期間中のすべての使用量の合計値に基づいて顧客に請求します。
  - **件数**: 請求期間中のすべての使用量の件数に基づいて顧客に請求します。
  - **最終**: 請求期間における最新の使用状況イベントの値に基づいて、顧客に請求します。                                                                                                                                                                                                           |
| ペイロードキーの上書き | イベントペイロードのどのキーが顧客と使用量の数値を表すかを指定します。

  - **value\_settings**: このパラメーターを使用して、使用量の数値を参照するイベントペイロード内のキーを定義します。デフォルトのキーは `value` ですが、トークンなど別のキーも指定できます。
  - **customer\_mapping**: このパラメーターを使用して、[Customer ID](https://docs.stripe.com/api/customers/object.md#customer_object-id) を参照するイベントペイロード内のキーを定義します。デフォルトのキーは `stripe_customer_id` ですが、`customer_id` など別のキーも指定できます。 |

## 使用量データの誤りを修正する

現在の請求期間に誤って記録されたイベントを特定した場合は、[メーターイベント調整](https://docs.stripe.com/api/billing/meter-event-adjustment/create.md) を作成して、それらのイベントをキャンセルできます。メーターイベントの [識別子](https://docs.stripe.com/api/billing/meter-event/object.md#billing_meter_event_object-identifier) を指定する必要があります。

過去 24 時間以内に Stripe に送信されたイベントのみキャンセルできます。確定済みの請求書に含まれている使用量をキャンセルしても、Stripe はその請求書を更新せず、キャンセルされた使用量を対象とする修正請求書も発行しません。また、顧客に送信された確定済みの請求書におけるキャンセルされた使用量の請求調整には対応していません。

数量をマイナスで記録して、誤って記録した使用量データを修正することもできます。サイクル全体の使用量がマイナスの場合、Stripe では請求書の項目の使用数量を 0 として報告します。

```curl
curl https://api.stripe.com/v1/billing/meter_event_adjustments \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d type=cancel \
  -d event_name=hypernian_tokens \
  -d "cancel[identifier]"={{METER_EVENT_IDENTIFIER}}
```