Foundations

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., POST /accounting/bill_credit_applications).
• 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 enum type. 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.