Compatibility & changelog¶
What you can rely on when you build on Ziex Try-On, and what has changed. Read this page before you pin a version and again when you plan an upgrade.
Compatibility policy¶
The API: /api/v1¶
Within /api/v1 the API changes additively only:
- New optional request fields, new response fields, new headers and new endpoints may appear at any time. Write your client to ignore what it does not know.
- A new error code appears only for a new condition. The error envelope and the meaning of every existing code never change. See Errors.
- Tightening a documented limit or timeout is a breaking change. Loosening one is additive. See Limits.
- Removals and renames happen only in a new major version,
/api/v2.
The widget¶
- The widget is one URL,
https://api.ziex-tryon.com/embed/tryon-embed.js.TryOn.versionis a semantic version. - Within a major version, options and events are additive: new optional options and new events may appear, existing ones keep their meaning. See the Widget reference.
- A breaking change of the widget is published at a new address,
/embed/v2/. That address is reserved and does not exist today.
Frozen in version 1¶
These parts will not change within version 1, because other code (a plugin, a loader, a CSS rule) reads them:
| What | Frozen as |
|---|---|
| The pickup slot | The sessionStorage key ziex-tryon:attempt: followed by the FNV-1a 32-bit hash of the publishable key, as 8 hex digits |
| The pickup record | Its shape, v: 1 |
| The ready flag | html[data-tryon-ready], with the value result or error |
The ready event |
Its data {job_id, kind, background} |
| The loader | ZiexTryOn.hasPending(pk) and ZiexTryOn.load([scriptUrl]) |
See Lazy loading and pickup for how a plugin uses them.
Deprecation¶
Anything we stop supporting is announced on this page at least 90 days before it is removed.
The machine-readable specification¶
The OpenAPI document is at https://api.ziex-tryon.com/api/v1/openapi.json. Its info.version is the version of the
specification (now 1.1.0) and info.x-changelog lists the changes of each version. The rendered pages are in the
API reference.
Changelog¶
API specification¶
1.1.0 - 2026-10-26¶
The first published specification. It describes every error status with its codes, the request and response headers,
the capabilities document and the webhooks. This is the same entry as info.x-changelog in the OpenAPI document.
Widget¶
1.2.0 - 2026-10-23¶
When the server answers 503 with the code OVERLOADED, no job exists and nothing was charged. The widget now sends
the POST again with the same Idempotency-Key, up to 3 times within 60 seconds, and shows a waiting message. See
A busy server and Limits.
1.1.0 - 2026-10-23¶
A new design of the window. New options theme, accent and launcherPosition. See the
Widget reference.