Foundations

Versioning

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.