Skip to main content
We are committed to maintaining a stable and predictable API. This page outlines our policy for managing breaking changes and how we communicate them.

​
What is a Breaking Change?

A breaking change is any change that can cause a previously working integration to fail or behave differently. Breaking changes to the API would require updates to an existing integration.

​
Examples of Breaking Changes

​
Requests

  • Removing or renaming endpoints
  • Changing URL paths, HTTP methods, required headers, or authentication requirements
  • Adding a new required request field, or changing field type/format
  • Changing validation rules in a way that rejects previously valid requests

​
Responses

  • Removing or renaming response fields
  • Changing the type or format of an existing field
  • Changing error formats or error codes
  • Changing pagination, sorting, or filtering behavior
  • Decreases to rate limits or quotas that can cause new failures for existing traffic

​
What is Not Considered Breaking

  • Adding optional request fields
  • Adding new response fields
  • Adding new endpoints, event types, or enum values
  • Bug fixes that bring behavior in line with documented expectations
  • Performance improvements
  • Security fixes

​
Compatibility Expectations for Client Developers

To help keep integrations resilient, clients should:
  • Ignore unknown response fields
  • Not rely on field ordering in JSON
  • Handle new enum values gracefully (treat as “unknown”)
  • Rely on status codes and not programmatically parse error strings

​
Versioning Model

Versions are communicated via the URL path or webhook event type:
  • Example (path): /v1/..., /v2/...
  • Webhooks: ...v2
A breaking change is released only in a new major version (e.g., v1 → v2) unless explicitly noted in the “Emergency changes” section of the changelog.

​
Deprecation and Support Windows

  1. Announcement — We will announce breaking changes and new major versions via Changelog and email to technical contacts on file.
  2. Minimum deprecation period — When we deprecate an API version or feature, we will provide at least:
    • 180 day notice for deprecating an endpoint/field/webhook event in the same major version
    • 1 year support overlap for retiring an older major version after a new major version is GA

​
How We Communicate Breaking Changes

Every breaking change announcement will occur via an email newsletter. Updates will also be shown on our changelog. Breaking change announcements will include:
  • What is changing and why, including updated OpenAPI specs
  • Who is impacted
  • Effective dates (announcement date, deprecation start, EOL date)
  • Migration steps and a compatibility/mapping table

​
Migration Support

For each breaking change, we will provide one or more of:
  • Migration guides and example requests/responses
  • Updated OpenAPI schema/specs
  • A sandbox/test environment that supports the new version
  • Direct support via developer-support@theguarantors.com

​
Contact

For questions or migration help, contact developer-support@theguarantors.com.