Versioning for API Methods
Dated versions are used for breaking changes and selected new features.
Some individual API methods have a dated version. Select the version you want as follows:
To use the dated version, you must specify the date in the
api_versionheader parameter in yyyy-mm-dd format. For example: 2023-11-29.To use an API method without a dated version, omit the
api_versionheader parameter.
Versioning of an API method might affect the following:
REST request or response
Webhooks
Behavior or business logic
Nonbreaking Changes
The following changes are generally considered nonbreaking and backward-compatible:
New method or endpoint.
New optional parameter or field in header, request body, response or webhook.
New value in list of values, larger range for a numeric parameter, longer length for a string parameter.
Required parameter changed to optional.
New default value for a parameter.
New error code and message, or updated error message.
New webhook.
Breaking Changes
The following changes are generally considered breaking and might adversely impact clients' code:
Deleted endpoint.
Deleted parameter or changed parameter name in REST request, REST response or webhook.
New required parameter or optional parameter changed to required.
Value deleted from list of values, smaller range for a numeric parameter, shorter length for a string parameter.
Parameter datatype changed.
Changed error code.
Materially different behavior due to a new value in a list of values or other cause that affects the use or functionality of the API.