SDKs and tools

Call the Two Minute Billing API from TypeScript with the typed client, or from any language with a client you generate from the OpenAPI document. Both use the same REST API that the API reference describes.

Use the TypeScript client

The client is a thin, dependency-free wrapper over the REST API. Its response types come from the OpenAPI document, so they match what the engine returns. It sends an Idempotency-Key on every write for you. Pass idempotencyKey in the options to replay a specific request.

Install it from the npm registry. It has no dependencies and uses the platform fetch, so it runs on Node 20+, Deno, Bun and in the browser:

pnpm add @two-minute-billing/sdk

The package version is the Two Minute Billing release it was built from. Install the version that matches your API. The source is in sdk/ in the repository.

import { Tmbilling } from "@two-minute-billing/sdk";

const tmb = new Tmbilling({
  apiKey: process.env.TMBILLING_API_KEY!,
  baseUrl: process.env.TMBILLING_URL,
});

const biz = await tmb.businesses.create({ name: "Fernhill Analytics", default_currency: "USD" });
const product = await tmb.products.create(biz.id, { name: "Pro" });
const price = await tmb.prices.create(biz.id, {
  product: product.id,
  name: "Pro monthly",
  model: "flat",
  currency: "USD",
  amount_minor: 2900,
  interval: "month",
});

const customer = await tmb.customers.create(biz.id, { email: "[email protected]", currency: "USD" });
const subscription = await tmb.subscriptions.create(biz.id, customer.id, {
  items: [{ price: price.id, quantity: 1 }],
  trial_days: 14,
});

Set baseUrl to your API host. Without it the client calls http://localhost:4000.

Handle errors from the client

A non-2xx answer throws a TmbillingError with the HTTP status, the error type, the message, and the full response in body. Branch on them as described in Errors:

import { TmbillingError } from "@two-minute-billing/sdk";

try {
  await tmb.invoices.collect(biz.id, invoiceId);
} catch (err) {
  if (err instanceof TmbillingError && err.type === "rate_limit_error") {
    // Nothing was processed. Wait, then retry the same request.
  }
  throw err;
}

Some errors also carry a code, such as live_access_required. Read it from err.body.error.code.

The client exports the resource types too — Business, Customer, Price, Subscription, Invoice and more — so you can type your own functions against the API's objects.

Know what the client covers

The client covers the billing flow end to end: businesses, the catalog (products, product groups, prices, coupons and coupon sets), customers, payment methods and payment intents, subscriptions (including estimates and plan changes), invoices, payments, the wallet, credit notes, payment links and checkout sessions, usage (meters, usage events, usage keys and model prices), events, metadata rules, tax profiles and regions, and webhook endpoints. Products, prices and subscriptions take your own id when you create them.

For the rest of the API, call it directly with fetch and the same Authorization and Idempotency-Key headers. That includes:

• reports and analytics,
• settings, team members and API keys,
• integrations,
• the dunning actions on an invoice (pause, resume, stop),
• creating a customer with your own id (the API accepts it; the client's type does not yet).

The API reference lists every endpoint.

Generate a client in another language

Fetch the spec from your API host:

curl $TMBILLING_URL/openapi.json -o openapi.json

It is a standard OpenAPI 3.1 document, so the usual generators work:

openapi-generator-cli generate -i openapi.json -g python -o ./tmbilling-python

oapi-codegen -package tmbilling openapi.json > tmbilling.go

npx openapi-typescript openapi.json -o schema.d.ts

This site's API reference is generated from the same document.

Use the built-in tools