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

# Versioning and deprecation

> How paywise versions its API paths, which changes can arrive without a new version, and the policy for retiring one.

paywise versions each API in its path, and only changes the version when the
contract changes in a way that would break a correctly written client. Inside
one version the contract grows; it does not shrink or change meaning.

## Path-based versions

| API | Current prefix |
| - | - |
| Case Management API | `/v2/` |
| Partner API | `/partner/v2/` |
| Mahnservice API | `/mahnservice/v1/` |

There is no version header, query parameter, or per-key version pin. The
prefix you call is the contract you get, on both `api.paywise.de` and
`api-sandbox.paywise.de`.

## Non-breaking changes

The following may appear inside the current version at any time. They are
announced in the [changelog](/api-docs/changelog) but require no action, so
build your client to tolerate them from day one:

* **New optional request fields** and new response fields. Ignore fields you
  do not know; do not fail on them.
* **New members in error bodies and webhook `data`.** The published OpenAPI
  leaves response, error, and event objects open; configure generated clients
  and validators to allow additional properties.
* **New enum values** where the field is documented as open (for example
  order and mandate states, event types, error codes). Treat an unknown value
  as "other" rather than as an error.
* **New endpoints** and new operations on existing resources.
* **New webhook event types.** A subscription created with `"*"` receives
  them automatically; one created with an explicit list does not. Answer
  `2xx` for a `type` you do not recognise and skip it; never fail the
  delivery.
* **New response headers.**
* **Relaxed validation** — a request that was accepted before stays
  accepted; a request that was rejected before may now succeed.
* Documentation-only changes: descriptions, examples, summaries.

## Breaking changes

These never happen inside a version. They wait for the next version prefix,
with a migration page and the notice period below:

* Removing or renaming a path, field, header, or enum value.
* Changing a field's type, format, or meaning; changing a default.
* Tightening validation so that a previously valid request is rejected.
* Changing which status code or error type an outcome produces.
* Changing authentication, access, or tenant-selection rules.
* Removing a webhook event type, or removing, renaming, or retyping a member
  of its payload.

## API v1 deprecation

With the [initial v2 release](/api-docs/changelog), the Case Management
and Partner v1 APIs become deprecated. They remain available during migration;
no shutdown date has been announced. The v1 contracts are frozen and receive
only security and critical fixes. Their documentation is preserved unchanged under
[Legacy APIs](/api-docs/legacy/overview). Build new integrations against the
current prefixes and move existing ones with the migration pages:

* [Migrate the Case Management API from v1](/api-docs/case-management-api/migrate-from-v1)
* [Migrate the Partner API from v1](/api-docs/partner-api/migrate-from-v1)

The new Mahnservice API uses `/mahnservice/v1/` and is not deprecated.

## Deprecation policy

<Note>
  No endpoint is scheduled for retirement, and no current response carries
  the `Deprecation` or `Sunset` headers described here.
</Note>

When paywise retires a version or an individual endpoint:

1. The retirement is announced in the [changelog](/api-docs/changelog) with
   the date on which the affected operations stop working.
2. A migration page describes what replaces the retired contract, what stays
   the same, and what changes.
3. Affected responses carry a `Deprecation` header from the announcement
   onwards and a `Sunset` header naming the retirement date, so a client can
   detect the notice at runtime instead of relying on someone reading the
   changelog.
4. The notice period is **at least six months** between announcement and
   retirement.
5. Retired pages stay in the documentation, labelled as retired, until the
   last migration window has passed.

Until a deprecation is announced, the changelog is the only signal you need
to watch; once one is, the headers above let your client detect it at
runtime.


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