Skip to main content
The Ledger API is a JSON API over HTTPS. It’s organised around a few resources: usage (check and track), customers, billing, and the catalog of plans, features and credit packs. The OpenAPI spec describes every endpoint, for code generation and agent tools.
Base URL
There’s one base URL for both environments. The API key decides whether a request reads and writes Sandbox or Live.

​
Authentication

Send a secret key as a bearer token on every request. Keys start with ledger_test_ (Sandbox) or ledger_live_ (Live), and each can be limited to groups of endpoints. See API keys and permissions.
Keep keys on your server. The API has no endpoints meant for browsers or mobile apps.

​
Conventions

  • Methods. GET reads, POST creates and updates, DELETE archives catalog items or deletes a customer. Updates take the item’s complete body.
  • Bodies. Send JSON with Content-Type: application/json, up to 1 MiB. Requests without the header get 415; larger bodies get 413.
  • Customers. Identify a customer by your own ID, customerId, in the body or, on GET and some POST and DELETE requests, as a URL-encoded query parameter: ?customerId=user_123.
  • Money is in US cents, in fields ending in Cents.
  • Timestamps are ISO 8601 strings in UTC.
  • Request IDs. Every response has an x-request-id header. Quote it when you ask about a request.

​
Errors

Errors return a non-2xx status and a body with an error code, sometimes with fields that help you act:
Errors lists every code with what to do about it.

​
Idempotency

Retries are safe where they matter:

​
Rate limits

Each key can send check and track at 200 requests a second, billing and catalog writes at 5 a second, and everything else at 50 a second, with short bursts above that. Every response carries RateLimit-* headers; over the limit, Ledger returns 429 with a Retry-After header. See Rate limits.

​
Pagination

List customer subscriptions and List customer purchases return pages, newest first:
Pass limit (1–100, default 25), and when hasMore is true, pass nextCursor as cursor to get the next page. Catalog lists return every active item at once.

​
SDKs

The TypeScript and Python SDKs, both integrateledger, wrap every endpoint except deleting a customer. Each endpoint page shows cURL, TypeScript and Python.