Versioning

The version lives in the path: /api/vendor/v1/.... Everything below describes what we may change without moving to v2, and what we will not.

Not a breaking change

Build so that these never break you:

• A new optional field in a response. Ignore fields you do not recognise.
• A new optional field in a request. Existing requests keep working.
• A new endpoint.
• A new webhook event type. Return 2xx and ignore unknown X-Hizliyo-Event values.
• A new value in an existing enum — for example an additional failureReason. Handle the values you know and fall back gracefully.
• Reworded message text. Branch on errorCode, never on the message.

The most common integration bug

Strict deserialisation that throws on unknown properties. One new optional field and every order fails. Configure your JSON layer to ignore extras before you go live.

A breaking change

These get a new version:

• Removing or renaming a field
• Changing a field's type
• Making an optional field required
• Removing an endpoint
• Changing the meaning of a status or error code

What happens at v2

• v2 is published and documented alongside v1
• v1 keeps working for at least six months
• We tell you the retirement date when v2 ships, and again as it approaches
• Both versions run in parallel; you move when you are ready

Security exceptions

A change required to close a security hole may land faster than the normal notice period. We will explain what changed and why. This is the only case where the six-month promise does not apply.

Operational parameters

Rate limits, timeouts and sandbox behaviour are configuration, not API surface. They can be adjusted with reasonable notice and do not constitute a version change. Limits are per account — see Rate limits.

Staying informed

• Changelog — every change, dated
• Technical notices go to the contact address you registered with us

Keep that address current and pointed at a mailbox someone reads.