Skip to content
Tutorials Center
My learning

Topics

Lesson 53 of 61 ยท Publishing and Maintenance

Maintaining Themes: Updates and API Versions

Keep a Shopify theme healthy for years: follow the quarterly API release cycle, handle deprecations, merge upstream Dawn updates, and write a changelog.

Launching a theme is the middle of its life, not the end. Shopify ships changes every quarter. Browsers change. Apps change. The merchant adds products, languages and plugins that you never planned for. A theme nobody maintains slowly gets slower, then buggy, then unsafe to edit.

This lesson covers the maintenance work that keeps a theme healthy: understanding which parts of a theme are versioned and which are not, reading deprecation notices, pulling in updates from the theme you started from, deciding what to customize, and recording what changed. It builds on Version Control and Team Workflows and Migrating Legacy Themes to Online Store 2.0.

Release dates, support windows and tool behavior below describe how Shopify has worked at the time of writing. They can change, so confirm them in Shopify's developer changelog before you plan around them. Everything about Shopify itself is read-only on this site. The two live examples are JavaScript stand-ins: a calculator for an API version's support window and a classifier for upstream merges.

What is versioned and what is not

Not everything a theme touches has a version number. Knowing which does is half of maintenance.

Versioned: Shopify's GraphQL APIs. The Storefront API and the Admin API use dated versions in the URL, such as 2026-01. A theme only meets these when it calls the Storefront API from the browser (see Storefront API and Fetching Data from a Theme) or when an app it relies on does.

Not versioned the same way: Liquid itself and the storefront Ajax endpoints such as /cart/add.js. Liquid changes by adding tags, filters and objects over time, and Shopify announces deprecations in advance. The Ajax Cart API (see The Ajax Cart API) has no version in the path, so it changes cautiously and mostly additively.

Yours: the theme's own version, which you choose and record in config/settings_schema.json under theme_info.

Because Liquid is not pinned to a version, you cannot "stay on an old Liquid". The platform moves under you, and your protection is tooling: run Theme Check regularly, because its rules track deprecations.

The quarterly cycle

Shopify releases a new API version every three months, with versions named by year and month (January, April, July and October). Each stable version is supported for about a year, and an older version eventually stops being supported. When you ask for a version that is no longer supported, Shopify handles the request with the oldest version it still supports, so your code may start to behave differently without you changing anything. That is why the rule is: put the version in one place and review it on a schedule.

flowchart LR
    R["Release candidate<br/>announced"] --> S["New stable<br/>version"]
    S --> U["You test and<br/>upgrade"]
    U --> W["Old version stays<br/>for about a year"]
    W --> E["Old version<br/>retired"]
    E -. "requests fall forward" .-> S

You have a window to upgrade. Using it on a schedule beats scrambling after something breaks.

Here is a small, honest stand-in for that schedule. It computes a version's expected retirement date and warns when it is close. The 12-month window is the rule of thumb described above; use the real dates from Shopify's documentation when you plan.

JS API version support window

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice the lesson of the output: the version you picked a year ago is the one most likely to be close to retirement. A reminder every quarter costs far less than an emergency.

Deprecations: how they reach you

Shopify announces deprecations in its developer changelog, usually with a long runway, and Theme Check adds rules for them. Typical examples in themes are old tags, old filters and old Ajax parameters. A healthy habit:

  1. Subscribe to the developer changelog, or check it once a month.
  2. Run shopify theme check before every release and treat new deprecation warnings as tasks (see Theme Check, Linting and Testing).
  3. Search your code for libraries you load from outside, because those age too: a script that worked for years can break when a browser removes a feature.
  4. Keep a maintenance branch where you update dependencies and rules, separate from feature work.

Deprecations are not emergencies. They are scheduled work, and your job is to schedule it.

Updating from Dawn or another upstream theme

Most themes start as a copy of a reference theme such as Dawn (see Exploring Dawn, the Reference Theme). The reference theme keeps improving: fixes, accessibility work, new section features. You want those improvements without losing your customizations. This is a Git problem with a clear solution.

