A payments API has thousands of integrators on many SDK versions. How should versioning, deprecation, compatibility testing and migration tooling be designed?

The principle that removes most of the problem

Additive change requires no version. New optional fields, new endpoints, new enum values that clients are told to ignore when unrecognised — all of these can ship continuously if the compatibility contract was established from the start.

The contract has to be explicit in documentation and enforced in the SDKs: unknown fields are ignored, unknown enum values fall to a default, and field order is not meaningful. Integrators who did not receive that instruction will have written code that breaks on an added field, which is why the rule must exist before the first version ships.

When a version is genuinely needed

Removing a field, changing a type, changing a default, changing an error's meaning, or altering the semantics of an existing operation. These are breaking, and the honest response is a new version rather than a quiet change with a blog post.

The mechanics that work at scale

• Date-based or pinned versions per account, so an integrator's behaviour is fixed until they choose to move. This is the model that scales to thousands of integrators, because it decouples your release cadence from theirs entirely.
• A translation layer mapping older versions onto the current internal model, so the core does not carry every historical shape. The version count is a cost paid in the translation layer, and keeping it out of the domain is what makes many versions survivable.
• Usage telemetry per version and per endpoint, so deprecation is driven by evidence. "Which customers use this field" must be answerable in minutes.
• A published deprecation policy with a real notice period, and communication that reaches the engineers rather than only the billing contact.
• Migration tooling, not just documentation: a compatibility checker, a diff of behaviour between versions, and ideally a shadow mode where their traffic is evaluated against the new version and differences reported.

The part that is organisational

Deprecation fails on communication, not on engineering. The integrator's original developer has left, the account contact is in finance, and the notification email goes to an unmonitored address. The mechanisms that actually work are in-band: deprecation headers in every response, warnings in the dashboard the developer uses, and — as the final step — brief scheduled brownouts that make the deadline real while it is still reversible.