API Lifecycle and Versioning

To provide you with the best possible product experience, we continuously improve our services. As a result, API changes are inevitable. In some cases, we may need to deprecate or sunset APIs due to security updates, legal requirements, performance improvements, redundancy, or other important reasons.

We understand that breaking changes require effort on your side. That's why we strive to minimize them and support you throughout the transition process.

API Lifecycle Stages

Stage	Description
`Not Active`	Endpoints are defined but not yet available.
`Beta`	Endpoints may change at any time, including breaking changes, with or without prior notice.
`Active`	Stable endpoints with full support. Breaking changes are rare and follow a formal deprecation process.
`Deprecated`	Endpoints remain available but are no longer actively maintained (except for critical security issues).
`Sunset`	The deprecation period has ended and the endpoint is no longer accessible.

Beta

Endpoints in this stage are clearly marked as such in the documentation.
They may change at any time without prior notice.
Feedback is welcome via your usual communication channels with us (e.g., Slack or email).

Active

We may introduce non-breaking enhancements, such as new optional fields.
You'll be notified of changes through release notes.
If we introduce breaking changes (e.g., removing or making fields mandatory), we’ll follow the deprecation process outlined below.

Deprecated

Deprecated endpoints are clearly marked and, where possible, we suggest alternatives.
We provide at least six months' notice before removing functionality or introducing breaking changes.
Exceptions apply in cases of legal, security, or third-party requirements, where less notice may be given.
Pliant is not liable for issues arising from the continued use of deprecated APIs.

Important Notes

All breaking and non-breaking changes are announced via our regularly updated API changelog.
In case of breaking changes, we will proactively contact you to coordinate and support migration.

Best Practices

We strongly recommend including the Pliant-API-Version header with every API request. While it may be tempting to rely on default behavior, explicitly setting the version ensures your integration remains stable and predictable over time. This practice:

Prevents unexpected breaking changes - Your integration won't be affected when new API versions are released.
Ensures consistent behavior - All your API calls will use the same version, eliminating version-related inconsistencies.
Simplifies debugging - When issues arise, you'll know exactly which API version is being used.

Without an explicit version header, your requests may default to an older version, potentially introducing breaking changes into your production environment without warning.

Make it a standard practice to include Pliant-API-Version: [version] in all your API calls.

Example:

Pliant-API-Version: 2.1.0

Pliant-API-Version: 2.0.0