> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theguarantors.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Breaking Change Policy

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](mailto:developer-support@theguarantors.com)

## Contact

For questions or migration help, contact [developer-support@theguarantors.com](mailto:developer-support@theguarantors.com).