API and app versioning

API path versions and Marketplace app versions solve different problems. The current public HTTP contract is /api/v1; each Marketplace app also publishes reviewed semantic versions.

API v1

Only the eleven documented operations belong to the current API v1 contract. Internal tables, RPCs, schemas, and routes are unversioned implementation details from an external developer's perspective. Do not bind to them.

App versions

Each app version has its own exact redirect URIs, requested scopes, webhook declarations, release notes, review state, and publication state. Review and approval apply to that exact version. Existing installations remain pinned until a merchant performs a supported upgrade or reauthorization action.

Compatible changes

The platform may clarify documentation or add backward-compatible optional response fields. Apps should ignore unknown fields and must not rely on undocumented ordering. A new required scope, removed field, changed meaning, or incompatible behavior requires explicit governance rather than a silent v1 change.

Deprecation governance status

Formal notice periods, sunset policy, and compatibility-support windows are PLANNED. No public deprecation date is currently promised. Until governance is published, the changelog is the authoritative public change record and the platform must not claim a policy it has not adopted.

Migration guide status

Migration guides are PLANNED because there is no historical public API version to migrate from. A guide will be published when an actual compatible migration path exists; future content must not invent versions or dates.