Versioning and deprecation
What ShopEazy promises will not break, and how deprecations are announced.
Both APIs are versioned under /v1. This page is the promise.
The promise
- v1 only grows. A contract changes only by adding: a new operation, an optional parameter or request field, a new response field, enum value or error code. Nothing is removed, renamed, retyped or made required, and no existing behaviour changes meaning.
- Deprecate before you remove. Anything that is going away is first marked deprecated, with the date it was deprecated and a sunset date at least 90 days later. It keeps working, unchanged, until then.
- Headers tell you. Every response from a deprecated operation, errors included, carries two headers.
- Breaking changes ship under a new version. Removing something, or changing what it means, ships as
/v2, beside v1, never inside it. The one exception is a correction nobody can have relied on, such as a security fix.
The Merchant API is in Beta. It follows the same policy, and it is still gaining operations quickly, so read the changelog when you upgrade.
Write a tolerant client
Because v1 only grows, your client must not break when it sees something new:
- Ignore fields you do not know in a response, and allow extra fields in an error body.
- Do not close an enum. A new value can appear, for example a new
typeon a notification. Ignore one you do not know. - Treat an unknown error
codeas its status class. The error codes are an extensible list. See Errors.
The deprecation headers
Deprecation: @1792627200
Sunset: Mon, 01 Feb 2027 00:00:00 GMT| Header | Meaning |
|---|---|
Deprecation | When it was deprecated, as @ and Unix seconds (RFC 9745). Here, 22 October 2026 |
Sunset | When it may stop answering, as an HTTP date (RFC 8594). Here, 1 February 2027 |
Watch for them in your client logs. In the OpenAPI specs a deprecated operation or field is marked deprecated: true.
Deprecated today
The old Storefront API paths
The Storefront API lives under /v1/store. Before that it answered at /v1/<resource>, for example /v1/products and /v1/orders. Those old paths keep answering, unchanged, until 1 February 2027, with Deprecation and Sunset headers. Move to the /v1/store/... paths. GET /v1/store has not moved.
The typed client has a paths option for the switch. See Storefront client.
The pre-paging list fields
Deprecated on 22 October 2026, sunset on 1 February 2027.
Seven Storefront API list operations still answer their old wrapper fields beside items and nextCursor: products, services, kits, policies, orders, bookings and members, each with count. Use items and nextCursor instead. Until the sunset the old fields are sent exactly as before. After it they may be removed. The operations themselves are not deprecated. Every response from these seven carries the headers above.
See Pagination.
Client versions follow the specs
@shopeazy/storefront-client and @shopeazy/merchant-client have the version of their API's contract, without any pre-release tag. A new operation or optional field is a minor bump. A fix or a description change is a patch. A breaking change waits for a new major version.
Where to read changes
See the Changelog.