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.
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.
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.