Details on API and Webhook versioning and backward compatibility


  • Changes may be made to any of our APIs or Webhooks without a change in version number, provided the change follows our backwards compatibility guidelines (see below).
  • Different versions will be managed via a HTTP header indicating the version of the API that the client is using.
  • Requests with no version number, or an unmatched version number, will be treated as version 1.0 requests.

Backwards Compatibility

The following changes are considered to be backwards-compatible:

  • Adding new API endpoints; new endpoints are independent.
  • Adding new Webhooks; new Webhooks are independent.
  • Adding new Webhook event parameters.
  • Adding new optional request parameters to existing API calls.
  • Adding new response properties to existing API calls. You should pay particular attention to this point if you are mapping your JSON responses to another programming language construct.
  • Changing of the property order in existing API responses.
  • Changing the length of object IDs (object IDs will never exceed 255 characters).
  • Changing the messages returned by validation or other error messages.
  • Output Encoding Rules are applied to some services and will be applied to all services in the future.