Versioning and backwards compatibility

The API is versioned by path (/v1/...). When we introduce breaking changes, we will increase this version number. We'll of course continually make backward-compatible changes without increasing the version number.

Examples of things we do not consider breaking include:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses. We will occasionally move response fields in the API, and will continue to return the existing field in its previous location, while removing it from this documentation.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings. Strings that are marked as const or enum in this documentation will not change.
  • Adding new EventType or ResourceType enum values for webhooks.
  • Adding new TransactionSource enum values for transactions.