Usage billing

Usage billing lets you charge customers based on metered consumption (API calls, seats, credits, etc.) on top of usage_based products. The flow is contract-first: every step below maps to a public REST endpoint in openapi.json.

For product setup (product_type: usage_based, prices, aggregation), see Products. Usage subscriptions are separate from recurring checkout subscriptions, use POST /usage-subscriptions to enroll customers on usage-based plans.

Golden path

Create a usage-based product

Create a product with product_type: usage_based and a recurring price. See Products.

Create a meter

Define the billable metric code your app will send on each usage event.

curl -X POST "https://sandbox.api.lomi.africa/meters" \
  -H "Authorization: Bearer $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api_calls",
    "product_id": "prod_...",
    "filter": { "code": "api_calls" },
    "aggregation": { "type": "sum", "property": "quantity" }
  }'

→ Create meter

Enroll the customer (usage subscription)

Before ingesting usage for a customer, enroll them on the usage-based product.

curl -X POST "https://sandbox.api.lomi.africa/usage-subscriptions" \
  -H "Authorization: Bearer $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_...",
    "product_id": "prod_..."
  }'

→ Create usage subscription

Record usage events

Send usage as it happens. Use a stable transaction_id per logical event for idempotency.

curl -X POST "https://sandbox.api.lomi.africa/usage-events" \
  -H "Authorization: Bearer $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "evt_unique_123",
    "code": "api_calls",
    "customer_id": "cus_...",
    "subscription_id": "sub_...",
    "quantity": 1
  }'

Returns 202 Accepted; processing is asynchronous.

→ Record usage event

Read balances and billing periods

Goal	Endpoint
Customer meter wallet	Get meter balance
Usage in current period	Get subscription usage
Historical periods	List billing periods
Prepaid credits	Credit wallet
Feature gating	Check entitlement

Reconciliation

List or get usage events when webhooks are delayed: List usage events, Get usage event.
Revenue reporting across MRR + usage + one-time: Combined revenue metrics.

Reference: lomi. Radar metering

lomi. Radar bills per screened charge when enabled on your organization. Each evaluation calls enqueue_usage_event with meter code radar_screen (aggregation: count).

Enable Radar via PATCH /organization/radar-settings (enabled: true). A radar_screen meter is created automatically when a matching usage-based product exists.
Every screened charge (card, MTN, Wave) records one usage unit while Radar is on.
Read balances and periods with the same endpoints as other usage meters (Get meter balance, List billing periods).

curl -X POST "https://sandbox.api.lomi.africa/usage-events" \
  -H "Authorization: Bearer $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "radar_screen_evt_123",
    "code": "radar_screen",
    "customer_id": "cus_...",
    "quantity": 1,
    "properties": { "assessment_id": "ra_...", "rail": "card" }
  }'

Platform ingestion is automatic when Radar runs; the example shows the event shape for reconciliation.

Radar: transaction screening product
Subscriptions: recurring checkout subscriptions (distinct from usage subscriptions)
Products: catalog and usage_based configuration
Verify payments: confirm transaction status before fulfilling access

Usage billing

On this page