Breaking API changes are changes that disrupt the working implementation of our customers. This can happen if we change our endpoints in a way that our customers do not expect them to change. We have a strict policy to never make a breaking change on an published version of our API.
Things we do not consider as breaking changes:
- Adding new API endpoints (e.g.,
- Adding new optional request parameters to existing API endpoints.
- Making a previously required required request parameter optional.
- Adding new property fields to existing API responses.
- Changing the order of property fields in existing API responses.
- Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
Every other API change is a breaking change. This includes (but is not limited to):
- Removing an API endpoint.
- Making a previously optional request parameter required.
- Adding a required request parameter to existing API endpoints.
- Removing or renaming property fields from existing API responses.
- Changing the property field type of existing API responses.
- Changing the property field of existing API responses that was non-nullable as nullable.
- Changing values of an
enumtype. Note that there are a couple of exceptions to this rule: we may add new values to
enums for platforms we support and for currency codes.