The following guide sets out TrusTrace's API versioning policy. 


TrusTrace uses an API versioning policy to support the evolution and improvement of our services without impacting our current clients' integrations. It also creates a continuous and predictable release pattern for our API. 

How we version 

TrusTrace introduces new changes to the API in 2 ways depending on the changes being implemented: 

  • a minor/patch version 
  • a major version 


When TrusTrace releases a new API version,  

  • Changelog between the “Existing” version and “Newly released version” are shared 
  • Will always ensure that the Existing API’s work without any impact due to the changes released in the new version 
  • Choose to upgrade to gain access to new features any time 

We strongly recommend upgrading to the “Newly released version” to take advantage of the new functionality and optimize it for the best user experience. 

Check TrusTrace API documentation for the list of API versions supported. 

Minor/Patch version releases 

TrusTrace will release a minor/patch API version when the changes being introduced are considered backwards compatible, i.e., additive changes, and can work without a need to upgrade the brand’s integration code. For example: 

  • Addition of new response fields 
  • Addition of new endpoints 
  • Changes to error messages (Not format) 
  • New optional request fields or parameters 
  • New required request fields that have default values. 

Minor versions are released more frequently and contain incremental changes to the API. 


Major version releases 

TrusTrace will release a major API version if any of the changes being introduced are backwards incompatible. In this case, brands will have to update their integration code to use the new major version released. 


Major versions are released less frequently. For example: 

  • Breaking Changes in Schema (data model). 
  • Changes in behaviour / Business logic of existing fields / API. 
  • Addition of a new required field/parameter (without default value). 
  • Adding a new or changing an existing validation to an existing resource. 
  • Changing the name or data type of an existing input/output field. 
  • Removal of an existing input parameter (whether required or optional). 
  • Removal of a response value. 
  • Deprecation of an end point. 
  • Removing or renaming the URL of an endpoint. 


Upgrading your API version 

Brands can choose to upgrade their integration to a newer API version at any time. Before upgrading, please refer to the changelogs for the changes in the API.  


Support timelines and deprecation 

All our API versions are supported until a deprecation notice is issued. Deprecation notices will give brands at least 6 months to migrate to a newer API version. Once an API is removed, any request to it will result in 404 error.  


Deprecation notices will contain: 

  • What is being deprecated 
  • When it will come in effect 
  • Changelog between the “about to be deprecated” version and “version to upgrade to”, that can be leveraged to update the integration code  


Deprecation notices will be available: