Track usage

POST /v1/usage/track evaluates access and records consumption in one transactional operation.

const idempotencyKey = `job:${job.id}:api_requests`;

const response = await fetch('https://api.usagey.com/v1/usage/track', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.USAGEY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({
    externalId: account.id,
    feature: 'api_requests',
    quantity: 1,
    source: 'worker',
    metadata: {jobId: job.id},
  }),
});

const result = await response.json();

Request body

The request accepts the same customer selectors, feature, quantity, and source fields as the check endpoint. It also accepts a metadata object for event context.

Idempotency

Send Idempotency-Key for every event. If delivery is retried, resend the same payload and key. Reusing a key with different data returns HTTP 409.

Responses

HTTP	Status	Meaning
200	access_granted	Usage was accepted and recorded
402	no_active_subscription	Customer has no active plan
429	limit_exceeded	Included quota is exhausted and overage is blocked
429	insufficient_credits	Shared prepaid balance is too low
429	account_limit_exceeded	Your Usagey account has reached its monthly accepted-usage allowance
400	Other denial	Customer or feature could not be resolved
401	Authentication error	API key is missing or invalid
409	Idempotency conflict	The key was reused with a different payload

The X-Processing-Time-Ms response header reports server-side processing time. Successful responses and account-limit responses can also include Usagey-Limit, Usagey-Remaining, and Usagey-Reset headers for the operator account's current monthly allowance.

Usagey records accepted quantity, not merely request count. Replaying the same idempotent request does not consume the allowance twice, and /v1/usage/check never consumes it. Account enforcement starts in shadow mode. A platform administrator can enable blocking for one organization only after its counters reconcile with immutable meter events; the approval, reason, evidence window, and evidence summary are retained as rollout history.

An organization-specific rollout decision takes precedence over the USAGEY_ACCOUNT_METER_MODE environment fallback. This permits a staged rollout and an audited return to shadow mode without changing every account at once.

Usagey queues account warnings when usage first crosses 80%, 90%, and 100% of the period allowance. Growth accounts can request an explicit additional-volume allowance; there is no automatic or unpublished percentage charge. Existing grandfathered Launch accounts retain their contracted allowance and access.

Warnings are sent once per threshold and billing period to active organization owners and administrators. Delivery workers claim each warning before sending it, retry transient failures with bounded exponential backoff, and recover claims abandoned for more than ten minutes. A warning becomes a terminal failure after five attempts or immediately when no eligible recipient exists.