Skip to main content
POST
Installation Rollback

Installation Rollback

A merchant can roll an individual app installation back to any previously published (or currently deprecated) version, independent of the version the rest of the merchant base is on. Rollback pins the installation — the next time the developer publishes a new version, this installation is not auto-updated. The merchant must explicitly resume auto-updates to opt back in. Both endpoints require merchant or staff-admin auth (merchant or staff-admin) and scope the installation lookup by the caller’s storeId.

Endpoints

Installation Lifecycle States

The relevant fields on the installation are:

Rollback to a Specific Version

POST /apps/store/installations/:installationId/rollback

string
required
The UUID of the installation to roll back. Must belong to the caller’s storeId.
string
required
Semver version string to roll back (or forward) to. Must exist as an AppVersion row in either published or deprecated status — draft versions cannot be installed by merchants.
Side effects on success:
  1. installedVersion = targetVersion
  2. pinnedVersion = targetVersion
  3. autoUpdate = false
  4. A rolled_back entry is appended to the version changelog.
Response (200):
Error codes:

Resume Auto-Updates

POST /apps/store/installations/:installationId/resume-auto-update

Side effects on success:
  1. autoUpdate = true
  2. pinnedVersion = null
  3. If a published version exists for this app, installedVersion jumps to the latest published version. Otherwise installedVersion is left as-is.
Response (200): the updated installation.

Interaction with Developer Publish

When a developer publishes a new version (POST /apps/developer/:appId/versions/:version/publish), the platform bumps installedVersion to the new version on every installation of the app that has autoUpdate = true and no pinned version. Pinned installations are skipped entirely — the publish has no effect on them until the merchant resumes auto-update.

When to use rollback vs uninstall

Common Patterns

Pin to the current version (suspend updates)

Rolling back to the version already installed is a valid no-op publish:
After this call, the merchant stays on 1.2.0 regardless of future publishes, until they call /resume-auto-update.

Beta channel

Developers commonly publish 1.x.x-beta.N versions, then have early- access merchants rollback to the beta version. When the beta is promoted (the dev publishes 1.x.x as stable), pinned beta merchants keep their -beta.N install until they resume auto-update.
There is currently no force flag — auto-updates always respect pinnedVersion. If a merchant must be force-updated (e.g. critical security fix), contact platform support; there is no public REST endpoint for this.