Deprecation Policy

Deprecation Policy

This page explains what we commit to when something in the public API changes, and what you can rely on staying stable.

What counts as a breaking change

A breaking change is anything that could make a correctly-written integration start failing or behaving incorrectly without any code change on your end:

• Removing an endpoint, a field, or a webhook event type.
• Renaming a field, or changing its type or meaning.
• Making an optional request field required.
• Tightening validation on an existing field so previously-accepted requests start being rejected.
• Changing the meaning of an existing status code for an existing situation.

The following are not breaking changes, and can ship at any time without notice:

• Adding a new endpoint, field, webhook event type, or scope.
• Adding a new optional request parameter.
• Adding a new field to a response body or a webhook payload — always write your integration to ignore fields it doesn’t recognize.
• Adding a new enum value to a field you don’t already exhaustively switch on without a default case (see the note below).

Handle unknown values gracefully

Write your integration to tolerate new fields on JSON objects and new values in fields with a fixed-looking set of options (like a status or event type). Treat an unrecognized value as “log it and skip,” not “crash” — that’s what keeps additive changes non-breaking for you, not just for us.

How we announce a deprecation

When we do need to make a breaking change, we deprecate the old behavior before removing it:

1. We announce the deprecation, the reason, the migration path, and the sunset date.
2. Every response from the deprecated route or field is marked with Deprecation and Sunset response headers — see Versioning for the exact header format.
3. The deprecated behavior keeps working, unchanged, until the announced Sunset date.
4. After the Sunset date, the deprecated route returns 404 (or the deprecated field is genuinely removed from the response).

We do not deprecate and remove something in the same announcement — there is always a runway, and the length of that runway is stated in the announcement itself (it scales with how disruptive the change is for integrators).

Webhook event types

The same policy applies to webhook event types: an event type is never repurposed to mean something different. If an event type needs to be replaced, the old one is deprecated (still delivered, on the same schedule as above) while the new one is introduced, and your endpoint keeps receiving whichever types it’s subscribed to for the length of the deprecation window.

Versions

v1 is the only version today. If we ever need to ship v2, v1 does not stop working the moment v2 ships — it follows this same deprecation process, on its own timeline, independent of v2’s release.

Staying informed

• Watch for Deprecation/Sunset response headers in your own logs/monitoring — this is the most reliable signal, since it comes from the exact routes you actually call.
• Deprecation announcements are also published through your usual account channels (release notes / dashboard notice).