API Versioning
Version-in-path policy, deprecation timeline, and breaking change rules for the 505pay API
API Versioning
505pay uses a version-in-path strategy. The current stable version is v1.
Version in path
The API version is the first segment of every endpoint path:
https://sandbox.505pay.link/v1/payments
https://api.505pay.link/v1/me
https://api.505pay.link/v1/tokenWhen a new major version is released, it is served at a new path prefix (/v2/...) while the previous version continues to operate at its existing prefix. You can migrate at your own pace within the deprecation window.
What constitutes a breaking change
Breaking changes require a new major version (v1 → v2). The following are always treated as breaking:
- Removing an endpoint
- Removing a required or optional request field
- Removing a response field
- Changing the type or format of an existing field
- Changing the semantics of an existing status code
- Changing stable error code strings
- Altering pagination envelope field names
The following are not breaking changes and may be introduced without a version bump:
- Adding new optional request fields
- Adding new response fields (your code should ignore unknown fields)
- Adding new endpoints
- Adding new error codes
- Expanding enum values (unless you do exhaustive matching — avoid this)
- Performance improvements with identical observable behavior
Design your integration to ignore unknown JSON fields. This allows 505pay to add new response fields without requiring changes on your end.
Deprecation timeline
| Phase | Duration | Action |
|---|---|---|
| Announcement | Day 0 | Deprecation notice published in changelog and docs; Sunset header added to deprecated responses |
| Active deprecation | 6 months | Old version remains fully functional; Deprecation response header warns on each call |
| End of life | Day 180+ | Old version returns 410 Gone for all endpoints |
The minimum notice period is 6 months from announcement to end of life. Critical security fixes may shorten this window with advance notification.
Deprecation headers
During the active deprecation period, responses from a deprecated version include:
Deprecation: true
Sunset: Sat, 30 Nov 2026 00:00:00 GMT
Link: <https://docs.505pay.link/docs/guides/versioning>; rel="deprecation"Monitor these headers in your API client to detect upcoming deprecations before they affect your integration.
Current versions
| Version | Status | End of life |
|---|---|---|
v1 | Current (stable) | Not scheduled |
Migration guidance
When a new version is released:
- Read the changelog for the new version — it lists all breaking changes and their replacements.
- Test your integration against the new version in the sandbox (
https://sandbox.505pay.link/v2/...). - Deploy the updated integration before the old version's
Sunsetdate. - Monitor the
DeprecationandSunsetresponse headers in your logging pipeline.
Changelog
The full API changelog is maintained at docs.505pay.link/docs/changelog. Subscribe to release notifications via the developer dashboard.
Was this page helpful?