The API version controls the API and webhook behaviors, such as parameters accepted in requests, and response properties. Your account is automatically set to the latest version when you sign up for Commerce API.

While we try to maintain backward compatibility, we version the API when a change creates compatibility issues. We maintain older versions of the API, which you can continue to use until you are ready to upgrade.

Non-breaking changes

We will release non-breaking changes without introducing new versions. Your code will be able to handle these changes no matter what version it's on. The following changes are non-breaking:

• Adding a new API resource

• Adding a new method to an API resource

• Adding new optional request parameters to existing API methods

• Adding new properties to an existing API resource

• Changing the order of properties in existing API responses

• Changing existing error response codes or messages

• Adding a field to a request or response

• Adding a value to an enum

• Adding new event types

• Changing the length or format of strings, such as object IDs, error messages, and other human-readable strings

See What's new for information on non-breaking changes.

Breaking changes

A breaking change is any change that requires you to apply changes to your application to avoid disruption to your integration. The following changes are breaking:

• Adding new or modifying existing validation to an existing API resource

• Requiring a parameter that was not required before

• Modifying the expected payload of webhooks and async callbacks

• Changing the data type of an existing field

• Changing the supported filtering for existing API resources

• Renaming a field or API resource

• Adding a new feature that will change the meaning of a field

• Removing an existing field or API resource

• Changing the URL structure of an existing API resource

See Changelog for information on breaking changes.