Release strategy and workflow

This page contains an overview of how we release API changes.

For non-breaking changes

Backward compatible releases (i.e., non-breaking changes) may involve the following updates to the API request and response schema:

• Adding new optional request fields
• Adding new optional response fields
• Adding a new required field in the response
• Deprecating and sunsetting an optional request field
• Adding a new enum value to an existing field in the request
• Adding a new oneOf object field in the request
• Making a required request field optional

These non-breaking changes will not disrupt your existing integration. We recommend you review the backward compatibility policy and best practices carefully and use the API changelog to track the updates.

For breaking changes

The following workflow explains how we release breaking changes that require you to adjust your integration code.

1. Identifying the change: Our engineering team identifies the updates that may affect your existing integration (e.g., changing an optional request field to required). In this step we scope the release timeline to determine the number of days of advance notice we should provide for partners to incorporate this update into their code.
   
   

2. Initial announcement: The release timeline is updated to announce the upcoming change that requires you to adjust your codebase. This timeline also includes a scheduled date on or after which the new update will be released to production.

   In the sample screenshot below, the release timeline entry indicates that the currently optional eventDetails field will become required after March 11th, 2025. If your code is already sending the eventDetails value in the request then your integration will not be affected by this release. However, if you had previously been treating eventDetails as an optional parameter, after the initial announcement, you would need to start sending its value in each request. This ensures that after March 11th, 2025 your integration will continue to work as expected.
   
   

3. Adjust your codebase: After the initial announcement, you must adjust your code to accept the new update. At this point, your existing integration will continue to work without making any changes. However, we encourage you to start the necessary changes when the initial announcement is made to ensure you can handle the upcoming breaking change.

   In the example above, you have until March 11, 2025 to prepare your codebase and start sending the eventDetails value in the API request. If you haven’t incorporated the changes by then, your API calls will fail.
   
   

4. Final release announcement: After the date mentioned in the initial announcement, the release timeline is updated again to indicate that the update has been released to production. At this point your codebase must already be adjusted to incorporate the new updates.

Note: In the example above, the initial announcement indicated the eventDetails field will be required starting on March 11th, 2025. This means we may release this new update to production on or after March 11th, 2025. The final release announcement (example shown in image below) will indicate that the change has been released to production.