# Compatibility policy

The `/v1` in every path is the API version. Lazy keeps `/v1` working for the integration you build
today. This page says which changes can still happen within `/v1`, so your code can tolerate them.

## Changes Lazy may make within /v1

Lazy may make these changes at any time, without a new version. Write your code so it keeps working
when they happen:

- **New endpoints.**
- **New fields in responses**, including in the [error envelope](https://developers.lazyinvoice.co.il/embedded/errors/). Ignore fields
  you do not know.
- **New optional request fields and query parameters.** Requests you send today stay valid.
- **New values in a field that holds one of a fixed set of values.** Handle a value you do not know
  without failing.
- **New error codes.** Handle an unknown code by its HTTP status.
- **New response headers.**
- **Changes to error `message` text.** Branch on `code`, never on `message`.
- **Changes to cursor contents.** [Cursors](https://developers.lazyinvoice.co.il/embedded/pagination/) are opaque; pass them back
  unchanged.
- **Changes to the order of fields** in a JSON object.

Every change is listed in the [changelog](https://developers.lazyinvoice.co.il/embedded/changelog/).

## Changes that need a new version

Lazy does not make these changes within `/v1`:

- Removing or renaming an endpoint, a field, or a query parameter.
- Changing a field's type, or making a response field that is never null nullable.
- Making an optional request field required, or adding a required request field.
- Changing what an existing field or status code means.

A change like this ships under a new version, such as `/v2`, next to `/v1`. Lazy announces it in the
changelog before it ships.