> ## Documentation Index
> Fetch the complete documentation index at: https://docs-provider.voucher.allride.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and deprecation

> How the API changes and how you hear about it.

## Version in the path

The major version is part of every path: `/provider/v1`, `/partner/v1`. All surfaces start at `v1`. A new major version (`v2`) would run side by side with `v1`, with its own reference.

## Changes without a new version

Within `v1` AllRide only makes additive changes:

* new operations, commands and query parameters;
* new optional request properties;
* new response properties and `_links` relations;
* new enum values, error codes and error members;
* new webhook types and payload properties;
* relaxed validation (longer maximums, more accepted values).

Your integration must ignore unknown properties and handle unknown enum values and error codes. See [Compatibility rules](https://docs-provider.voucher.allride.io/guides/requests-and-responses.md#compatibility-rules).

## Breaking changes and new versions

These changes happen only in a new major version: removing or renaming an operation, property or parameter; making an optional input required or tightening validation; changing a type, format, unit or meaning; changing status codes or error codes of an existing outcome; changing envelopes, pagination defaults or id formats; adding a required permission to an existing operation. The published OpenAPI document is checked against these rules on every change.

## Deprecation and sunset

A deprecated operation or major version answers every request with:

```text theme={null}
Deprecation: @1798761600
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://docs-provider.voucher.allride.io/guides/versioning>; rel="deprecation"; type="text/html"
Link: <successor URL>; rel="successor-version"
```

* At least **12 months** pass between a new major version becoming available and the old one's sunset; at least **6 months** for a single operation that has a `v1` successor.
* The reference marks deprecated operations.
* Partners who still call a deprecated operation get emails at deprecation and 90, 30 and 7 days before sunset, sent to `contacts.technicalEmail`.
* After the sunset, the operation answers 410 `api-version-sunset` (with `more.sunsetAt` and `more.successorUrl`) for 90 days, then 404.

## Webhook versions

Webhook bodies carry no version. The body is always `{"event": {"id", "type", "timestamp"}, "payload": {…}}`, and a payload only gains fields: ignore properties you do not know. A breaking change to a payload ships as a **new event type**, which you subscribe to when you are ready; the existing type keeps its shape.

## Staying informed

* Keep `contacts.technicalEmail` on your partner a current, monitored mailbox: deprecation notices and security emails go there.
* Watch for `Deprecation` and `Sunset` headers in your logs.

## Related

* [Requests and responses](https://docs-provider.voucher.allride.io/guides/requests-and-responses.md#compatibility-rules)
* [Webhooks](https://docs-provider.voucher.allride.io/webhooks/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.