Skip to main content
The Orvlin API is a JSON API over HTTPS. Every endpoint lives under /v1.

​
Making requests

  • Send and receive JSON. Set Content-Type: application/json on requests with a body.
  • Authenticate with an API key (see Authentication).
  • Dates and times are ISO 8601 strings, with a timezone offset or Z.
  • Money amounts are decimal numbers in the currency named on the object. Currencies are three-letter ISO codes, such as USD.
  • IDs are strings. Customer IDs are yours or cust_…. Other objects get ULID-style IDs.

​
Pagination

Lists return { "data": [ … ] }. Some also accept paging parameters: Invoice lists also return a pagination object with total, page, and pageSize.

​
Idempotency

Requests that create billable records take an idempotency key, so a retry can’t create a duplicate:
  • Events: set idempotencyKey on each event.
  • Credit grants and purchases: set idempotencyKey in the body.
Reusing a key returns the original result instead of creating a second record.

​
Errors and rate limits

Errors return a JSON body with an error message. See Errors. Requests are rate limited. If you receive 429 Too Many Requests, wait and retry with exponential backoff.

​
Usage

Usage summaries and time series for the dashboard are available from:
  • GET /v1/usage/summary: totals across the workspace.
  • GET /v1/usage/customers/:customerId/timeseries: consumption for one customer over time.

​
Health

​
Resource index

Some endpoints are for the dashboard and aren’t covered here. They include coupons, contracts, dunning, forecasts, and revenue recognition, which are documented in the guides where they apply.