Skip to content

Platform Upgrades

Some new features need a one-off step before an existing shop gets them: a block added to the order page, a checkout step, a setting switched on. New shops get them from the start. Existing shops apply them from Settings › Platform upgrades (/admin/upgrades), when they're ready.

The page

The page opens with where the shop stands: how many upgrades still need dealing with, a progress bar, and a count for each list, each linking to it. Then the lists, in the order to work through them:

List What's in it
Needs your attention An apply couldn't finish automatically (usually a customised page), or the upgrade's state couldn't be read. The row says what to do by hand; Check again looks once more.
To apply Compliance and recommended upgrades not applied yet, compliance first.
Optional Upgrades only some shops need, each saying who it's for ("For shops that sell subscriptions."). They don't count towards progress.
Done Applied upgrades, most recent first, with who applied them and when, folded away. An upgrade whose apply asked for a check (the privacy notice: "check this is the right page") is marked and keeps its steps. Upgrades marked not needed sit here too, with Put back.

Each row shows the upgrade's importance (Compliance, Recommended or Optional), New for one released this month or last, the month it was released, and What this changes, the full release notes. Lists with nothing in them aren't shown. Once nothing needs dealing with, the page says the site is up to date and opens the Done list.

Not needed takes an upgrade off the to-do lists for this site, for example the cookie banner on a shop that doesn't use analytics. It moves to Done as "Marked not needed" and stops counting. Put back undoes it. An applied upgrade can't be marked not needed.

An upgrade that builds on another shows Waiting and "Apply … first." until the other one is applied, with no Apply button. Importing earlier marketing consent waits for customer messaging.

Applying is safe to repeat: every upgrade checks what's already there. After an apply, the result appears at the top of the page, naming the upgrade.

What counts as waiting

The admin home page's "N platform upgrades waiting" link counts the Needs your attention and To apply lists only. Optional upgrades and ones marked not needed never count, so a shop isn't nagged about restaurant ordering because it doesn't run a restaurant.

How it works

Each upgrade is a SiteUpgrade bean. SiteUpgradeService.overviewForSite asks each one for its live state (detect) on every visit and joins it with the site's SiteUpgradeRecord (the last apply's outcome, and the not-needed choice: dismissedAt, dismissedBy). UpgradeOverview sorts the results into the lists. Nothing is worked out ahead of time.

An upgrade describes itself with:

Method Meaning
id() Starts with the release month, yyyy.MM- (2026.10-cookie-consent); the page reads the month from it. Never change it once shipped.
importance() COMPLIANCE (helps meet the law), RECOMMENDED (the default) or OPTIONAL.
audience() Who it's for, finishing "For …". Give one for every optional upgrade.
requires() Ids of upgrades that must be applied first. applyUpgrade refuses until they are, and records nothing.
statusDetail() A line of counts or progress under the row (the consent import's figures).

Superadmins see every site's state under System › Platform upgrades, from the stored records.