> For the complete documentation index, see [llms.txt](https://support.ordereazi.com/central/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.ordereazi.com/central/developers/api-versions.md).

# API versions

How to choose an OrderEazi API version with the x-api-version header, and what version 2.0 adds.

Some endpoints changed shape over time, such as clients getting structured addresses. OrderEazi keeps both shapes, as API versions, so existing integrations keep working. You choose the version for each call with a header, not in the address.

### How to choose a version

Send the `x-api-version` header with every call. Use `2.0`, the current version, for new integrations. `1.0` is the first version, and calls without the header are treated as `1.0`.

```bash
curl https://yourcompany.ordereazi.com/api/ping \
  -H "X-OrderEazi-Key: YOUR_API_KEY" \
  -H "x-api-version: 2.0"
```

The address is the same for both versions, such as `/api/client/list`. Don't put the version in the address: `/api/v2/client/list` returns a `404`. Addresses starting `/api/v1/` or `/api/v2/` are only for the [API reference](/central/developers/finding-your-api-reference.md).

Each response has an `api-supported-versions` header, listing the versions that endpoint supports.

### What version 2.0 adds

Every version 1.0 endpoint is also in version 2.0. Version 2.0 adds these:

* **Client addresses:** `/api/client/address`, to read, add, change, and delete a client's addresses.
* **End Users:** `/api/end-user`, with their addresses and contacts.
* **Receiving Purchase Orders:** `POST /api/purchaseorder/receive`, to receive stock against a Purchase Order.
* **Product additional codes:** `/api/product/{sku}/additionalcode`, for a product's other codes, such as a supplier's code for it.
* **Rounding:** `/api/rounding/config`, `/api/rounding/calculate`, and `/api/rounding/reconcile`, to round amounts the same way OrderEazi does.
* **Warehouses:** `POST /api/warehouse`, to create a warehouse.

These endpoints return a different shape in version 2.0:

* **Clients and suppliers:** Addresses are objects, `PostalAddress` and `ShippingAddress`, instead of address lines. Clients also have `Addresses` and `DocumentLanguage`.
* **Orders:** `POST /api/order/{channel}` also takes `Description`, `KeyValues`, `DueDate`, `DiscountValue`, collection shipping, and structured addresses.
* **Organisation and warehouses:** The organisation detail and warehouse responses have more fields. The [API reference](/central/developers/finding-your-api-reference.md) lists them.
* **Client lookups:** A client that doesn't exist returns a `404` in version 2.0 and a `400` in version 1.0.

### When a version isn't supported

Calling an endpoint that's only in version 2.0 without `x-api-version: 2.0` returns a `400`, with an `UnsupportedApiVersion` error. This error doesn't use the usual response envelope. Add the header and call again.

### Related pages

* [Finding your API reference](/central/developers/finding-your-api-reference.md): every version 2.0 endpoint
* [Responses, errors, and warnings](/central/developers/responses-errors-and-warnings.md): the response envelope