One script tag. Every price is a surprise.

Install #

Drop in one script tag. The library defines its custom elements on load and exposes window.QuantumBilling. This page loads it from /sdk/v1/quantum-billing.js.

<script src="https://getquantumbilling.com/sdk/v1/quantum-billing.js"></script>

Or use a package manager. The package is the same file with a package.json around it.

npm install @quantum-billing/js

import QuantumBilling from "@quantum-billing/js";

Single file, plain JavaScript, about 57 KB unminified. Works as a classic script, as a CommonJS module, and as a global. It does not touch the network.

Initialize #

Call QuantumBilling.init() once. Components find the latest instance through QuantumBilling.instance. If you never call it, they initialize themselves with a demo key and mention nothing.

const qb = QuantumBilling.init({
  publishableKey: "pk_superposed_8fQ2x",
  customer: "cus_halcyon",     // optional
  observer: "you",             // optional, appears in events
  collapse: "on-observe",      // "on-observe" | "aggressive" | "reduced"
  currency: "auto",            // "auto" or a fixed ISO code
});

Prefer markup? Put the same options on the script tag and skip the JavaScript.

<script src="https://getquantumbilling.com/sdk/v1/quantum-billing.js"
        data-publishable-key="pk_superposed_8fQ2x"
        data-customer="cus_halcyon"></script>

Try the collapse modes

Pricing table #

Plan cards with an interval toggle. Prices and features re-collapse on hover, on focus, and every time the table scrolls back into view. Annual billing sometimes costs more than twelve months. Choosing a plan fires qb:select, where the plan you receive may differ from the one you requested.

<qb-pricing-table plans="starter,growth,enterprise" interval="month" highlight="growth"></qb-pricing-table>

<script>
  document.querySelector("qb-pricing-table").addEventListener("qb:select", (e) => {
    const { requested, selected } = e.detail;   // selected sometimes differs
    // e.preventDefault() skips the checkout modal
  });
</script>

Checkout #

A three-step modal: review the plan, choose which universe to be billed in, confirm. There is no card field, no CVC and no password. The payment method is read-only and belongs to someone else. The confirmation total will not match the quote.

<qb-checkout-button plan="growth">Upgrade</qb-checkout-button>

<script>
  qb.on("checkout", ({ plan, universe, total }) => console.log(plan, universe, String(total)));
  // or open it yourself:
  const result = await qb.checkout.open({ plan: "growth" });  // { status, plan, universe, total }
</script>

The button also dispatches qb:checkout (bubbles, composed) with the result when an order completes.

Customer portal #

A mini portal in a modal: plan, entitlements, recent invoices and a cancel button. The cancel button fails in a different way each time, and occasionally moves.

<qb-portal-button>Manage billing</qb-portal-button>

<script>qb.portal.open();</script>

Entitlement gate #

Show different content depending on whether a feature is on, off or maybe. It collapses when viewed or hovered. If you provide no maybe slot, the default content is shown with a small ◐ ribbon explaining the maybe.

<qb-entitlement feature="sso">
  <div>shown when on</div>
  <div slot="off">shown when off</div>
  <div slot="maybe">shown when maybe</div>
</qb-entitlement>

Usage meter #

A meter for any metric. The limit is also observed, so the bar may exceed 100%. Overage is shown in the same colour as concern.

<qb-usage-meter metric="api_calls" label="API calls"></qb-usage-meter>

Invoice list #

Recent invoices as rows. Click a row to open a preview whose total disagrees with the row. Both are correct as of their observation.

<qb-invoice-list limit="4"></qb-invoice-list>

Observation badge #

A small pill showing this page's live observation count, with an amber ping on every collapse. Adding it to a page increases the number it shows.

<qb-observation-badge></qb-observation-badge>

Inline price #

A price you can put in a sentence. It re-collapses each time it scrolls into view, so the sentence stays technically true.

<p>Growth is <qb-price plan="growth"></qb-price>.</p>

Events #

Subscribe with qb.on(event, handler). It returns an unsubscribe function. Handlers run synchronously, inside the observation.

const off = qb.on("collapse", ({ target, kind, before, after, observation }) => {
  console.log(`#${observation}`, kind, before, "→", after);
});
off();   // stop watching. it will not help.

DOM events

Components also dispatch bubbling, composed events: qb:select, qb:entitlement, qb:checkout, qb:portal.

JavaScript API #

Every read resolves after 40 to 400 ms of simulated latency, increments qb.observations and emits collapse. About 3% of results carry superposed: true.

// press Run. the result will be different from the one in the docs.

Additions

• qb.select(planId): what qb-pricing-table calls. Resolves { requested, selected } and emits select.
• qb.invoices.get(id): a single invoice preview, with a total that disagrees with the list.
• qb.configure({ collapse, currency }) changes modes at runtime. qb.destroy() detaches the instance.
• Every read accepts a trailing options object. plans.list({ plans, interval }) and invoices.list({ limit }) narrow the result.
• Money-like results (balance, checkout.total) coerce to their display string when printed.

Theming #

Components render in Shadow DOM and read CSS custom properties from their ancestors. Set them on :root or on any wrapper. Defaults follow prefers-color-scheme. Modals take the properties of the element that opened them.

Bonus: --qb-accent-fg sets the text colour on accent buttons.

qb-pricing-table, qb-usage-meter, qb-invoice-list {
  --qb-accent: #e8590c;
  --qb-radius: 4px;
  --qb-font: "Iowan Old Style", serif;
}

Guarantees #

The SDK makes the following commitments. Each was true when you read it.

1. Every render is final, until the next one.Whatever you see is the value. The next thing you see is also the value.
2. Reading counts.Every API call is an observation. qb.observations is exact, and so is the other number.
3. No secrets are collected.There is no card field, no CVC and no password field anywhere in the SDK.
4. Accessible by default.Modals are real dialogs with a focus trap, Escape to close, focus restoration and scroll lock. Animations stop when the OS asks them to.
5. Well-behaved.Components work when added after load, work in multiples, and clean up their observers and timers when removed.
6. Sandbox by default.Demo keys never bill. Live keys bill when observed.

View the example app ↗

Source of this page's demos: /sdk/v1/quantum-billing.js. Also see the server SDKs and the changelog.