As we continue to expand and enhance our APIs, we recognize the importance of stability and transparency for your integrations. Our API versioning policy ensures that every change is carefully evaluated and clearly communicated, keeping you informed at all times.

To help you understand how changes may impact your integration, we categorize updates as breaking changes or non-breaking changes.

​
Breaking Changes

When a change qualifies as a breaking change, we introduce a new API version and provide a deprecation date, giving you time to transition to the new API version smoothly. These changes will be documented in the Release Notes and Deprecation Notices.

​
Non-Breaking Changes

When a change qualifies as a non-breaking change, you don’t need to do anything. Your integrations will continue to function as normal while maintaining backward compatibility. These changes will be documented in the Release Notes to keep you informed of new features and improvements.

The table below outlines what constitutes a breaking change versus a non-breaking change:

Change TypeBreaking Change?
Removing or renaming a property in the request or response.Yes
Changing a property’s type.Yes
Changing an API’s endpoint URL.Yes
Altering response behavior for the same request.Yes
Changing the paging mechanism.Yes
Adding a new property to the request or response.No
Adding a member to an enumeration.No
Updating an error code.No
Changing the order of properties in the request or response.No

​
Versioning Strategy

Our versioning strategy ensures smooth transitions and backward compatibility by clearly defining how updates are managed.

​
APIs

New API versions are included in the endpoint URL using the following format:

https://api.example.com/v{version_number}/{service}/{param_value}

For example, version 2 of the Create Checkout Session API:

https://api.example.com/v2/create-checkout-session/1000

​
Personalization API

The Personalization API response includes a version field, enabling integrations to adapt dynamically without modifying request URLs.

For example, version 2 of the Personalization API will look like:

{  
  "version": 2,  
  "status": "valid",  
  "profileFrameId": "123456",  
  ...  
}

​
Deprecations

We provide a 6-month deprecation notice before retiring an API, giving you sufficient time to adopt the new version. During this period, the existing API version will continue to function as normal. Afterward, it will no longer be supported or accessible. Towards the end of the API lifecycle, our development and customer success teams will notify you to assist with a smooth transition.

​
Communication & Updates

  • See the Release Notes for a list of all the latest updates.
  • See the Deprecation Notices, detailing APIs scheduled for deprecation and their deprecation dates.