---
title: "Versioning"
description: "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."
canonical_url: "https://twominutebilling.com/help/developers/api-essentials/versioning"
---
# 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.

tmbilling versions its API by date. Pin a version with a header:

```http
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](https://twominutebilling.com/help/developers/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](https://twominutebilling.com/help/developers/api-reference) renders that as a badge. Deprecated does not mean removed — it
keeps working for the life of its version.

## Related

- [Changelog](https://twominutebilling.com/changelog)
- [SDKs and the OpenAPI document](https://twominutebilling.com/help/developers/getting-started/sdks)


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.