Operations

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.

Review changelog Open API reference

Current contract

Custom REST API v1.0, currently in the Beta release stage. One active contract across the published paths under https://app.foxpay.it/api; additive evolutions roll forward on the same v1.0 surface, and any breaking change will move the public surface to a new explicit version boundary.

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.

Runtime deployment rule

API runtime changes in the Foxpay webapp follow the staging-first production rule even when the public docs are allowed to publish directly.

Webapp API changes are merged and deployed to staging before they are promoted to production.
Production deployment is gated against the latest successful staging deployment unless an authorized manual workflow dispatch is used intentionally.
Docs may describe an upcoming contract only when the implementation state is clear; once the runtime ships, the changelog should mark it as deployed.
For contract-impacting changes, verify both `https://app.foxpay.it/api/healthz` and the live docs/OpenAPI surface after production rollout.

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.