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, estimated charges, and margin data. 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.
Common errors
400 invalid_request— malformed payload or failed validation.401 unauthenticated— missing, malformed, or revoked API key.
Authorization
apiKey x-api-key<token>
Your RevKeen API key (powered by Unkey). Get it from Dashboard > Settings > API Keys. Use rk_sandbox_* for test mode and rk_live_* for production.
In: header
Query Parameters
subscription_id?string
Filter to a specific subscription
Format
uuidcustomer_id?string
Filter to a specific customer by RevKeen ID
Format
uuidexternal_customer_id?string
Filter to a customer by your external identifier
meter_id?string
Filter to a single meter
Format
uuidResponse Body
application/json
application/json
application/json
Stuck on an error response? Ask the RevKeen assistant to explain it.
curl "https://api.revkeen.com/v2/usage/balance" \
-H "x-api-key: $REVKEEN_API_KEY"{
"object": "usage_balance",
"meters": [
{
"meter_id": "mtr_abc123",
"meter_name": "API Calls",
"price_name": "API call overage",
"unit_name": "calls",
"billing_scheme": "per_unit",
"tiers_mode": "graduated",
"unit_amount_minor": 10,
"unit_amount_decimal": "0.02",
"package_size": 100,
"percentage_rate_bps": 70,
"current_value": 1250,
"included_quantity": 1000,
"used_quantity": 1250,
"remaining_included": 0,
"overage_quantity": 250,
"estimated_amount_minor": 2500,
"total_cost_minor": 0,
"margin_minor": 0,
"currency": "usd",
"period_start": "2026-03-01T00:00:00.000Z",
"period_end": "2026-03-31T23:59:59.999Z",
"last_event_at": "2026-03-12T15:42:00.000Z"
}
],
"total_estimated_amount_minor": 2500,
"total_cost_minor": 0,
"total_payment_processing_cost_minor": 85,
"total_platform_fee_minor": 175,
"true_net_margin_minor": 2215,
"true_net_margin_percent": 88.6,
"currency": "usd"
}{
"error": {
"message": "string",
"type": "string"
}
}{
"error": {
"message": "string",
"type": "string"
}
}