RevKeenDocs
StatusSupport
API Reference
📊 Usage BillingUsage Balance

Get current usage balance

Returns the current usage balance for a customer or subscription in the active billing period. Shows per-meter breakdown with included allowance, overage, and estimated charges. A subscription has one currency; metered usage attributed to the subscription is assumed to be in that same currency. RevKeen does not perform FX conversion in the metering layer.

GET/usage/balance

Returns the current usage balance for a customer or subscription in the active billing period. Shows per-meter breakdown with included allowance, overage, and estimated charges. A subscription has one currency; metered usage attributed to the subscription is assumed to be in that same currency. RevKeen does not perform FX conversion in the metering layer.

Required: at least one of subscription_id, customer_id or external_customer_id. Each is optional on its own, but a request with none of them is rejected with 400 and error.type invalid_request_error. meter_id narrows the result and does not identify a customer by itself.

Common errors

  • 400 invalid_request — malformed payload or failed validation.
  • 401 authentication_error — missing, invalid, expired, or revoked credential. Codes: authentication_failed, invalid_api_key, expired_api_key, api_key_revoked, session_invalid, merchant_required. Carries a WWW-Authenticate: Bearer challenge.

Authorization

apiKey
x-api-key<token>

Your RevKeen merchant API key. Create and manage keys in Dashboard → Settings → Developer. Use rk_sandbox_* for staging/test and rk_live_* for production. The same key may be sent as Authorization: Bearer <key> if that suits your HTTP client better. A missing, invalid, expired, or revoked key returns 401 with a WWW-Authenticate: Bearer challenge; a valid key without the required scope returns 403.

In: header

Query Parameters

subscription_id?string

Filter to a specific subscription

Formatuuid
customer_id?string

Filter to a specific customer by RevKeen ID

Formatuuid
external_customer_id?string

Filter to a customer by your external identifier

meter_id?string

Filter to a single meter

Formatuuid

Response Body

application/json

application/json

application/json

application/json

Stuck on an error response? Ask the RevKeen assistant to explain it.
curl -X GET "https://api.revkeen.com/v2/usage/balance?subscription_id=11111111-1111-4111-8111-111111111111&customer_id=11111111-1111-4111-8111-111111111111" \
  -H "x-api-key: $REVKEEN_API_KEY"

Synthetic documentation data, validated against the response schema; not a live API result.

{  "object": "usage_balance",  "meters": [    {      "meter_id": "7c8d9e0f-1a2b-4630-8d4e-5f6a7b8c9d01",      "meter_name": "API calls",      "price_name": "API call overage",      "unit_name": "calls",      "billing_scheme": "per_unit",      "tiers_mode": null,      "unit_amount_minor": 2,      "unit_amount_decimal": "2",      "package_size": null,      "percentage_rate_bps": null,      "current_value": 1250,      "included_quantity": 1000,      "used_quantity": 1250,      "remaining_included": 0,      "overage_quantity": 250,      "estimated_amount_minor": 500,      "currency": "gbp",      "period_start": "2026-04-16T10:00:00.000Z",      "period_end": "2026-05-16T10:00:00.000Z",      "last_event_at": "2026-04-18T09:15:00.000Z"    }  ],  "total_estimated_amount_minor": 500,  "currency": "gbp"}

Put this endpoint to work

Configure usage billing