RevKeenDocs
StatusSupport
API Reference

List a customer's meter usage

Returns per-meter aggregates for a single customer. Requires a `customer_id` query parameter. For each meter the merchant has defined, the response includes the aggregate quantity (applying the meter's native aggregation function), the event count, and the most recent event timestamp. Use this to render a customer's current consumption snapshot in your own UI — for example, a usage dashboard showing "4,820 / 10,000 requests this period". --- **Related endpoints** - `GET /customer-meters/{customer_id}/{meter_id}` — Retrieve a customer-meter aggregate **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. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers.

GET
/customer-meters

Returns per-meter aggregates for a single customer. Requires a customer_id query parameter. For each meter the merchant has defined, the response includes the aggregate quantity (applying the meter's native aggregation function), the event count, and the most recent event timestamp.

Use this to render a customer's current consumption snapshot in your own UI — for example, a usage dashboard showing "4,820 / 10,000 requests this period".

Related endpoints

  • GET /customer-meters/{customer_id}/{meter_id} — Retrieve a customer-meter aggregate

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.

Pagination

Offset-based with limit (default 25, max 100) and offset. The response pagination block includes total and hasMore. See the pagination guide for SDK auto-paging helpers.

Authorization

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

customer_id*string

Customer UUID. Required — customer-meters are not queryable merchant-wide via this endpoint. Use /v2/meters for merchant-level meter definitions.

Formatuuid
meter_id?string

Optional single-meter filter. When provided, the response contains at most one entry.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

Stuck on an error response? Ask the RevKeen assistant to explain it.
curl "https://api.revkeen.com/v2/customer-meters?customer_id=value" \
  -H "x-api-key: $REVKEEN_API_KEY"
{  "object": "list",  "data": [    {      "object": "customer_meter",      "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",      "meter_id": "1e13adc1-9ac9-453b-b100-17d2f2da2eb8",      "meter_name": "string",      "meter_event_name": "string",      "aggregation": "string",      "unit_name": "string",      "total_quantity": 0,      "event_count": 0,      "last_event_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": false,  "url": "string"}

Retrieve a customer-meter aggregate GET

Returns a single customer-meter aggregate for the specified customer + meter pair. Returns 404 only if the meter itself does not exist on the merchant — if the meter exists but the customer has zero events, the response returns an aggregate with `total_quantity: 0`, `event_count: 0`, `last_event_at: null`. --- **Related endpoints** - `GET /customer-meters` — List a customer's meter usage **Common errors** - `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. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key.

Retrieve the authenticated customer GET

Returns the customer represented by the bearer token. Useful as a warm-up / identity check when an embedded portal page loads. --- **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice - `GET /customer-portal/mandates` — List the authenticated customer's Direct Debit mandates - `POST /customer-portal/mandates/{id}/re-authorize` — Re-authorise a Direct Debit mandate with new bank details **Common errors** - `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. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key.