Usagey documentation

Build usage metering, entitlement checks, and billing workflows without maintaining the billing infrastructure yourself.

Usagey developer documentationUse the Node.js SDK or REST API in Sandbox, then promote to Production.

Install SDK

Explore Usagey

QuickstartConfigure a sandbox workspace and send your first event.Plans and featuresModel pricing, quotas, entitlements, and overage behavior.Node.js SDKInstall the typed server SDK with npm, pnpm, Yarn, or Bun.SDK configurationConfigure API environments, hosts, and request timeouts.Check entitlementsConfirm access before running billable customer work.Track usageRecord successful usage with concurrency-safe idempotency.Payment providersConnect and operate provider-managed billing lifecycles.AnalyticsRead usage, revenue, settlement, and customer metrics.

Popular guides

AuthenticationProtect server requestsDeveloper eventsInspect the live event streamWebhooks and billingOperate billing actionsInteractive API referenceExplore endpoints and schemas

Start your integration

The shortest reliable path is to configure a sandbox workspace, model one entitlement, and test the check-and-track lifecycle.

1. Configure the workspace

Open the Usagey dashboard, select Sandbox, and configure your default currency, tax behavior, invoice profile, and payment provider.

The workspace overview keeps environment selection, setup progress, transactions, and live operational signals in one place. Select the image to inspect it at full size.

2. Model access

Create these resources in order:

1. A plan group, such as primary-plan.
2. A plan, such as Starter.
3. A metered feature with a stable key, such as api_requests.
4. A plan entitlement that attaches the feature and its quota to the plan.
5. A billable customer and an active subscription.

3. Create a sandbox API key

Create a key from Developer > API keys. Sandbox keys begin with usg_test_; production keys begin with usg_live_.

Use sandbox keys only with https://sandbox.usagey.com/v1 and live keys only with https://api.usagey.com/v1. Usagey rejects a key sent to the wrong environment host.

Keep keys server-side

Never expose a Usagey API key in browser or mobile application code.

USAGEY_API_KEY=usg_test_replace_me

4. Check access

Call the check endpoint before expensive work runs:

curl --request POST https://sandbox.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
  }'

5. Track successful usage

Record usage only after the operation succeeds. Reuse the same idempotency key when retrying the same event.

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

A successful response returns status: "access_granted" with current usage, remaining quota, credit balance, and overage information where applicable.

Prefer the Node.js SDK

Server-side Node.js and TypeScript applications can use the official usagey SDK for typed entitlement checks, idempotent metering, checkout creation, and developer events. The REST API remains available for other runtimes.