API Breaking Change Policy

A change is breaking if it can make a working integration stop working without you changing your code. One test settles almost every case:

​

Breaking changes

A change in this list is never applied in place. It ships as a new version of the endpoint, or, for removals, as a deprecation. The version you are already calling keeps its current behavior until the removal date in the deprecation notice.

​

Requests

• Adding a required field or parameter
• Making an optional field required
• Removing or renaming a field we used to accept
• Rejecting input we used to accept, including tighter validation and removed enum values

​

Responses

• Removing or renaming a field
• Changing a field’s type, or making an always-present field nullable or optional
• Changing the meaning of an existing field
• Changing the HTTP status or error code returned for the same condition
• Changing pagination, sort order, or any other documented guarantee

​

Endpoints

• Removing or renaming an endpoint
• Changing its default behavior
• Adding an authentication or permission requirement to an existing endpoint

​

Non-breaking changes

These ship at any time, without a version change:

• New endpoints
• New optional request fields, with a default that preserves current behavior
• New response fields
• New enum values in responses
• New error messages under the same error code
• Accepting input we previously rejected
• Performance, infrastructure, and undocumented behavior

​

What your client must do

The list above holds only for clients that tolerate additive change. Your integration is expected to:

• Ignore response fields it doesn’t recognize
• Accept enum values it hasn’t seen before
• Not depend on field order
• Match on error codes and HTTP status, never on message text
• Not depend on behavior absent from the API reference

A client that does these things can take every non-breaking change we ship without any code change. A client that doesn’t will break on additive changes, and that breakage is not covered by this policy. Behavior not described in the API reference is not covered by this policy.

​

When we make a breaking change

1. It ships as a new version of that endpoint, or as a deprecation naming whatever replaces it — a differently named endpoint, or nothing at all. Either way what you are already calling is unaffected while the window below is open.
2. We publish the migration guide before announcing the deprecation.
3. We announce it in the changelog, in the API reference, on a deprecation page for that endpoint, and by direct notice to customers we see calling the endpoint.
4. The old version is supported for at least 30 days from the announcement. After the removal date it stops answering and returns 404.

​

Exceptions

Ambiguous cases are decided by the API owner, and the default is to treat the change as breaking.

​

Learn more