Updates & Versioning

How Updates Work

Once your plugin is approved and live, updates go through a controlled process that protects merchants from unexpected changes.

Update flow for approved plugins:

1. Edit your plugin in the Developer Portal (name, description, URL, scopes, etc.)
2. Changes are saved to pending_changes — the live version is not touched
3. Submit for re-review
4. If approved: pending changes merge into the live version atomically
5. If rejected: pending changes are discarded, the live version stays as-is

This means merchants always see the last approved version of your plugin until an update is explicitly approved by the review team.

Version Numbers

Use semantic versioning: MAJOR.MINOR.PATCH

1.0.0       Initial release
1.0.1       Patch — bug fix
1.1.0       Minor — new feature, backward compatible
2.0.0       Major — breaking change
1.0.0-beta.1  Pre-release label allowed

Rules:

• Versions can only go up — downgrades are blocked
• Version is read from package.json by default
• You can override with --set-version on the deploy command

Deploying an Update

# Standard deploy (prompts for confirmation)
whatalo deploy --message "v1.2.0: Added inventory sync"

# Non-interactive (CI/CD — --force is required)
whatalo deploy --force --message "v1.2.0: Added inventory sync"

# Override version instead of reading from package.json
whatalo deploy --set-version 1.2.0 --force

The --force flag is required in non-interactive environments (CI/CD pipelines). Without it, the command will pause and wait for terminal input, which will hang or fail in CI.

Scope Changes and Merchant Consent

When you add new permissions to an updated plugin, the platform enforces a 3-layer security process:

Layer 1 — Review

The review team sees a diff of scopes added and removed. Scope expansion (adding new permissions) is a privilege escalation and receives closer scrutiny.

Layer 2 — Propagation

On approval, new scopes are added to pending_scopes on all existing merchant installations. The current installation remains functional with the old scope set.

Layer 3 — Consent

Each merchant sees a consent screen the next time they open your plugin. They must explicitly approve the new permissions before the expanded scope takes effect.

Removing scopes takes effect immediately on approval — no merchant consent is required when you give up access.

What Can Be Updated Without Re-review

Minor content changes that don't affect functionality or permissions may not require re-review, depending on platform policy at the time. When in doubt, submit for review — the team will process it quickly if the changes are low-risk.

Versioning in CI/CD

A typical release workflow:

# In your CI pipeline after tests pass:
npm version minor  # or patch / major
whatalo deploy --force --message "Automated release from CI"

Or with explicit version control:

whatalo deploy --set-version 1.3.0 --force --message "v1.3.0 release"

Checking Your Deployed Version

The deploy command outputs the current and previous version on success:

Plugin   my-analytics-plugin
Version  1.3.0
Previous 1.2.1
Status   pending_review

The status reflects the current review state of the submitted version.