Versioning and stability
What v1 promises, what changes in SDK 0.x, and how deprecations will work.
The API: /v1#
/v1 is the current public API version. Within v1 we only make additive changes: new endpoints, new optional request fields, new response fields, and new values for values the API returns (such as a new payment status or event type). A breaking change — removing or renaming a field, endpoint or value, making an optional request field required, or changing a type — requires a new major API version (/v2) or an explicit, announced deprecation process. We do not promise a support timeline for old versions yet.
Because v1 can gain new values, write clients that tolerate them: keep a default branch when you switch on a status, channel, method or event type. The official SDKs already do this — an unknown value is passed through instead of crashing. Requests stay strict: sending a value the API doesn't know is rejected.
The SDKs: 0.x#
SDK packages follow their own semantic versioning and are 0.x: the package's API may still change between minor versions while we learn from real use. That is separate from the REST contract: an SDK release never changes what /v1 means, and /v1 compatibility does not depend on which SDK version you use. Pin an exact SDK version and read the changelog when you upgrade.
The docs#
/v1 documents API v1, whichever SDK version you use.
Deprecations#
Nothing is deprecated today. When something is, we will: mark it deprecated in the API reference and changelog, add a notice in these docs, send a Deprecation response header where useful, and only announce a sunset date once a real timeline exists. We won't invent dates.