zero gravitySOLUTIONS
← All insightsSAAS ENGINEERING / COMPATIBILITY AND SUNSET PLAN

API versioning for independent customer upgrades

QUICK ANSWER

Version a B2B API when its contract must change incompatibly, while keeping compatible improvements within the existing version. Test real consumer assumptions, isolate version translation from business rules, and retire versions using account-level usage evidence and a concrete migration path.

Inside this article 5 sections

A B2B API serves clients whose release calendars you do not control. One customer may deploy weekly, another may need a quarterly review, and a small integration may run unattended until it fails. Versioning must preserve a usable contract during that overlap, not merely place a new number in a URL.

Start by identifying the change that threatens compatibility. Adding a documented optional response field may fit the current contract. Changing an order status meaning, pagination behavior, required input, or monetary unit may require a new contract even when the JSON types remain unchanged. The version boundary should express that difference.

Inventory the assumptions clients actually make

For each supported consumer class, record endpoints, authentication method, request fields, response fields, pagination usage, retry behavior, and generated client version if available. Use account-level integration telemetry and customer-provided fixtures where appropriate. Avoid treating the public schema as a complete description of client behavior.

A client may assume that an empty list means no more pages, that a status enum contains only three values, or that a retry returns the same result. These assumptions can be contractual, accidental, or undocumented but widespread. Classify them before changing behavior so the team can distinguish a safe improvement from a migration that needs explicit communication.

Illustrative compatibility matrix for an order API
ConsumerDependencyFixture required
Warehouse connectorKnown order states and stable orderingNew state, equal timestamps, multiple pages
Finance exportAmount units and roundingCurrency boundaries and unchanged totals
Customer portalRetry and conflict responsesLost response, duplicate key, stale revision
Partner SDKGenerated response typesUnknown fields, enum values, null versus absent
Compatibility is observable consumer behavior. A successful schema validation cannot replace these workload-specific assertions.

Separate additive change from changed meaning

Define what clients must tolerate within a version. If the contract permits unknown response fields, test generated clients against them before relying on that rule. If enum expansion is permitted, provide an explicit unknown-value strategy. A theoretically additive change can still break a strict client that the business has committed to support.

Do not silently repurpose a field. If amount changes from minor units to decimal major units, introduce an explicit new representation or version. If order status changes from payment state to fulfillment state, a new name may be necessary even if both are strings. Reusing a familiar name for a different concept creates failures that are difficult to detect in transport tests.

Response ordering and pagination are also behavior. Moving from offset pagination to opaque cursors can improve consistency but changes client iteration. Offer a clear migration example and specify snapshot or consistency expectations. An old client should not receive a new pagination model merely because its first page happens to look similar.

Keep versions at the contract boundary

Translate each supported API version into a current internal command or query model. Keep authorization, business invariants, and durable operation identity in the shared application layer. This avoids maintaining two independent order implementations whose permission checks and bug fixes gradually diverge.

Illustrative boundary:
/v1/orders request -> V1 adapter -> CreateOrder command
/v2/orders request -> V2 adapter -> CreateOrder command
CreateOrder result -> version-specific response adapter

Shared: authorization, transaction, operation identity
Versioned: field names, accepted shapes, response semantics

Translation has limits. If version two introduces split shipments that version one cannot represent, the old adapter needs an explicit rule: exclude unsupported operations, expose a compatible summary with documented limitations, or prevent the new feature for that integration until migration. Do not invent a lossy translation and call it equivalent.

Store durable state in a way that both supported adapters can interpret. A rollback of the API binary does not undo data written under a new model. Exercise old-version reads after new-version writes and confirm that their behavior is defined. This cross-version state test is often more important than testing each endpoint in isolation.

Preserve retry semantics across versions

Decide whether a client may retry the same business operation through a different API version. The safest default is to keep the original version and idempotency contract for recovery. If cross-version replay is supported, normalize both requests to the same business intent and define how response translation works.

Do not let version adapters create separate operation identities for the same underlying request accidentally. Conversely, do not treat materially different commands as identical because they share a header key. The idempotency scope, fingerprint, and retention policy need to remain explicit during migration.

Include errors in the contract tests. Customers may classify a conflict as retryable, display a validation code, or use a status response to reconcile an uncertain write. Changing only error behavior can break integrations even when every successful example remains identical.

Keep caches and generated links version-aware. A shared cache key that omits the negotiated API version can return the wrong representation even when both adapters are correct. Test pagination links, resource URLs, and conditional requests through the real gateway so infrastructure behavior does not bypass the intended version boundary.

Make retirement a project with evidence

Publish the replacement contract, migration examples, test environment, known semantic differences, and support contact before announcing a retirement date. A sunset signal can communicate planned unavailability, but it does not migrate a client. Identify which accounts still call the old version and whether that traffic represents active business work or abandoned retries.

Track migration completion by account and integration owner. Avoid recording credentials or raw customer payloads in usage reports. A small volume of old-version calls may still be critical, such as monthly billing. Observe a period that covers the relevant business cycle rather than assuming a quiet week proves the version is unused.

Rehearse the final rejection response and rollback plan. Keep the retirement decision tied to verified migration status and contractual commitments. The business API boundary guide establishes ownership, and idempotency design covers repeated commands. B2B API implementation should make the coexistence period as deliberate as the new endpoint itself.

FROM INSIGHT TO ACTIONCustom software development

Evolve your API without losing contract clarity.

We can implement version adapters, consumer regression fixtures, and usage visibility for a controlled migration.

Explore software developmentDiscuss your build

Start with your goals.
We’ll work through the next step together.