Skip to main content
The API version is part of the URL:
An integration built on a version does not break while that version is supported. When a breaking change is needed, a new version (v2) is released and the old version keeps working for a while.

​
What can change within a version?

The following changes are backward compatible and can be released in the current version without notice. Build your integration to tolerate them:
  • New endpoints
  • New optional request fields
  • New response fields (ignore fields you do not recognize)
  • Different wording of error messages (base your logic on HTTP status codes, not message text)
  • A different order of fields in responses

​
What requires a new version?

  • Removing or renaming a field or endpoint
  • Adding a new required field
  • Changing the type or meaning of a field
  • Making validation rules stricter
  • Changing default behavior

​
Version lifecycle

A version keeps working for at least 6 months after it is marked deprecated.

​
Headers

Responses from endpoints report the supported versions in the api-supported-versions header. When the version you use is deprecated, the api-deprecated-versions header is returned too. Watch this header to detect when you need to migrate:

​
Versions