- What counts as breaking vs non-breaking
- How Suki handles deprecations
- Where to find deprecation and removal notices
- How to plan migrations
What’s a breaking change?
Breaking changes
Require updates to your integration:
- Removing or renaming endpoints, fields, or parameters
- Changing data types or formats
- Making optional fields required
- Tightening validation rules
- Changing default behavior in a way that affects existing clients
Non-breaking changes
Work with existing code:
- New endpoints or optional fields
- New optional parameters
- Performance improvements
- Documentation clarifications
The deprecation timeline
Unlike a fixed quarterly removal schedule, Suki sets deprecation timelines per change. Your partnership team is the primary channel for migration dates, rollout guidance, and org-specific impact. When we need to make a breaking change, we follow this process:Announce the deprecation
We mark the feature as deprecated in documentation, changelogs, and (for APIs) in the reference with a DEPRECATED tag. Your integration continues to work during the migration period.
Migration period
Old and new approaches typically run side by side. We publish migration guides, release notes, and changelog entries with replacement APIs or SDK patterns.
Removal when ready
We remove the deprecated feature after partners have had time to migrate. Removal timing is communicated through your partnership team and published in Release notes, product changelogs, and the Deprecation list.
If you do not hear from your partnership team about a deprecation, review the Deprecation list, product changelogs, monthly release notes, and announcements. Subscribe to release notes by RSS or email from the Release notes hub.
How you’ll know about changes
| Channel | What you get |
|---|---|
| Partnership team | Migration timelines, rollout guidance, and org-specific impact |
| Deprecation list | Searchable catalog of active deprecations and past removals |
| API reference | DEPRECATED tags on endpoints and inline warnings on parameters |
| Product changelogs | Version labels, tags, and migration pointers per product line |
| Monthly release notes | Cross-product summaries with Deprecated and Removed sections |
| Announcements | Site-wide operational notices |
Planning your migration
When something you use is deprecated or removed:- Assess impact: Find every call site, config flag, or SDK option that uses the deprecated item.
- Confirm timing: Ask your partnership team when removal applies to your organization if it is not listed on the Deprecation list.
- Implement replacements: Use the linked migration guide, changelog entry, or API reference page for the recommended alternative.
- Test before production: Run regression tests in staging before you deploy the update.
After removal
When a deprecated item is removed, behavior depends on the type of change:| Item type | Typical response |
|---|---|
| Endpoints | HTTP error with a message pointing to the replacement endpoint |
| Request fields or parameters | Validation error if the field is sent; omit deprecated fields in new requests |
| Response fields | Field omitted from the response |
| SDK properties or events | Type or runtime errors if you still reference removed symbols; upgrade to the documented replacement |
For API error handling patterns, refer to the API error messages page.