Usage Metering Quick Start

Set up usage-based billing: define a billable metric, price it on a product, add it to a plan, and send usage events.

Usage metering bills customers for what they consume — API calls, storage, compute hours, tokens, seats — instead of, or on top of, a fixed fee. In Alguna it takes four things: a billable metric that aggregates your events, a metered product priced on that metric, a plan (or subscription) that includes the product, and the usage events your application sends. This guide sets each up, in the dashboard and with the API. How metrics, prices and invoices fit together is described in How Alguna works.

---

How usage billing works

1. Usage occurs — the customer uses your product
2. Events recorded — your application sends events to POST /events, tagged with the customer and an event_name
3. Usage aggregated — at invoice time, Alguna evaluates each metric over the billing period
4. Invoice generated — the aggregated quantity is priced by the product’s pricing model
5. Payment collected — with the customer’s stored payment method, or by invoice

---

Step 1: Create a billable metric

A metric names the event_name to read, optional filters on event properties, and the aggregation.

Method	Result	Example
count	Number of events	API requests
sum	Sum of a property	GB transferred
count_unique	Distinct values of a property	Active users
average	Mean of a property	Response time
min	Smallest value	Lowest latency
max	Largest value	Peak concurrent connections

Dashboard: open Billable Metrics, click Create Metric, and set the name, event name and aggregation.

API:

cURL

curl -X POST https://api.alguna.io/metrics \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Requests",
    "event_name": "api_request",
    "aggregation": { "method": "count" }
  }'

The response includes the metric id (mtr_…). Reference: Create a billable metric; all options in Create metrics and the metrics reference.

---

Step 2: Create a usage-based product

Dashboard: open Products, click New Product, set Fee type to Metered, choose the metric, and pick a pricing model.

API: create the product with Create a product (fee_type: "metered"), then price it when you add it to a plan or subscription — a metered price carries metric_ids: ["mtr_…"] and a pricing model. Examples in Creating a subscription.

Pricing models for usage

Model	Description	Example
Unit	Fixed price per unit	$0.001 per API call
Graduated tiered	Each tier priced at its own rate	First 1,000 free, then $0.01 each
Volume (tiered)	All units at the rate of the tier the total lands in	0–1,000: $0.01 each; 1,001+:$0.008 each
Package	Price per block of units	$10 per 1,000 calls

See Pricing models and the API’s pricing model reference.

---

Step 3: Add it to a plan

Dashboard: open Plans, select or create a plan, click Add Product, choose the metered product, and save.

API: include the product in the plan’s items with Create a plan, or put the metered price directly on a subscription with Create a subscription. See Plans.

---

Step 4: Send usage events

Every event needs:

Field	Description
event_name	The metric’s event name, e.g. api_request
account	The customer’s Alguna ID (cust_…) or one of their aliases
unique_id	An idempotency key per event, max 72 characters; a resend with the same value is dropped
timestamp	When the usage occurred (RFC 3339); optional, defaults to now
properties	Up to 50 key/value pairs for filters and sum/max/… aggregations

cURL

curl -X POST https://api.alguna.io/events \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "unique_id": "req_9f1c2e7a",
        "event_name": "api_request",
        "account": "cust_abc123",
        "timestamp": "2026-04-01T10:30:00Z",
        "properties": { "endpoint": "/v1/analyze" }
      }
    ]
  }'

Up to 100 events per request; the response lists ingested and failed IDs. For batching, buffering, CSV import and warehouse connectors, see Send usage events. Reference: Ingest billable events.

Usage can also arrive without code — pull it nightly from BigQuery or ClickHouse, or upload a CSV.

---

Viewing customer usage

Current period

1. Open Customers and select the customer
2. Open the Usage tab to see usage by metric, estimated charges and trends

Historical usage and revenue

Open Revenue Insights to filter by customer, metric or date range; see Revenue Insights. The same figures are available through the Insights endpoints.

---

Common use cases

Use case	Metric	Aggregation	Pricing
API billing	API requests	count	Graduated tiered (free tier + overage)
Storage billing	Storage (GB)	max	Unit, per GB per month
Compute billing	Compute hours	sum	Unit
Active-user billing	Active users	count_unique	Unit, per user per month
Token billing	Tokens	sum of a tokens property	Unit or package

---

Troubleshooting

No usage showing

1. Check the failed list in the POST /events response — a 200 does not mean every event was accepted
2. Confirm event_name matches the metric exactly
3. Confirm account resolves to the customer on the subscription (ID or alias)
4. Check timestamps fall within the billing period

Incorrect charges

1. Review the metric’s aggregation method and field
2. Check the pricing model on the product
3. Verify the billing period dates on the subscription

---

Best practices

Set unique_id on every event

Retries are then safe; the same event is never counted twice.

Use event time

Send the time the usage happened, not the time you sent it.

Test in sandbox

Send known event sets and check the metric before going live.

Filter at the metric

Exclude internal or failed requests with metric filters, not in pricing.

---

Next steps

Create metrics

Filters, aggregations and API examples.

Pricing models

Unit, tiered, volume and package pricing.

Credits quick start

Sell prepaid credits against the same metrics.

Developer quick start

Auth, SDK, webhooks and sandbox.