Versioning

Versioning is how Chargee evolves the Order API without silently breaking clients that already work.

Path-based versions

The business API lives under a versioned URL prefix. The current major version is v1. Clients should always address that version explicitly. Relying on unversioned shortcuts is fragile; the stable contract is the versioned path.

A few operational URLs (health and the OpenAPI document) sit outside the versioned prefix. They are for liveness and documentation discovery, not for order business logic.

What “compatible” means while v1 is current

Chargee may add fields, clarify messages, or introduce new capabilities under v1 without calling it a new major version, as long as existing well-behaved clients keep working. Well-behaved means: you send only known fields where validation is strict, and you ignore unknown fields you do not understand when reading responses.

Breaking changes — removing or renaming fields, changing auth in an incompatible way, or reshaping core resources — belong in a future major such as v2. When that happens, v1 and v2 can coexist for a migration window; sunset details would be announced separately.

Why this matters for integrators

Pin your client configuration to v1 and regenerate or review clients when Chargee publishes contract updates. Do not assume that “whatever /api redirects to today” is a permanent alias for your production traffic. Treat the version in the path as part of your integration contract, the same way you treat authentication and ownership rules.