API Reference
API StatusGet API KeysRoadmapHelp

Versioning

Keep track of changes and upgrades to the API

Your API version controls the API and webhook behaviour you see (for example, what properties you see in responses, what parameters you’re permitted to send in requests, and so on). When a breaking change is introduced to the API, a new semantic version is released. To avoid breaking your code, we don’t change your version until you’re ready to upgrade.

Backwards Compatible Changes

We consider the following changes backwards compatible:

  • Adding new API resources/endpoints.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Adding new response codes
  • Adding new enum values
  • 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.
  • Adding new webhook event types.

Upgrading your API version

If you’re running an older version of the API, upgrade to the latest version to take advantage of new functionality or streamline responses so the API is faster for you. Upgrading your API version will affect:

  • The API calls you make without a version in base URL path: the parameters you can send and the structure of objects returned.
  • The structure of objects sent to your webhook endpoints

When performing an API upgrade, make sure that you specify the API version that you’re integrating against in your base URL path.

👍

Current API Version

Our current stable version is v1 (main).

🚧

Deprecation Notice Period

Between the date of announcement and deprecation, there are 180 days for you to upgrade your code. If a change is not backward-compatible, then it is your responsibility to upgrade your code within the deprecation notice period.

❗

Alpha API Version

Changes made within alpha API versions are not subject to our versioning policy and will continue to have breaking changes until they are made available to the general public as a stable version. Reach out to our support team before using non-stable API versions.