Versioning

The version is in the path: /integration/v1.

What stays true inside v1

• A field that exists keeps its name and its type.
• A route that exists keeps its path, its verb and its meaning.
• An error code keeps its number and keeps meaning the same thing.
• A scope string keeps its name.

That last one matters more than it looks: scope strings are stored on the keys merchants have already issued, so renaming one would break every key carrying it. They are treated as permanent.

What can change inside v1

• New fields appear on existing responses. Ignore what you do not recognise; do not fail on it.
• New routes appear.
• New optional request fields appear.
• New error codes appear. Handle an unfamiliar non-zero code as a generic failure rather than crashing.
• Message text is reworded. Never match on message — that is what code is for.

A generated client should tolerate unknown response fields. Most generators do this by default; some can be told to reject them, and that setting will break you on a release that adds a field.

What a breaking change looks like

Removing a field, renaming one, changing its type, or changing what a route does. Those go to /integration/v2 as a new path. /integration/v1 keeps serving while both exist.

Why this version is separate from Bione's

Bione's own apps talk to /v1, and that number moves on Bione's release schedule. Yours does not — /integration/v1 has its own axis so an internal major release cannot move a path your integration depends on.

Deprecation

If a route or field is going away, it is announced on the changelog before it stops working, and it keeps working for the announced period. Nothing is removed from a live version without notice.