# Versioning

> How the Maxmove API v1 and its webhook payloads are versioned, which changes can happen without notice, and how to build an integration that keeps working.

## API version

The major version is part of the path: every endpoint lives under `/v1`. Breaking changes come as a new major version with a new path. Your integration keeps working on `/v1` until you move it.

Within v1, Maxmove only makes additive changes:

- new endpoints,
- new optional request fields,
- new response fields,
- new webhook event types,
- new error codes.

## Webhook payload version

Every webhook event carries a `version` field. The current version is `2026-10`.

```json
{
  "id": "evt_4c1f9e2b7a3d8c5e6f0a1b2c3d4e5f60",
  "type": "delivery.status_updated",
  "version": "2026-10",
  "created_at": "2026-10-07T09:42:11Z",
  "data": { … }
}
```

`version` changes only with breaking payload changes. Additive changes, such as new fields in `data`, keep the version. See [Webhook events](https://maxmove.com/en/developers/docs/webhooks/events).

## Build for additive changes

- **Ignore unknown fields** in responses and webhook payloads.
- **Handle unknown error codes** by their HTTP status. See [Errors](https://maxmove.com/en/developers/docs/concepts/errors).
- **Ignore unknown event types**, or subscribe only to the events you handle with `events` on the webhook endpoint.
- **Don't depend on field order** in JSON objects.

## Where changes are announced

Changes to the API and webhooks are listed in the [changelog](https://maxmove.com/en/developers/docs/changelog). The [API reference](https://api.maxmove.com/v1/docs) is generated from the API code, so it always shows the current state.

---

Source: https://maxmove.com/en/developers/docs/versioning