Versioning & deprecation policy

Versioning

The Partner API is versioned in the URL path: /api/v1/partner.

• Additive, backwards-compatible changes ship within the current major
  version (v1): new endpoints, new optional request fields, new response
  fields, and new webhook event types. Integrations must tolerate unknown fields.
• Backwards-incompatible changes ship under a new major version
  (/api/v2/partner). Examples: removing/renaming a field or endpoint, changing
  a type, tightening validation, or changing default behavior.

Every change is tracked in the Changelog, and the OpenAPI spec
is the single source of truth. CI runs Spectral lint and an oasdiff breaking-
change check on every change to the spec.

Deprecation & sunset

When we deprecate an endpoint or field:

1. It is marked deprecated: true in the OpenAPI spec and annotated in the
   changelog with a replacement and timeline.
2. Responses include standard HTTP headers:
   • Deprecation: true (or an HTTP-date when deprecation takes effect)
   • Sunset: <HTTP-date> - the date after which the endpoint may be removed
   • Link: <docs-url>; rel="deprecation" - migration guidance
3. We provide a minimum 90-day window between announcing a sunset and removal
   for v1 endpoints.

Recommendations for integrators

• Pin to a major version and read the changelog before upgrading.
• Ignore unknown response fields rather than failing.
• Monitor for Deprecation/Sunset response headers and alert on them.