Monetization API (Preview)

Meters

Copy page

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:

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

Each event contains the subscription ID as the subject and a total field with the quantity to record:

Code
{
  "type": "requests",
  "subject": "sub_xxxxxxxx",
  "source": "monetization-policy",
  "data": {
    "total": 1
  }
}

Token Usage

Track token consumption for AI applications:

Code
{
  "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:

Code
{
  "type": "tokens",
  "subject": "sub_xxxxxxxx",
  "source": "monetization-policy",
  "data": {
    "total": 50
  }
}

Data Transfer

Track bytes transferred:

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

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

Code
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.