# Meters

:::note{title="Beta"}

API Monetization is in beta and free to try. The APIs are stable but should be
evaluated in non-production environments first. To go to production, contact
[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
announced.

:::

Meters aggregate usage data from your API. They watch for specific event types,
extract numeric values, and sum them over configurable time windows.

## How Meters Work

A meter is configured with:

- **Event type** - Which events to process (e.g., `requests`, `tokens`)
- **Value property** - JSONPath to extract the numeric value from event data.
  Events use `$.total` as the standard value property.
- **Aggregation** - How to combine values (typically `SUM`)

When events are ingested, the meter matches events by type, extracts the
specified value, and aggregates it per customer over time.

## Common Examples

### API Request Counting

Track the total number of API requests:

```json
{
  "slug": "requests",
  "name": "API Requests",
  "eventType": "requests",
  "aggregation": "SUM",
  "valueProperty": "$.total"
}
```

Each event contains the `subscription` ID linking it to a subscription and a
`total` field in `data` with the quantity to record:

```json
{
  "id": "5c10fade-1c9e-4d6c-8275-c52c36731d3c",
  "specversion": "1.0",
  "type": "requests",
  "source": "monetization-policy",
  "subject": "customer-id",
  "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
  "data": {
    "total": 1
  }
}
```

### Token Usage

Track token consumption for AI applications:

```json
{
  "slug": "tokens",
  "name": "Token Usage",
  "eventType": "tokens",
  "aggregation": "SUM",
  "valueProperty": "$.total"
}
```

Each event reports a fixed quantity per request. For example, if a meter is
configured to report 50 tokens per request:

```json
{
  "id": "a1b2c3d4-5678-4abc-8def-1234567890ab",
  "specversion": "1.0",
  "type": "tokens",
  "source": "monetization-policy",
  "subject": "customer-id",
  "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
  "data": {
    "total": 50
  }
}
```

### Data Transfer

Track bytes transferred:

```json
{
  "slug": "data_transfer",
  "name": "Data Transfer (bytes)",
  "eventType": "data_transfer",
  "aggregation": "SUM",
  "valueProperty": "$.total"
}
```

Each event reports the number of bytes transferred:

```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "specversion": "1.0",
  "type": "data_transfer",
  "source": "monetization-policy",
  "subject": "customer-id",
  "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
  "data": {
    "total": 4096
  }
}
```

## Naming Consistency

The meter `eventType` must match the key used in three places:

1. The meter's `slug` and `eventType`
2. The key in the monetization policy's `meters` configuration
3. The `featureKey` on the plan's entitlement

If these don't match, usage is not tracked correctly against the subscription's
entitlements.

## Creating a Meter

```shell
curl \
  https://dev.zuplo.com/v3/metering/$BUCKET_ID/meters \
  --request POST \
  --header "Authorization: Bearer $ZAPI_KEY" \
  --header "Content-Type: application/json" \
  --data @- << EOF
{
  "slug": "requests",
  "name": "API Requests",
  "eventType": "requests",
  "aggregation": "SUM",
  "valueProperty": "$.total"
}
EOF
```

## API Reference

For complete API operations (list, get, update, delete), see the
[Meters API Reference](../../api/metering-meters).