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 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 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.

1
2
3
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), which is sent before the API sees your request, and the 400 for an unsupported version, because no version was served.

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.