Skip to main content

Check and track usage

Check without consuming​

const access = await usagey.check({
  externalId: "customer-42",
  feature: "api_requests",
  quantity: 1,
});

if (access.status !== "access_granted") {
  return { status: 403, reason: access.status };
}

check() evaluates the customer's subscription, entitlement, quota, credits, and account allowance without recording consumption.

Track successful work​

const result = await usagey.track(
  {
    externalId: "customer-42",
    feature: "api_requests",
    quantity: 1,
    source: "api",
    metadata: { route: "/v1/embeddings" },
  },
  { idempotencyKey: "request_01JEXAMPLE" },
);

Use exactly one customer selector per request: customerId, externalId, or email.

meter() is an alias for track():

await usagey.meter({
  customerId: "cus_123",
  feature: "ai_tokens",
  quantity: 800,
});

Idempotency​

The SDK generates an idempotency key when one is not supplied. For jobs, queues, and retried HTTP requests, provide a stable key from your own operation and reuse it for every retry. A replay returns the original decision without consuming the allowance twice.

Business decisions​

Expected denials are returned as typed results rather than thrown as transport errors. Handle statuses including limit_exceeded, feature_not_in_plan, no_active_subscription, insufficient_credits, and account_limit_exceeded in normal application control flow.