> Part of [WHCC Developer Documentation](https://www.whcc.com/developer/llms.txt)

# API Versions

Version 1.4 · Updated 2026-10-09

You choose an API version with the `WHCC-API-Version` request header, a month written `YYYY-MM`. The current version is `2026-10`. The header applies to the commerce, catalog, discovery and [fulfillment](https://www.whcc.com/developer/docs/api/fulfillment/index.html.md) routes. URLs don't change: `v1` in the path is the API generation, not the version, and new versions arrive as new months in the header.

## Versions

- **No header.** You get your account's default version, currently `2026-10`.
- **A listed version.** The request is served as that version.
- **Any other value.** An unlisted month, `v1`, `latest`, an empty value, or anything else returns `400` before the route runs. The [body](https://www.whcc.com/developer/docs/api/errors/#example-400-version) names the value you sent and lists the versions that exist in `supportedVersions`.

WHCC creates a new version only for a breaking change, and `2026-10` keeps working as it does today.

## Sending the header

Send `WHCC-API-Version: 2026-10` on every request, including requests to the links a response returns: `actions`, `self` and `actions.fulfillment` carry no version. The header, not the URL, keeps you on your version, so a later change to your account's default can't change what you get.

```shell
curl https://apis-stage.whcc.com/api/v1/catalog/products \
	-H "Authorization: Bearer <YOUR_API_KEY>" \
	-H "WHCC-API-Version: 2026-10"
```

## Response headers

Every response from the API carries these headers, errors included, with two exceptions: a key error from the gateway (the [`{ "message": … }` body](https://www.whcc.com/developer/docs/api/errors/#gateway-errors)), which is sent before the API sees your request, and the `400` for an unsupported version, because no version was served.

- **`WHCC-API-Version`**: The version served.
- **`WHCC-API-Version-Latest`**: The newest version.
- **`Vary`**: `WHCC-API-Version`, because the response depends on that request header.
- **`WHCC-API-Version-Requested`**: What your header asked for. Present only when your request sent the header.

## How this API changes

We add to the API without notice: endpoints, response fields, optional request parameters, values in an enumerated field, and entries in `actions`. Additions reach every version at once. So that they never break your integration, your client must:

- ignore response fields it does not recognise;
- handle a value it does not recognise in an enumerated field without failing;
- not depend on the order of properties in an object;
- treat ids, cursors and tokens as opaque strings, with no fixed length or format;
- follow the URLs we return in `actions` and `self` as given, and not build or parse them;
- ignore entries in `actions` it does not recognise.

A request body containing a field we do not recognise is rejected. Query parameters we do not recognise may be rejected or ignored, depending on the endpoint, so do not send them.

WHCC makes a best effort not to break a version that exists. A breaking change is one that could make a client fail even though it follows this page and the reference documentation: removing or renaming a field or endpoint, changing a field's type or format, making a field that was always present nullable, adding a required parameter, tightening validation, changing a default, or changing the HTTP status or problem `type` returned for an existing condition. A change like that arrives as a new dated version you move to when you choose, by changing the header.

Three things fall outside that:

- **Error text.** The `title` and `detail` of an error are written for people and may change. Rely on the HTTP status and the problem `type`.
- **Limits.** Rate limits, response times and how long a cursor stays valid may change.
- **Security fixes.** We may tighten behaviour in every version, including an existing one, to close a security problem.