Build billing that notices you.

Quickstart #

Make your first observation in about four minutes.

1. Install the SDK. Python, Ruby and curl are also supported.

npm install @quantum-billing/node

2. Create a client and observe a customer. Observing is a read. Reads are billed. Your first 1,000 observations are free, unless you counted them.

Sample generated for this tab.

3. Read the response. Reading it again is billed.
4. Check what you were billed. See Observer-based billing. This is also a read.

Concepts #

Five ideas explain every behavior in the API. Two of them explain the invoices.

Observer-based billing #

Every read is a billable event. Think of it as read receipts for reads: you are told who looked at what, and charged for being told.

Observers are identified in the X-Observed-By header. If no observer is present, the read is billed to the one most likely to have been looking.

API reference #

Base URL: https://api.getquantumbilling.com. All requests use bearer auth and send QB-Version. All responses are JSON.

Authorization: Bearer qb_live_••••••••
QB-Version: 2026-10-29.ψ
QB-Universe: (optional) uni_prime

API playground #

Send a request against the sandbox universe. Click a history entry to review it. It will be different now.

// press "Send request"

Webhooks #

Subscribe to events and we will POST to your endpoint. Delivery is at-least-once. Webhooks may arrive before the event they describe.

Verifying signatures

Each delivery includes a QB-Signature header. Compute an HMAC of the raw body with your signing secret and compare in constant time. Verification can succeed for a different payload.

const ok = qb.webhooks.verify(rawBody, req.headers["qb-signature"], secret);
if (!ok) return res.status(400).end();   // ok may be true and false

Idempotency #

Send an Idempotency-Key on any POST. Keys guarantee a request happens at most once per universe. Retry as often as you like. In this universe, it will not happen again.

curl "https://api.getquantumbilling.com/v1/subscriptions" \
  -H "Idempotency-Key: 6f1c-once-per-universe" \
  -d '{"customer":"cus_halcyon","plan":"growth"}'

Errors #

Errors return a stable code, a human message, and an observed flag indicating whether the error occurred before you saw it.

Rate limits #

Rate limits are known only after you exceed them. Measuring your remaining quota would consume it, so we do not offer a header for that. We offer a header for what you used, one request later.

• Limits apply per key and per universe.
• Retry-After is accurate to the second, sometime last Thursday.
• Need higher limits? Talk to sales.

SDKs #

Server SDKs for Node, Python, Ruby, Go and Rust, plus a COBOL copybook of uncertain origin. Official libraries are generated from the OpenAPI spec, which is generated from the libraries.

Building a front end? The browser SDK is one script tag and eight web components: pricing table, checkout, portal, entitlements and more. Read the SDK docs.

Versioning #

SDKs use semantic versions. The current SDK is v4.2.1.

The current API version is 2026-10-29.ψ. Versions are named by date and a Greek suffix, and released out of order. Pin a version with the QB-Version header. Pinned versions are honored until they are observed to be wrong.

Breaking changes are announced in the changelog at least 90 days before, or 90 days after.

Was this page helpful? Yes No