I am writing to express concern over the discontinuation of detailed API release notes starting with version 2025-04. While the developer changelog provides updates, it lacks the depth and structure that the release notes previously offered, which are crucial for developers to effectively manage and adapt their applications.
Key Differences Between Release Notes and Changelog:
Structured Summary of Breaking Changes:
Release Notes: The 2025-01 release notes included a dedicated section outlining breaking changes, such as the change of the adjustmentPercentage field in SellingPlanPercentagePriceAdjustment from Int to Float, and the deprecation of the storefrontCustomerAccessTokenCreate mutation.
Changelog: These critical changes are scattered across multiple entries without a consolidated summary, making it challenging to identify and address breaking changes promptly.
Comprehensive Coverage of Changes:
Release Notes: Provided a holistic view of all changes in a given API version, including new features, deprecations, and modifications.
Changelog: While it lists updates, it does not offer the same level of comprehensive coverage, potentially leading to overlooked changes that could affect application functionality.
Context and Guidance:
Release Notes: Offered context and rationale behind changes, aiding developers in understanding the implications and necessary adjustments.
Changelog: Often lacks detailed explanations, leaving developers to interpret the significance and impact of changes independently.
Impact on Development Workflow:
The absence of detailed release notes hampers our ability to:
Quickly identify and adapt to breaking changes.
Understand the full scope of updates in each API version.
Make informed decisions during application development and maintenance.
Request:
I kindly urge the Shopify team to reconsider the decision to discontinue detailed API release notes. Their reinstatement would greatly enhance the developer experience by providing structured, comprehensive, and contextual information necessary for efficient application development and maintenance.
It was kind of nice, but I don’t find it hard to use the changelog at Recent changes to Shopify’s platform, filtering by API version, breaking changes, etc. It’s less confusing to have the changes in one spot instead of two. As long as you read all the changes, (at least ones with Action required), you won’t miss anything. And you can also subscribe to updates in this forum so every change will be emailed to you.
Did you read @Kyle_W requests details at all or is this a bot response.
The changelog is a glossy overview it lacks a level of critical depth, typically only linking to somewhere else in the docs with around ~5% of the time not even being a valid link, and most the rest of the time the referenced doc STILL lacks critical detail.
And that’s when the changelog even bothers to have an entry for a change instead of a silent update.
Causing a lot of bouncing around to gather info for a migration , it’s unnecessary friction by undoing a system that just worked.
Agreed, please bring this back. I’ve definitely relied on the detailed notes in the past to find any updates I’ve needed to make to our API integrations.
Thanks so much for the feedback here! I personally find the release notes really helpful too, especially when troubleshooting past API behavior with developers.
A couple of updates that should help with the concerns raised here. We now include more details in API headers about specific deprecated resources being called (see the changelog), which gives you that real-time context about what’s deprecated right in your API responses. Also worth noting that 2025-01 was our last published release notes, so once 2026-01 rolls out, the changelog should have a much more comprehensive view of current available API versions, meaning fewer instances where you’d need to cross-reference both resources.
If I could, I would like to reframe some of these requests to see if they could be applied to the current changelog. From what you have shared here, this is what I’m seeing would get this better parity to the former release notes:
Structured summary / consolidated view of breaking changes (this is already address in some way with the recent updates to version and Action Required filters)
Enhanced context and rationale behind changes to help understand implications and necessary adjustments
Better link reliability and critical detail depth (avoiding “glossy overviews”)
Reduced friction by avoiding the need to bounce around between multiple docs for migration info
If I may add one item to that list is that sometimes a changelog has a link that 404s when it first goes out. That makes it significantly harder to know if the change was reverted or if we need to dig to find the correct URL. So I guess my request is that if something is getting pushed to the changelog, leave it pushed and update the content with an *updated note or something rather than deleting the URL.
Your list is worthwhile, but personally, I feel like that would add bloat to the changelog. Traditionally, changelogs are simple in both concept and format: a timeline of notable changes.
When a new API version becomes stable, I’d prefer to look at a single document that summarizes all changes in that version (complete with references and callouts for breaking changes), instead of having to piece together what could be 100+ changelog entries.