Usage billing

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.

MethodPathPurposePermission
POST/merchants/:merchantId/usage-metersCreate a meter.usage:write
GET/merchants/:merchantId/usage-metersList meters.usage:read
PATCH/merchants/:merchantId/usage-meters/:meterIdUpdate name, unit or aggregation.usage:write
FieldTypeRequiredNotes
keystringNoDerived from the name when omitted. Unique per merchant.
namestringYes—
descriptionstringNo—
unitstringNoFor example requests, GB or tokens.
aggregationsum | count | max | lastNo—

Ingest events

Send up to 500 events in one request. Each event carries an externalId that acts as the idempotency key for that meter.

MethodPathPurposePermission
POST/merchants/:merchantId/usage-eventsIngest a batch. Query: environment=live|test.usage:write
GET/merchants/:merchantId/usage-eventsList events by meter, subscription, customer or date range.usage:read
GET/merchants/:merchantId/usage-events/aggregateAggregate a meter over a period.usage:read
GET/merchants/:merchantId/subscriptions/:subscriptionId/usageCurrent-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.

MethodPathPurposePermission
GET/api/v1/usage/metersList meters for the key's merchant.—
POST/api/v1/usage/eventsIngest events with a merchant API key.—
GET/api/v1/usage/eventsQuery events.—
GET/api/v1/usage/events/aggregateAggregate a meter.—