Concepts

Account hierarchy

Learn how organizations, businesses, customers and subscriptions nest, when to add a second business, and why catalog ids look different from other ids.

tmbilling nests four levels, and each one has a job:

Organization          your tmbilling account — API keys, webhook endpoints, the isolation boundary
└── Business          one billing entity — its own catalog, currencies, gateways, invoice numbering
    └── Customer      the payer — contacts, payment methods, balances
        └── Subscription   what they are billed for

Organization

Your organization is your account. It holds your API keys and webhook endpoints, and it is the isolation boundary: everything a key reaches belongs to that organization, enforced in the database rather than in whichever query happens to run.

Most integrations use one organization and never think about this level again.

GET/v1/me

Business

One organization holds many businesses, and they are genuinely independent. Each business has its own:

catalog of products, prices and coupons
currencies, with its own default
gateway accounts, the payment providers it charges through
invoice numbering, branding and email templates
tax configuration
settings: dunning schedule, collection defaults, billing anchors

Create separate businesses when you sell under separate legal entities, in separate regions, or under separate brands.

Use one business when the same entity sells several things. The catalog already handles that, and splitting it splits your reporting too.

They are two businesses with two ids: the live one carries test_business_id, the test one carries live_business_id. POST /v1/businesses creates both and returns the one that matches your key's mode. Each mode has its own customers, invoices and settings, and a key reaches one mode only, so a test key cannot touch live data by accident. See Test and live mode.

Almost every URL in the API is scoped to a business:

/v1/businesses/{biz}/customers
/v1/businesses/{biz}/invoices
/v1/businesses/{biz}/subscriptions

Customer

Your customer is the payer within one business. Someone who buys from two of your businesses is two customers, with separate invoices, balances and payment methods — because those belong to the selling entity.

A customer owns contacts, vaulted payment methods with primary and backup roles, and three per-currency balances. See Customers.

Subscription

A subscription belongs to a customer and holds many items: one line per price, each with a quantity. That is how a plan, three add-ons and a metered usage line share one renewal date and one invoice.

See Subscriptions.

Object ids

tmbilling uses two id styles on purpose:

Style	Looks like	Where you see it
Generated	`cus_…`, `inv_…`, `sub_…`, `biz_…`	Customer-facing objects get a stable public id, separate from the internal key. Store it and expose it safely.
Slug	`pro`, `pro-monthly-usd`, `WELCOME20`	Catalog and coupon objects — product groups, products, prices, coupons, coupon sets — take a readable id you set. It is unique per business and immutable. Omit it and tmbilling derives one from the name.

Slug ids are what let one configuration reference the same objects in your test and live businesses. pro-monthly-usd means the same thing in both, so your deployment script, your fixtures and your support team can all name it.

Edit this pageorReport an issue

AI assistants (MCP)

Let Claude, Cursor or any MCP client read your billing data: customers, subscriptions, invoices, payments and metrics, with a read-only API key.

Catalog

Build your catalog from product groups, products and prices, select from eight pricing models, and give an add-on a different price on each plan.