Current contract mode
The public API currently operates on one active contract across the published paths.
Versioning and deprecation
Foxpay publishes additive updates on the current public contract and uses documented deprecation windows for breaking changes. Merchants should treat the changelog and direct support communication as the authoritative sources for lifecycle updates.
Deprecation window
Breaking removals or changed semantics are communicated with a minimum 90-day deprecation window.
Communication surfaces
Changes are reflected in the docs, the changelog, and merchant communication channels.
Documentation deployment rule
A docs change is complete only after the production docs workflow has deployed it and the live site has been verified.
- Local `type-check`, `lint`, and `build` are required before publishing material docs changes.
- Pushes to `main` must complete the production docs deployment workflow successfully.
- After deployment, verify `https://docs.foxpay.it/healthz` and the affected public page or OpenAPI spec URL.
- If the API reference changes, verify the live `https://docs.foxpay.it/openapi/foxpay-openapi.json` contract, not only the rendered page.
- Do not mark a docs update as shipped while the deployment workflow is queued, running, failed, or unverified.
Lifecycle policy
- Additive changes may ship on the current public contract when they do not alter existing behavior.
- Breaking changes are communicated with a documented deprecation period before removal or semantic change takes effect.
- Deprecated fields or endpoints remain available for at least 90 calendar days after public announcement, unless a security or compliance issue requires accelerated action.
- Major breaking evolutions should introduce an explicit version boundary instead of silently mutating the published surface.
What counts as breaking
- Removing an endpoint, field, or event already available to merchants.
- Changing field meaning, authentication requirements, or webhook signature behavior.
- Changing success or failure semantics in a way that breaks existing integrations.
- Changing polling or webhook expectations without preserving compatibility during migration.
What is additive
- New optional fields.
- New endpoints that do not alter current behavior.
- Additional examples, guides, and clarifications.
- Additional webhook event types that are explicitly additive and documented as such.