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

# Versioning and deprecation

> The major version in the path, which changes happen without a new version, and how deprecations and sunsets are announced.

## Version in the path

Each surface carries its major version in the path: `/consumer/v1` and `/partner/v1`. Everything in these docs describes `v1`. A future `v2` would run side by side with `v1` under its own path, with its own OpenAPI document and its own version in these docs.

## Changes without a new version

Within `v1` the API changes only additively. Expect, without notice in advance:

* new operations, commands and webhook event types;
* new optional request properties and query parameters;
* new response properties and `_links` relations;
* new enum values (every enum is an open set);
* new error codes and new members in an error's `more` object;
* relaxed validation (longer maximum lengths, more accepted values).

Your client must therefore ignore unknown response properties, relations and error members, treat unknown enum values as "other", and ignore webhook types it does not handle. Additions appear in the API reference.

## Breaking changes and new versions

These changes never happen within `v1`; they only come with a new major version:

* removing or renaming an operation, property, parameter, header or relation;
* making an optional input required or tightening the validation of an existing field;
* changing a property's type, format, unit, meaning or nullability;
* removing an enum value or rejecting a value that was accepted;
* changing the status code or `errorCode` of an existing outcome;
* changing envelopes, pagination defaults or id formats;
* changing authentication or adding a required permission to an existing operation.

When a new major version is released, the old one stays available for **at least 12 months** after the new one is generally available.

## Deprecation and sunset

A deprecated operation, or every operation of a deprecated major version, answers with these headers:

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

* `Deprecation` (RFC 9745) is the moment the deprecation took effect, in Unix seconds.
* `Sunset` (RFC 8594) is when the operation stops working.
* `Link` points to the [deprecation and sunset](#deprecation-and-sunset) rules on this page and, where there is one, to the successor. Which operations are deprecated is shown by `deprecated: true` on the operation in the API reference and in the deprecation email to your technical contact.

Minimum notice between deprecation and sunset:

| What is deprecated | Notice |
| - | - |
| A whole major version | 12 months |
| A single operation that has a successor in the same version | 6 months |

Deprecated operations are marked on their reference page with the sunset date. After the sunset, the operation answers `410` [`api-version-sunset`](https://docs-consumer.voucher.allride.io/errors/catalog#api-version-sunset) for 90 days (`more.successorUrl` names the successor), then `404 route-not-found`.

Log the `Deprecation` and `Sunset` headers in your client so you notice a deprecation even if you missed the announcement.

## Webhook versions

Webhook bodies carry no version, and a webhook endpoint is not bound to one. 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 monitored mailbox. Every deprecation and sunset is announced there, together with network address changes and sandbox resets.
* Keep your partner's technical contact current in the developer dashboard: deprecation notices are emailed to it when your integration still calls a deprecated operation.
* Deprecations with a sunset within 90 days are also announced in a banner on this site.

## Related

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


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