Usage API

One GET returns everything you need to reason about your own usage this billing period — how many orders neolife routed for you, where you stand against your plan (and any cap), and a count of your developer-surface objects.

Get current usage#

GET /v1/developer/usage

curl https://api.neolife.health/v1/developer/usage \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

{
  "object": "usage",
  "period": {
    "start": "2026-07-01T00:00:00.000Z",
    "end": "2026-07-05T00:00:00.000Z"
  },
  "plan": "starter",
  "ordersRouted": 12,
  "activeApiKeys": 2,
  "enabledWebhookEndpoints": 1,
  "eventsThisPeriod": 340
}

On a capped tier, the response also carries the cap and how much of it is left:

{
  "object": "usage",
  "period": { "start": "2026-07-01T00:00:00.000Z", "end": "2026-07-05T00:00:00.000Z" },
  "plan": "rail",
  "ordersRouted": 12,
  "orderCapPerMonth": 50,
  "ordersRemaining": 38,
  "activeApiKeys": 2,
  "enabledWebhookEndpoints": 1,
  "eventsThisPeriod": 340
}

Response fields#

Field	Type	Description
object	string	Always "usage".
period.start	string (date-time)	Start of the current billing period (the first of the month, UTC).
period.end	string (date-time)	The moment the response was computed.
plan	string	Your plan tier key (for example starter, rail).
ordersRouted	number	Orders neolife routed this period — the billable metric. Counts orders that have reached submission (submitting, submitted, accepted, shipped, delivered); drafts and rejected orders don't count.
orderCapPerMonth	number	Monthly routed-order cap. Present only on capped tiers — omitted when your plan is uncapped.
ordersRemaining	number	Orders left under the cap this period, floored at 0. Present only on capped tiers.
activeApiKeys	number	Count of your non-revoked API keys.
enabledWebhookEndpoints	number	Count of your enabled webhook endpoints.
eventsThisPeriod	number	Events recorded for your tenant this period.

orderCapPerMonth and ordersRemaining are conditional. They appear only when your plan has a cap. Treat their absence as "uncapped" rather than assuming a value.

Scope#

This endpoint reads your own tenant's aggregates for the current billing period. It returns counts only — no order, patient, or line-item detail crosses this surface, so it stays clear of the PHI boundary. Reading it requires a key with the billing:view scope; see Authentication.

The window resets at the start of each calendar month (UTC). To watch usage move within a period, poll this endpoint — the figures are always for the period that contains "now."

Related#

• API reference — base URL, versioning, errors, and rate limits.
• Events — the durable, PHI-free log behind eventsThisPeriod.
• Subscriptions — how plans and caps work.