Product Development

API Versioning for B2B Integrations: Change Without Breaking Clients

Version a B2B API when a change would break a consumer's existing contract. Keep compatible changes on the current version, test against real client behavior, and run old and new versions together long enough for partners to migrate. A new version number alone does not make an integration safe.

November 16, 20263 min readOpenGeeksLab

Direct answer: Version a B2B API when a change would break a consumer’s existing contract. Keep compatible changes on the current version, test against real client behavior, and run old and new versions together long enough for partners to migrate. A new version number alone does not make an integration safe.

For a Swedish B2B company, an API may connect its product to a customer ERP, a logistics partner, a payment provider or an internal operations tool. Those systems rarely release on the same day. The design problem is therefore continuity: how can one team improve its service without forcing every connected team into an emergency release?

Start with the contract, not the URL

List the operations each consumer uses, including required fields, optional fields, error codes, pagination, authentication and retry behavior. Record who owns each consumer and how quickly that team can deploy. An undocumented spreadsheet export or nightly job can be a consumer too. Microsoft’s API design guidance treats the API as a contract between services and recommends backward-compatible changes where possible.

Consider an order API that adds an optional delivery note. Existing clients can generally keep working if the server accepts requests without the new field and clients tolerate unknown response fields. Removing an existing field, changing its meaning, or requiring that note in every request is different: those changes can break a client. Test the specific clients before classifying a change as compatible.

Choose a version boundary with an owner

A major version should mark a deliberate incompatible contract. Publish which version each partner uses, who approves a breaking change, and when the old version will retire. Version routing may be in the path, header or gateway; choose one method and document it consistently. Keep implementation releases separate from client-visible API versions. A backend can be deployed many times without changing its public contract.

Microsoft’s API implementation guidance calls for explicit behavior when a version is omitted, malformed or unsupported. Silent fallback makes defects difficult to diagnose. Return a documented error and an upgrade path instead.

Use contract tests and a migration window

Before release, create representative requests for every important consumer. Test response shape, permissions, failure cases and retry behavior against both old and new versions. For writes, include repeated requests after a timeout: a retry should not create a second order. Capture request identifiers and version numbers in operational logs without exposing sensitive payloads.

Then publish a migration plan: the new contract, a test endpoint or sandbox, partner contact, target dates, monitoring and rollback criteria. During dual operation, watch actual use of both versions. A retirement date is credible only if you can identify the remaining users and help them move.

Decision checklist

  • Can the change be made compatible by adding an optional field or operation?
  • Which named clients depend on the existing behavior?
  • Do contract tests cover ordinary requests, errors and retries?
  • Can old and new versions run in parallel with clear ownership?
  • What signal shows that migration is complete?

For a broader integration architecture, see our API integration design guide. OpenGeeksLab’s custom software development service can help map the contract and delivery sequence around your existing systems.

Frequently asked questions

Does every API change require a new version?

No. A compatible change can usually stay on the current version when older clients continue to work and tests confirm the behavior. A breaking contract change needs an explicit migration path.

How long should the old version remain available?

Base the window on actual consumers and their release cycles. Record the owner and retirement criteria rather than choosing a date without migration evidence.

From idea to reliable product

Make the next product decision clearer.

Bring the customer problem, the current evidence and the constraints. We will help shape a focused path through discovery, MVP delivery, custom software or AI development.

Discuss your product