Introduction
Two Minute Billing — tmbilling for short, and the name you will see in the API — is a multi-tenant subscription billing platform. It runs your recurring billing end to end: a catalog of products and prices, subscriptions with trials and proration, invoices with tax and discounts, collection through your own payment gateways, and dunning when a card fails.
It is not a payment gateway. Your payment gateway charges the card. tmbilling decides what to charge, when, and what to do when the charge fails.
What tmbilling owns
tmbilling is the source of truth for your subscription state. It asks a payment provider to do two things: charge a card and vault it. It never asks the provider what a subscription is, when it renews, or whether it is in trial.
That boundary is what lets you change provider, run two at once for different currencies, or bill through one provider and refund through another — without touching your subscription data.
Three things to know before you build:
- Amounts are integers in minor units, with a currency code.
1999plus"USD"is $19.99. You will not find a float anywhere in the API. - Balances come from an append-only ledger, not from a column tmbilling overwrites. A correction is a new entry, so you can trace every number on an invoice back to what produced it.
- Every write takes an
Idempotency-Key. Retry a request that may or may not have landed and you get the original answer, which is how you should handle a timeout.
How a billing cycle runs
Once your subscription exists, tmbilling drives it on a durable clock — a Postgres job queue rather than an in-memory timer. A restart loses nothing, and tmbilling catches up a missed minute instead of skipping it.
On each tick, for every subscription whose period has ended:
Roll the term forward
tmbilling advances the period. If the subscription has a fixed number of cycles left, the counter drops. A subscription that runs out of cycles stops renewing rather than cancelling.
Assemble the invoice
tmbilling gathers recurring lines, prorations from any mid-cycle change, metered usage for the period that just closed, and any unbilled one-off charges waiting to be swept in.
Apply discounts, then tax, then credits
Coupons and promotional credits come off before tax. Refundable credits and excess payments come off after it. That order is what keeps the tax figure defensible.
Collect
If the subscription collects automatically, tmbilling charges the customer's primary payment method, falling back to the backup cards on any decline.
Dun on failure
A failed charge moves the invoice to payment_due and starts the retry schedule. You configure
what happens when the retries run out.
Every step emits events, and you can receive each one as a webhook. To see exactly what your integration will get, read the event reference — tmbilling generates it from its own event registry, so it cannot drift from what actually fires.
Where to start
Related
Ask Billy
Billy answers questions about your billing from your own data, checks every figure, shows you where to act, and prepares changes that you confirm.
Quickstart
Bill your first customer from code in test mode: create a business, a price, a customer with a test card, and a subscription that charges it. No gateway needed.