# Create a billing meter

Creates a billing meter.

## Request

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

### Response

```json
{
  "id": "mtr_123",
  "object": "billing.meter",
  "created": 1704824589,
  "customer_mapping": {
    "type": "by_id",
    "event_payload_key": "stripe_customer_id"
  },
  "default_aggregation": {
    "formula": "sum"
  },
  "display_name": "Search API Calls",
  "event_name": "ai_search_api",
  "event_time_window": null,
  "livemode": false,
  "status": "active",
  "status_transitions": {
    "deactivated_at": null
  },
  "updated": 1704824589,
  "value_settings": {
    "event_payload_key": "value"
  }
}
```

## Returns

Returns a billing meter.

## Parameters

- [`default_aggregation`](https://docs.stripe.com/api/billing/meter/create.md?query=default_aggregation) (object, required)
  The default settings to aggregate a meter’s events with.

- `display_name` (string, required)
  The meter’s name. Not visible to the customer.

- `event_name` (string, required)
  The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events.

- [`customer_mapping`](https://docs.stripe.com/api/billing/meter/create.md?query=customer_mapping) (object, optional)
  Fields that specify how to map a meter event to a customer.

- `event_time_window` (enum, optional)
  The time window to pre-aggregate meter events for, if any.
Possible enum values:
  - `day`
    Events are pre-aggregated in daily buckets.

  - `hour`
    Events are pre-aggregated in hourly buckets.

- [`value_settings`](https://docs.stripe.com/api/billing/meter/create.md?query=value_settings) (object, optional)
  Fields that specify how to calculate a meter event’s value.