Billing Metrics API

EmbayLMS runs platform billing on direct Stripe Billing (ADR-016): Stripe is the billing engine, and the LMS owns the definition of what to bill. The external billing orchestrator pulls each tenant’s current billable metrics from this endpoint at invoice time, then sets the quantity on the Stripe invoice. Metrics are computed live per call, so a pull is always current.

This is a server-to-server endpoint — not part of the tenant-facing public API.

Note: although live, this endpoint is intentionally excluded from the public OpenAPI spec at /api/v1/docs. It authenticates with a static platform Bearer secret (BILLING_METRICS_API_KEY), not a tenant API key, and is only for the external billing orchestrator — this page is its canonical reference.

Finding the tenant

Call with the EmbayLMS tenant id. The Stripe Customer carries metadata.embaylms_tenant_id, so the orchestrator can map a Stripe customer/subscription back to the tenant id to pull with.

Endpoint

GET /api/v1/billing/metrics?tenantId={uuid}

embaylms_tenant_id is accepted as an alias for tenantId.

Authentication

Authorization: Bearer <BILLING_METRICS_API_KEY>

A single platform secret (BILLING_METRICS_API_KEY; the legacy HUBSPOT_METRICS_API_KEY is accepted as a fallback during transition). Unset/mismatch ⇒ 401. The check is constant-time.

Response `200`

{
  "data": {
    "tenantId": "eaf926b4-7bec-440a-9083-7e75ad8a193b",
    "slug": "acme",
    "status": "active",
    "activeUsersThisMonth": 1,
    "licensedUsers": 2,
    "asOf": "2026-06-24T23:54:53.089Z"
  },
  "meta": null,
  "error": null
}

Field	Meaning
`activeUsersThisMonth`	Billable quantity (default) — users who logged in at least once this calendar month (active, not deleted).
`licensedUsers`	Provisioned active accounts (seats available).
`asOf`	Server timestamp when the counts were computed.

Adding a metric: each billable metric is a discrete field — add it to computeBillingMetrics and it appears here automatically (no metric-type enum). The orchestrator decides which field a given subscription bills on.

Status codes

Code	When
`200`	Authorized; metrics returned.
`400`	`tenantId` (or `embaylms_tenant_id`) missing.
`401`	Missing/invalid Bearer token, or `BILLING_METRICS_API_KEY` (and the legacy fallback) unset.
`404`	No tenant with that id.

Troubleshooting

Always 401 — BILLING_METRICS_API_KEY is not set on the EmbayLMS environment, or the orchestrator is sending a different value.
404 for a known tenant — confirm the tenant id (or the Stripe customer’s embaylms_tenant_id metadata) matches an EmbayLMS tenant.
Counts look low — only users who logged in this calendar month count as active; provisioned-but-never-logged-in users do not.

LTI 1.3 Overview