App distribution

An app reaches a store in one of two ways. You can install it yourself into any store you have access to, which needs nothing more than a version — this is how private apps and client work are distributed. Or you can publish it to the Swell App Store, where any merchant can find it and install it themselves. Publishing is where a partner account, a release and a review come in.

Use the swell app install command to install an app into any store you have user-level access to. Without a store specified, the app is installed in the Live environment of the current store; without a version, the latest version is installed.

swell app install [-s store-id] [-e env] [-v version]

A version is all this requires. The app doesn’t have to be released, and it doesn’t have to belong to a partner account. See App development for versioning and release notes.

If you are updating an installed app in a live store, the CLI requires incrementing the app version as part of your workflow.

Publishing lists your app in the Swell App Store, where merchants browse and install it themselves. It runs through the partner dashboard, and every release is reviewed by Swell before it goes live.

Partner accounts are self-serve — sign up at partners.swell.store. In the partner dashboard, open Apps and choose Connect app to link an app you have already built in a development store. An app has to belong to a partner account before it can be released.

Releasing marks a version as a candidate for publishing. Swell validates your listing details at this point, so a release fails if something a listing needs is missing. See App Store submission for the full list.

swell app release 2.0.0 --release-notes releases/v2.0.0.md

Open the app in the partner dashboard and submit the release. While it’s being reviewed the app page shows Reviewing release, and the Review tab carries the conversation with your reviewer — reply to comments there. For what to prepare and check beforehand, see App Store submission.

A reviewer either publishes the release or rejects it. A rejected release keeps its comments so you can see what was raised; fix it, release a new version and submit again. Once published, your app appears in the App Store.

What merchants see is drawn from your swell.json, your app assets and your DESCRIPTION.md: name, description, images, the price fields, support_url, documentation_url, support_email and preview_video_url. The icon comes from assets/icon.*, and the long description from DESCRIPTION.md in the app root. Categories are assigned by Swell. Storefront and theme apps also use preview_src, preview_mobile_src, use_cases, purchase_options and features; other app types cannot set those. See the swell.json reference for every field.

You don’t have to publish to see how it will look. Preview release, on the app page in the partner dashboard, opens the App Store filtered to your app, so you can check the listing and its detail page before anyone else can.

Every app carries a private ID and a public ID. Private apps deliberately share IDs — that’s what lets the same app be installed privately in more than one store — but only one published app can hold a given public ID. Both releasing and approving a release will fail if a published app already holds yours, so rename the app before you release it.

Release a new version and submit it for review the same way. The newly approved version becomes the published one, and your release notes are what merchants read when deciding to update.

You can also unpublish a release from the partner dashboard. The app falls back to the previously published version if there’s one, and otherwise leaves the App Store.

From a listing, Install app takes a merchant through signing in, choosing which store to install into, and reviewing the app details and permissions before anything is installed. Linking someone straight to your listing is enough — the flow handles the rest.

There’s no shareable install link for an app that isn’t published. Private installs go through the CLI, as above.

For what to prepare before submitting, see App Store submission. For the development workflow behind a release, see App development. For what reviewers look for, see best practices.