# Versioning and deprecation

> How the Transferz APIs change over time, how deprecated fields are marked, and how to stay compatible.

Section: Essentials · Last updated: 2026-11-15

The Transferz APIs have no version number in their URLs. This guide explains how changes reach you
and how to write a client that keeps working.

## How the APIs change

- **Additive changes** happen without notice: new endpoints, new optional request fields, new
  response fields, new webhook event fields and new enum values.
- **Deprecated fields** stay in the API for now and are marked as deprecated in the
  [API reference](https://developers.test.transferz.com/reference).
- **Every change** to the API specifications appears in the [changelog](https://developers.test.transferz.com/changelog), with its date and
  the audience it affects.

Each specification has a version number, shown in the API reference. It changes when the API
changes.

> **To be confirmed by Transferz:** The policy for breaking changes (how they are announced, how much notice you get, and how long
> deprecated fields keep working) is still to be confirmed by Transferz.

## Write a tolerant client

- Ignore response and event fields you do not know.
- Handle enum values you do not know, for example by logging them and treating them as "other".
- Do not depend on the order of fields in JSON or of items in a list, unless the reference says so.
- Read only the fields you need, so a change elsewhere cannot affect you.
- Follow the [changelog](https://developers.test.transferz.com/changelog) or its feed.

## Deprecated today

| API                    | Field                                         | Use instead                      |
| ---------------------- | --------------------------------------------- | -------------------------------- |
| Partners API           | `limitToVehicleCategory` (quote request)      | `limitToVehicleCategories`       |
| Partners API           | `combinedBabyAndBoosterSeatsCapacity` (quote) | `combinedSeatBasedAddonCapacity` |
| Transfer Companies API | `addOns` (journey)                            | `addonsPerQuantity`              |

Some enum values are deprecated as well; the [Constants](https://developers.test.transferz.com/guides/essentials/constants) guide marks
them.
