Money and currency
The API never uses floating-point money. Every amount is an integer in the currency's minor unit, sent with its currency code, and rounding follows one rule.
Send amounts in minor units
Every amount in the API is an integer in the currency's minor unit, paired with an ISO 4217 currency code. You will not find a floating-point amount anywhere.
| Amount | You send | Currency |
|---|---|---|
| $19.99 | 1999 | USD |
| ₹499.00 | 49900 | INR |
| ¥1,200 | 1200 | JPY |
JPY has no minor unit, so 1200 means ¥1,200 rather than ¥12. tmbilling knows each currency's
exponent. Your code only needs it when formatting for display.
1999 into a float, dividing by 100 and sending it back is how you lose a cent. Keep the
integer, and divide only in your formatter at the moment of display.Expect half-up rounding, per line
tmbilling rounds half-up to the nearest minor unit. That matters wherever a calculation lands on a fraction: percentage discounts, proration for a partial period, tax on a line, or a per-unit price times a quantity.
It rounds each line, then sums the rounded lines — rather than rounding one unrounded total. That is why an invoice still adds up when your customer checks it by hand.
Match currencies across the hierarchy
You set a currency at several levels, and they have to agree:
| Level | Field | What it sets |
|---|---|---|
| Business | default_currency | The currency the business bills in by default, and the one its reporting rolls up to. |
| Price | currency | The one currency a price is denominated in. Sell in three currencies and you create three prices. |
| Customer | currency | The currency you bill this customer in. It decides which prices you can put them on. |
| Subscription | derived | Every item on one subscription shares one currency. tmbilling refuses a mixed-currency item list rather than converting it. |
tmbilling never converts currency when billing. Conversion exists only for reporting: give a business exchange rates and its metrics roll up into its default currency. That never changes what you charge a customer.
Handle zero amounts
A zero-amount invoice is normal — a fully discounted period, or a trial that produced a document but no charge. tmbilling posts it and marks it paid without calling a gateway.
Invoice amounts are never negative. Reduce what a customer owes with a discount line, a credit application or a credit note. Each is its own object with its own ledger entries, so you keep the reason for the reduction. See Credits and the ledger.
Related
Versioning
Pin a date-based API version with a header, learn which changes arrive additively within a version, and know when to expect a new version and a deprecation.
Webhooks
Register an endpoint and receive every billing state change as a signed, retried webhook, so your systems learn about renewals, failures and disputes at once.