Versioning
tmbilling versions its API by date. Pin a version with a header:
Tmbilling-Version: 2026-06-20
Omit the header and you get the deployment's current version. Pin it in production — an unpinned client can change behaviour without you deploying anything.
Expect these changes within a version
tmbilling changes the API additively. Within one version, expect it to:
- add an endpoint
- add an optional request field
- add a field to a response
- add a value to an enum you only read, such as an event type
- add a webhook event type
Write your client to tolerate all of these. Ignore response fields you don't recognise, and log
an unknown event_type or status rather than throwing on it.
Expect a new version for these
tmbilling issues a new version before it:
- removes or renames a field
- changes a field's type or meaning
- makes an optional request field required
- removes an endpoint, or changes what an existing call does to your data
Trust the spec as the contract
tmbilling generates this site's API reference from the OpenAPI document the typed SDK is built from — the same file, on every build. No second, hand-maintained description exists to drift out of step.
So if the reference and the engine disagree, the spec is wrong and your generated client carries the same mistake. Report it as an engine bug rather than a documentation lag.
Watch for deprecations
tmbilling marks an endpoint or field on its way out as deprecated in the spec, and the
API reference renders that as a badge. Deprecated does not mean removed — it
keeps working for the life of its version.
Related
Rate limits
Read the rate-limit headers on every response, slow your client down before requests are refused, and design your integration so it never reaches the limit.
Money and currency
Send every amount as an integer in minor units with a currency code, expect half-up rounding per line, match currencies across levels, and handle zero amounts.