Interface Contract Evolution and Deprecation Policy

The Integration Hub defines a harmonised interface specification that integrators implement in their adapter layer. This specification constitutes a shared contract between Toqio and all active integrators. Because changes to this contract have direct implementation implications for every adapter in production, Toqio manages interface evolution through a structured process of classification, communication, and grace periods rather than through parallel versioning infrastructure.

This document describes how Toqio introduces changes to the harmonised interface, how those changes are communicated, and the obligations and timelines that both Toqio and integrators are expected to uphold.

Change classification

Not all changes to the interface specification carry the same risk. Toqio classifies every change into one of two categories before it is announced, as the category determines the communication and grace period requirements that apply.

Non-breaking changes

Changes that extend the contract without invalidating existing conformant implementations. Integrators are not required to act, though they may choose to adopt new capabilities.

Examples:

Addition of new optional fields to existing request or webhook payloads
Introduction of new webhook types not previously defined
Addition of new optional endpoints to the harmonised interface specification
Expansion of existing enumeration values with new members (integrators must implement tolerant readers — see Tolerant Reader principle)

Non-breaking changes are communicated proactively but do not carry a mandatory grace period obligation.

Breaking changes

Changes that require integrators to modify their adapter implementation to maintain conformance and avoid service disruption.

Examples:

Addition of new mandatory fields to existing request or webhook payloads
Removal or renaming of existing fields
Changes to field types, formats, or enumeration values that alter existing semantics
Removal or restructuring of existing endpoints in the harmonised interface
Changes to authentication or security requirements (see Authentication)
Changes to error response structures documented in Error Management

Breaking changes are subject to the full deprecation and grace period process described below.

Deprecation process

When a breaking change is identified, Toqio initiates a formal deprecation process before the change takes effect. The process involves collaboration between Technology, Product, and Delivery teams to assess technical feasibility and integrator impact prior to any announcement.

Process steps

1. Internal assessment The change is evaluated internally to determine its impact severity (Low, Medium, or High) and the corresponding grace period. This assessment considers the breadth of integrators affected, the complexity of the required adapter changes, and any regulatory or contractual dependencies.

2. Official announcement The change is officially announced to all active integrators and relevant stakeholders simultaneously. The announcement includes:

A precise description of what is changing and why
The impact classification
The date from which the grace period begins (the announcement date)
The date after which the deprecated behaviour will no longer be supported (the end-of-support date)
Guidance on what integrators need to change in their adapter implementation
Where applicable, the specification of the replacement behaviour

3. Grace period The grace period begins on the announcement date. During this period, the existing behaviour remains fully supported alongside the new behaviour where technically feasible. Integrators must complete their adapter updates before the end-of-support date.

4. End of support After the end-of-support date, the deprecated behaviour is no longer guaranteed. Integrators that have not completed their adapter updates by this date may experience service disruption.

Grace periods

Grace periods are determined by the impact severity of the breaking change, as assessed during the internal evaluation phase. The following reference periods apply:

Impact severity	Definition	Grace period
Low	Limited scope — affects a small number of integrators or a non-critical path of the interface	1.5 months
Medium	Moderate scope — affects multiple integrators or a commonly used interface path	2.5 months
High	Broad scope — affects all or most integrators, or a critical path such as transaction processing or compliance flows	4 months

These periods represent the minimum committed notice from the official announcement date. Where circumstances allow, Toqio aims to provide additional time beyond the minimum.

The grace period is designed to allow integrators to complete a full development and certification cycle within their own release cadence. Integrators experiencing exceptional constraints should engage Toqio as early as possible after the announcement to discuss their specific situation.

Communication channels

Breaking change announcements and deprecation notices are delivered through communication channels established during the onboarding process. The specific channels are defined based on the operational needs and conditions of each integration, and may include both technical and business stakeholder contacts.

Integrators are responsible for ensuring that the contacts registered during onboarding remain current, and that announcements are routed to the appropriate technical teams within their organisation.

Non-breaking changes are communicated through the same channels and are also reflected in the interface specification changelog, which integrators should monitor as part of their ongoing integration maintenance.

Tolerant reader principle

Regardless of change classification, all adapter implementations should be designed according to the tolerant reader principle: the adapter must not fail when it encounters fields or enumeration values it does not recognise. Unknown fields should be safely ignored, and unknown enumeration values should be handled gracefully rather than treated as fatal errors.

This design principle is a prerequisite for non-breaking changes to be genuinely non-breaking in practice, and significantly reduces the operational risk associated with interface evolution for all parties.

Integrator obligations

Active integrators are expected to:

Monitor announced changes through the established communication channels
Assess the impact of each breaking change on their specific adapter implementation promptly after announcement
Complete adapter updates and any required internal certification within the applicable grace period
Engage Toqio proactively if a grace period cannot be met due to circumstances outside their control
Maintain adapter implementations that conform to the tolerant reader principle at all times

Toqio's delivery team is available throughout the grace period to provide technical guidance and support for integrators undertaking adapter updates.