Skip to main content

Customers and subscriptions

Usagey operators are not the same records as billable customers. A customer belongs to one billing workspace and can have subscriptions, credit balances, entitlement overrides, transactions, invoices, and receipts.

Customer self-serve portal​

Hosted portal route

Customer portal endpoints run on https://usagey.com and require the signed-in customer's portal session. They are not part of the API-key-authenticated production or sandbox /v1 APIs.

The production customer portal shows the customer's effective entitlements rather than only raw event totals. Each feature includes:

  • usage in that feature's active reset window
  • the effective limit after a current manual override
  • remaining included usage and the next reset time
  • whether the feature is available, near its limit, at its limit, using billable additional volume, unlimited, or revoked
  • whether additional usage is blocked, charged immediately, collected at a threshold, or added to the next invoice

The portal warns customers before a limit becomes ambiguous. A blocked feature is shown separately from a feature whose additional usage is billable.

GET /api/customer-portal/{orgSlug} keeps the older usageSummary field for compatibility and adds entitlementSummary as the effective limit-aware view. This route uses the signed-in customer's email and does not consume usage or emit an entitlement-check event.

Portal checkout creation and confirmation require the same signed-in customer identity. Send an Idempotency-Key for both calls. Confirmation rejects provider references owned by another customer before provider verification or local balance and subscription reconciliation begins.

Portal reads never seed or mutate billing data. An organization must already have a production workspace and an active customer record before the route becomes available.

Create one Usagey customer for each billable account in your product. Set externalId to a stable identifier from your own database; do not use an email address as the only durable identity.

A subscription attaches a customer to a plan and stores lifecycle state, billing periods, trials, seat count, and provider references.

Seat count​

Seat-based pricing uses the explicit seatCount on a billing subscription. Usagey does not automatically synchronize this value with organization membership.

Lifecycle​

Subscriptions move through pending, trialing, active, past-due, and cancelled states. Provider webhooks reconcile remote lifecycle changes back into the workspace.

Dashboard lifecycle mutations verify the customer, plan, provider connection, and subscription against the selected workspace. Local lifecycle state, its developer event, and the idempotency response are committed atomically. Immediate upgrades and seat increases use prorated charging; downgrades and seat decreases are scheduled for the next renewal where provider capabilities permit it.