Keep the original as a remote called upstream, and merge from it on a branch:

Terminal
git remote add upstream https://github.com/Shopify/dawn.git
git fetch upstream
git checkout -b update/dawn-latest
git merge upstream/main

Git reports conflicts only in files that you and upstream both changed. Those are the ones you resolve by hand. If you did not start from a Git history (you copied files), you can still compare: download the version you started from and the latest version, and run a three-way comparison of your files against both.

The best way to make future updates cheap is to customize in a way that survives merges:

  • Add new files (a new section, a new snippet) instead of editing shared ones. A new file never conflicts.
  • When you must edit a shared file, keep the change small and mark it with a comment such as {% # custom: free shipping bar %}, so you can find it later.
  • Put your CSS in your own file or in a clearly separated block.
  • Do not reformat upstream files. A whitespace-only change creates conflicts that mean nothing.

The next stand-in classifies files the way a merge would see them. For every file it has three versions: the original you started from, your current version, and the latest upstream version.

JS Classifying files for an upstream merge

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The output shows why small, separate customizations matter: the files that fall into "CONFLICT" are the only ones that cost you time.

Changelogs and releases

A changelog is a promise to the next person who edits the theme, who may be you in a year. Keep a CHANGELOG.md at the project root (outside the theme folders that get uploaded, or list it in .shopifyignore) and add an entry for every release:

MARKDOWN
## 3.2.0 - 2026-10-12
### Added
- Announcement bar section with a dismiss button.
### Changed
- Product cards load the second image only on hover.
### Fixed
- Cart drawer no longer loses focus after removing the last item.

Use a version number that tells people how risky the update is. A common scheme: change the first number for breaking changes, the second for new features, and the third for fixes. Tag each release in Git so you can return to any version. For a theme sold to many stores, a changelog is also what merchants read before deciding to update; see Theme Store Requirements and Selling a Theme.

A maintenance routine

Maintenance works best as a calendar, not as heroics. A reasonable rhythm:

  • Every release: Theme Check, a preview-theme test and an accessibility pass.
  • Monthly: read the developer changelog, update third-party libraries, review app scripts that were added since the last visit (see Theme Performance and Core Web Vitals).
  • Quarterly: review the API version you use, merge upstream changes, re-run Lighthouse on key pages.
  • Yearly: look at the whole theme: delete unused sections and snippets, simplify settings that nobody uses, and ask whether a larger migration is due.

Deleting is maintenance too. Every unused setting and section is code that can break and a choice that confuses merchants.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which part of a theme's environment is pinned to a dated version?

    Shopify's GraphQL APIs have dated versions. Liquid and the Ajax endpoints are not pinned that way, so tooling such as Theme Check is how you track their changes.
  2. 2. What happens when you request an API version that is no longer supported?

    Requests for retired versions fall forward to the oldest supported version. Your code can change behavior without any edit, which is why you review your version on a schedule.
  3. 3. Which customization style makes future upstream merges cheapest?

    A new file never conflicts, and small marked edits are easy to find and re-apply. Reformatting creates conflicts that mean nothing.
  4. 4. In a three-way merge, a file is changed by you and not by upstream. What happens?

    Only changes made on both sides conflict. If upstream left the file alone, your change goes through.
  5. 5. What is the purpose of a changelog?

    A changelog records decisions and changes so updates can be planned and problems traced to a release.

Summary

  • Shopify's GraphQL APIs have dated, quarterly versions; Liquid and the Ajax endpoints do not, so use Theme Check and the developer changelog to follow them.
  • Keep the API version in one place and review it each quarter; retired versions fall forward to the oldest supported one.
  • Treat deprecations as scheduled work, not emergencies.
  • Merge upstream theme updates on a branch with a remote called upstream, and make your customizations easy to merge: new files, small marked edits, no reformatting.
  • Keep a changelog and tag releases.
  • Maintain on a calendar: every release, monthly, quarterly and yearly tasks; delete what is unused.

You now have the full path from build to release to upkeep. Put it into practice in Project: A Configurable Hero Banner Section.