API REFERENCE
Usage billing
Meters describe what a customer consumes. Events record consumption. Prices decide what it costs at the end of the period.
Meters
A meter belongs to one merchant, has a unique key, and aggregates events with sum, count, max or last.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| POST | /merchants/:merchantId/usage-meters | Create a meter. | usage:write |
| GET | /merchants/:merchantId/usage-meters | List meters. | usage:read |
| PATCH | /merchants/:merchantId/usage-meters/:meterId | Update name, unit or aggregation. | usage:write |
| Field | Type | Required | Notes |
|---|---|---|---|
| key | string | No | Derived from the name when omitted. Unique per merchant. |
| name | string | Yes | — |
| description | string | No | — |
| unit | string | No | For example requests, GB or tokens. |
| aggregation | sum | count | max | last | No | — |
Ingest events
Send up to 500 events in one request. Each event carries an externalId that acts as the idempotency key for that meter.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| POST | /merchants/:merchantId/usage-events | Ingest a batch. Query: environment=live|test. | usage:write |
| GET | /merchants/:merchantId/usage-events | List events by meter, subscription, customer or date range. | usage:read |
| GET | /merchants/:merchantId/usage-events/aggregate | Aggregate a meter over a period. | usage:read |
| GET | /merchants/:merchantId/subscriptions/:subscriptionId/usage | Current-period usage per metered price. | subscriptions:read |
Ingest two events
bashExample
curl -X POST \
"$SOBTRA_API_URL/merchants/$MERCHANT_ID/usage-events?environment=test" \
-H "Authorization: Bearer $SOBTRA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"meterKey": "api_requests",
"events": [
{
"externalId": "req_9f81",
"quantity": 1,
"occurredAt": "2026-11-01T10:00:00Z",
"subscriptionId": "sub_1042"
},
{
"externalId": "req_9f82",
"quantity": 1,
"occurredAt": "2026-11-01T10:00:01Z",
"subscriptionId": "sub_1042"
}
]
}'Pricing usage
Prices accept a billing scheme, tiers and guardrails. The scheme decides how the period total is calculated.
- per_unit: quantity multiplied by the unit price.
- tiered: graduated tiers, where each tier prices only the units inside it.
- volume: every unit is priced at the tier the total quantity reaches.
- package and per_unit fall back to quantity multiplied by price when no tiers exist.
Usage is attached to the renewal invoice as its own line item and marked as billed, so a period cannot be invoiced twice. Minimum and maximum amount guardrails apply after the scheme is calculated.
Integration routes
API-key authenticated routes for server-to-server ingestion.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /api/v1/usage/meters | List meters for the key's merchant. | — |
| POST | /api/v1/usage/events | Ingest events with a merchant API key. | — |
| GET | /api/v1/usage/events | Query events. | — |
| GET | /api/v1/usage/events/aggregate | Aggregate a meter. | — |