How Shopify Manages API Versioning and Breaking Changes

Summary

Shopify describes how it versions APIs and manages breaking changes for an ecosystem of tens of thousands of partners. It releases date-based API versions every three months, with changes introduced in an unstable version and represented in the monolith through frozen records and a change file. Teams classify changes by whether third-party developers must migrate, use impact analysis and forward-compatibility testing, and protect uncertain changes with beta flags. For necessary breaking changes, tooling marks breaking or possibly breaking request paths, sends metadata through Monorail to a data warehouse, and produces reports on affected calls. Runtime conditionals then help teams manage old and new behavior, measure adoption, identify remaining risk, and communicate with developers.

Context

Shopify supports tens of thousands of partners whose applications depend on stable, predictable API behavior, while more than 1,000 engineers can ship code affecting its APIs. The post frames versioning as a way to continue platform development without requiring ecosystem-wide migrations whenever behavior changes.

Approach / What changed

Shopify releases date-based API versions quarterly and models changes through frozen records, an unstable version, optional beta flags, and runtime ApiChange checks. Teams assess proposed changes, instrument breaking paths with mark_breaking or mark_possibly_breaking, send request metadata through Monorail to a data warehouse, and use reports and conditionals to manage adoption and remaining risk.

Takeaways

• A breaking change is defined as any API change requiring a third-party developer to do migration work to preserve an application’s existing functionality.
• Forward-compatible changes can be adopted by any merchant without depending on shop migrations or other conditions; changes that fail this test remain limited or beta-protected.
• mark_breaking and mark_possibly_breaking capture request context so teams can measure affected API calls, identify apps and shops at risk, and track adoption after release.

Related reading