Check an entitlement

POST /v1/usage/check evaluates the customer's current plan, overrides, quota, credits, and overage policy without recording usage.

curl --request POST https://api.usagey.com/v1/usage/check \
  --header "Authorization: Bearer $USAGEY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "externalId": "cus_9f2a",
    "feature": "api_requests",
    "quantity": 1
  }'

Request body

Field	Type	Required	Description
`customerId`	string	Conditional	Usagey customer ID
`externalId`	string	Conditional	Stable ID from your application
`email`	string	Conditional	Customer email fallback
`feature`	string	Yes	Feature key
`quantity`	positive integer	No	Defaults to `1`
`source`	string	No	Caller label; defaults to `api`

Provide at least one customer selector. Prefer customerId or externalId over email.

{
  "status": "access_granted",
  "customerId": "cm123",
  "featureId": "cm456",
  "subscriptionId": "cm789",
  "quantity": 1,
  "currentUsage": 420,
  "limit": 2000,
  "remaining": 1579,
  "creditsRemaining": null,
  "overage": null
}

Call this endpoint before expensive or irreversible work. A successful check does not reserve capacity, so the subsequent track call remains authoritative under concurrency.

Request body​

Request body