consume()

Use consume() instead of check() when the action you’re gating is the usage - the limit check and the increment happen in one atomic database statement, so two concurrent requests can’t both slip through a BLOCK limit the way a separate check-then-increment would allow.

const result = await kerne.consume('api_calls', {
  customer: userId,
  delta: 1,              // defaults to 1
  idempotencyKey: requestId, // optional - see below
  dimension: 'cutter_42',   // optional - see below
});
// { allowed, limit, used, remaining, overage_behavior, ... }

If allowed is false, nothing was incremented - the request never happened as far as the counter is concerned.

string

Whose quota to check and charge. Optional in the type (same as check()), but with a secret key there is no implicit “current user” - pass the customer you mean.

number

Whole number, defaults to 1. A fractional delta is rejected, not rounded.

string

Optional. A retry with the same key replays the original decision instead of counting again - see Idempotency.

string

Optional. Which slice of the customer to charge - see Dimensions. The SDK param is dimension; it is sent on the wire as dimension_id.

delta is a whole number. Meter in the smallest unit you bill - minutes rather than hours, megabytes rather than gigabytes, tokens rather than thousands of tokens - and let the plan’s rate put the offer back (“0.35 EUR per 60 minutes”). A fractional delta is rejected, not rounded.

Dimensions

dimension names which slice of the customer this consumes - a machine, a project, a device. What it does depends on how the plan is configured:

Plan setting	Effect
Allowance shared	The customer keeps one counter. The dimension is recorded for attribution only - “which machine cost what” stays answerable.
Allowance per dimension	Each slice gets the full allowance, counted separately. Required: a call without one is rejected.

// 200 hours per cutter: cutter_42 running out doesn't touch cutter_43
await kerne.consume('cutter_minutes', {
  customer: customerId,
  dimension: 'cutter_42',
  delta: 60,
});

// The same call, counting per seat instead: 1,000 credits each
await kerne.consume('ai_credits', { customer: orgId, dimension: userId, delta: 1 });

// ...or per project, per device, per one of your customer's own clients
await kerne.consume('sms_sent', { customer: agencyId, dimension: 'client_88', delta: 1 });

Two mistakes are rejected rather than silently ignored, because both would charge the wrong counter: sending a dimension on a feature that declares none, and omitting one when the plan limits per dimension.

The billing cap binds independently of the allowance - it can bound the customer’s total bill, or each dimension’s own. See Usage billing.

A customer can hold up to 1,000 distinct dimensions per feature per period. Past that, calls naming a new one are refused - a guard against a loop accidentally passing a fresh id on every request. Existing dimensions keep working.

Idempotency

Pass a stable idempotencyKey (e.g. your own request id) and a retried call with the same key replays the original decision instead of double-counting - safe to retry on a timeout without double-charging usage.

await kerne.consume('api_calls', { customer: userId, idempotencyKey: `req_${requestId}` });

Only for QUOTA features

consume() throws if called on a BOOLEAN or STATIC feature - those have nothing to increment. Use allows()/check() for those instead.

Server SDK

Frontend SDKs

Dimensions

Idempotency

Only for QUOTA features

​Dimensions

​Idempotency

​Only for QUOTA features

Dimensions

Idempotency

Only for QUOTA features