Concepts

Catalog: products and prices

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.

Each business has its own catalog, with three levels:

Product group        an optional grouping for reporting and portal display
└── Product          the thing you sell — a plan, an add-on, or a one-off charge
    └── Price        one way to charge for it — a currency, an interval, a model

Products

Give each product a kind:

Kind	Use it for
`plan`	The main thing a subscription is for. Most subscriptions carry exactly one.
`addon`	Something bought alongside a plan, such as extra seats or premium support.
`charge`	A one-off, rather than a recurring line.

curl -X POST $TMBILLING_URL/v1/businesses/$BIZ/products \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pro", "code": "pro", "kind": "plan" }'

DELETE archives a product by setting active=false rather than removing it, so your history keeps pointing at something real.

Prices

Give a product as many prices as you need. Each price fixes a currency, an interval and a model. Selling one plan monthly and yearly, in USD and EUR, means four prices on one product.

curl -X POST $TMBILLING_URL/v1/businesses/$BIZ/prices \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "pro",
    "id": "pro-monthly-usd",
    "name": "Monthly USD",
    "model": "flat",
    "currency": "USD",
    "amount_minor": 2900,
    "interval": "month"
  }'

Set type to recurring, the default, or one_time. Recurring prices need an interval of day, week, month or year, plus an optional interval_count — so "every three months" is interval: "month" with interval_count: 3.

Select a pricing model

Model	You set	How it charges
`flat`	`amount_minor`	A fixed amount per period, whatever the quantity.
`per_unit`	`amount_minor`	The amount times the quantity. Use it for seats.
`tiered`	`tiers[]`	Graduated. Each tier's units charge at that tier's rate, so a quantity spanning three tiers pays all three.
`volume`	`tiers[]`	Charges the whole quantity at the rate of the tier it lands in.
`stairstep`	`tiers[]`	Charges the tier's `flat_amount_minor`, wherever in the tier the quantity falls.
`package`	`amount_minor`, `package_size`	Sells in blocks — 1,000 credits for $10 — rounding up to whole packages.
`usage`	`usage_aggregation`	Meters usage and bills in arrears for the period just closed. See Usage-based billing.
`percentage`	`percentage_bps`	Takes a cut in basis points, where `250` means 2.5%. `free_units` exempts a base amount first.

The tier, package and percentage models bill recorded usage instead of the subscription quantity when you give them a usage_aggregation. The price object then reads metered: true. See Usage-based billing.

Reprice without repricing your customers

A PATCH on a price applies to new subscriptions only. Existing subscriptions keep the price you created them with, so raising a price never silently reprices everyone on it.

To move existing customers, change their subscription items. See Upgrades and downgrades.

id is a slug you set, such as pro-monthly-usd, unique per business. Omit it and tmbilling derives one from the name, or from the currency, interval and model.You cannot change it once set, and a collision returns 409. That immutability is what lets you use the same id in your test and live businesses.

Add-ons

Restrict a product with kind: "addon" to specific plans, and give it a different price depending on the plan it attaches to.

PUT/v1/businesses/{biz}/products/{prod}/applicable_plans

Restricts the add-on to a list of plans. tmbilling refuses to add it to any other plan.

PUT/v1/businesses/{biz}/products/{prod}/differential_prices

Sets a differential price: what the add-on costs on that particular plan, overriding its own price. Use it to bundle an add-on cheaply with an expensive plan.

Coupons

Coupons live in the catalog too, because they are configuration rather than transactions.

A coupon is a reusable discount — percent or amount, with validity dates and constraints on which products it applies to.
A coupon set is a batch of unique single-use codes from one definition, for a campaign where each recipient gets their own code.

See Coupons and discounts.

Edit this pageorReport an issue

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.

Customers

Create the customer who pays, with the currency and address fields that tax depends on, saved payment methods with a backup role, and three separate balances.