The version is in the URL path.
There is no version header and no date pinning. Every caller on /api/v1 sees the same behaviour, so there is no per-key version state to track or migrate.

​
What can change within v1

These are additive and can ship at any time. Your integration must tolerate them.
  • New fields on existing responses. Ignore fields you do not recognise rather than failing to parse.
  • New endpoints and new resource families.
  • New optional request fields.
  • New error codes. Handle the codes you care about and fall through to a default that logs the rest. See Error codes.
  • New values in an existing enum, such as a new order status.
  • Wording of an error message. Branch on code, never on message text.
A client that rejects unknown response fields, or that treats an unrecognised enum value as a fatal error, will break on an additive change. Parse permissively on the way in.

​
What will not change within v1

  • Removing a field from a response
  • Renaming a field
  • Changing a field’s type, including the integer minor units convention for money
  • Removing an endpoint
  • Changing the meaning of an existing error code
  • Adding a required request field to an existing endpoint
  • Tightening validation so a request that was accepted becomes refused
Any of those would require /api/v2, served alongside v1 rather than replacing it.

​
Writing a client that survives additive change

1

Ignore unknown response fields

Most JSON parsers do this by default. If you have explicitly enabled strict decoding for responses, turn it off. Strict decoding is right for your own inputs and wrong for someone else’s outputs.
2

Branch on code, with a default arm

Never switch on code without a default that logs code, message and x-request-id. An unrecognised code must not fall through as success.
3

Treat unknown enum values as unknown, not as invalid

A new order status should surface as “a status this client does not recognise”, not crash and not silently map to the closest known value.
4

Do not depend on field ordering or on response byte length

JSON object keys have no meaningful order. Nothing about serialisation is contract.

​
Note on strictness direction

This API rejects unknown fields in requests while asking you to tolerate unknown fields in responses. That is not inconsistent, it is the same principle applied from each side: be strict about what you accept, be liberal about what you tolerate from someone else. A rejected unknown request field tells you about your typo immediately. A tolerated unknown response field lets us add capability without breaking you.

​
Deprecation

If any part of v1 is ever scheduled for removal, it will be announced ahead of time with a migration path, and v1 will keep working through the announced window. Nothing in v1 will disappear without notice.