API Versioning Strategy for SaaS: Change Without Breaking Customers
Choose a versioning approach, define what counts as a breaking change and run a deprecation process customers can plan around.
This is for CTOs and product managers at SaaS companies whose customers and partners have built integrations on their API. An unannounced change to a field or endpoint can break a customer's billing, inventory or CRM sync overnight, and the support and trust cost lands on you. This post helps you define breaking changes, pick a versioning approach, run deprecations with clear timelines and know exactly which customers are affected before you change anything.
A developer renames a field in an API response from customer_name to name to tidy up the code. The change passes review because nothing internal breaks. The next morning, a large customer's ERP sync fails silently, and their finance team spends two days reconciling missing invoices before anyone traces it back to your release.
As a SaaS product grows, its API becomes a contract with customers, partners and marketplace apps. Many teams still treat it like internal code, changing responses, validation rules or error formats without notice. There is no written versioning policy, no changelog customers read, and no data on who uses which endpoints, so every change is a guess about who might break.
A procurement SaaS in Hyderabad had several partner integrations break after routine releases, each followed by escalations and goodwill credits. The CTO wrote a short breaking-change policy, added schema checks against the API specification to the build pipeline and started logging calls by version and client key. When the team later needed to change how tax fields were structured for GST invoices, they released a new version, emailed every client still using the old structure and gave them a clear timeline. Integrators migrated on schedule, support escalations about broken syncs dropped away, and partners began trusting release announcements.
Should API versions go in the URL or a header?
Both work. URL versions are easy to see and test, while header or dated versions allow finer control. Choose one that suits your customers' developers and apply it consistently across every endpoint.
How long should we support an old API version?
Choose a window that gives customers realistic time to change their integrations, and state it publicly. Enterprise contracts may specify notice periods, so check those with your account and legal teams before setting your policy.
Is adding a new field a breaking change?
Adding an optional response field is usually non-breaking, as long as clients ignore unknown fields. Adding a required request field, or changing a field's meaning, is breaking. Document this so engineers apply it consistently.
Who should own the API in a small SaaS team?
Name one senior engineer or product manager as API owner. They maintain the specification, approve changes to the public contract, run deprecations and keep the changelog current for customers and partners.
Want this fixed in your business?
Send the workflow. You get a scope and a fixed price within two working days — or a straight answer that it isn't a fit.