Supported breaking changes
This section lists the breaking changes we will release to the APIs, along with the code change time period and guidelines to prepare for the update.
The following are the API updates that will require you to adjust your integration code.
| API update | Code change window | Action to take |
|---|---|---|
| Making an optional field (in the request or response schema) required. | >= 21 days | After the initial announcement, adjust your integration code to treat the field as required. If the update is made to the request schema, then you’ll need to start sending the field in the API requests. If the update is made to the response schema, ensure that your integration is able to receive this new field. |
| Releasing a new required field in the request or response schema. | >= 21 days | As mentioned in the backward compatibility policy, the new field will be released initially as an optional parameter. After the initial announcement is made on the release timeline, keep track of its release using the API changelog. Once the API changelog is updated indicating that the field is released as optional, adjust your integration code to incorporate this new field before the code change time period ends. |
| Deprecating and sunsetting a required field in the request or response schema. | >= 21 days | After the initial announcement, the deprecated field will be made optional. Remove this field from your codebase anytime before the sunset date mentioned in the initial announcement. |
| Deprecating and sunsetting an enum value in the request or response field. | >= 21 days | After the initial announcement, stop using this deprecated enum value in your code. The integration code must be updated before the sunset date mentioned in the initial announcement. |
| Releasing a new enum value for a field in the response schema. | >= 21 days | After the initial announcement, the API will be updated to include the new enum value within the field. Adjust your integration code to start expecting the new enum value before the code change time period ends. |
Releasing a new oneOf reference object in the response schema. | >= 21 days | After the initial announcement, the API will be updated to include the new oneOf reference object within the field. Adjust your integration code to start expecting the new oneOf object reference before the code change time period ends. |
Note: The code change time period mentioned in the table above indicates the time provided between the initial and final announcements. During this time, partners must adjust their integration to accomodate the API change.