Apps

Fields
idstringrequired

ID of the app, used to identify itself in code. For example, my_app.

namestringrequired

Name of the app.

typestring

Type of the app. Some configurations apply differently based on the type of app. Defaults to admin.

admin: Enhances functionality of the Swell Admin dashboard or API.

integration: Integrates with an external service. E.g., an email provider or payment gateway.

storefront: Implements a storefront experience. E.g., a store website, page builder, or checkout.

theme: A theme created for a specific storefront app, for example Wave or Proxima.

channel: Implements an external sales channel. E.g. Amazon marketplace.

kindstring

For storefront apps, what the storefront is. Only a shop storefront can create storefronts, and it needs a desktop preview image to release.

shop: A store website. The default for storefront apps.

checkout: A checkout.

account: A customer account portal.

Swell sets extension itself for an app that has extensions but no storefront or theme.

companionboolean

Indicates whether the app is a companion app, which comes with a theme and has no listing of its own in the Swell App Store. A companion app is always free. Defaults to false. See Companion apps.

versionstring

Semver-formatted version number. swell app version increments it. swell create app writes 1.0.0; an app record created without a version starts at 0.1.0.

descriptionstringrequired

A brief description of the app, shown as the tagline in the App Store catalog. Maximum 70 characters. Required to release.

permissionsarray of permission

An array of permission scopes limiting which store data the app can access. When a merchant installs the app, Swell issues it an access token restricted to the scopes declared here.

Defaults to [], which grants unrestricted access to store data. Apps published to the Swell App Store must declare the specific scopes they need.

Each scope combines an access level with a collection name:

  • read_{collection}: grants read access. For example, read_orders.
  • write_{collection}: grants read and write access. write_orders also covers read_orders, so there is no need to declare both.

Use the base collection name. read_accounts also covers its child collections, such as accounts:cards.

It is not necessary to declare scopes for resources your app defines. An app always has full access to its own models, settings, and app record.

Permissions are recorded with each version of your app. The scopes granted on install are those declared by the version the merchant installs, so changing them takes effect with your next released version.

aiobject

Declares that the app uses AI through Swell. AI is on by default when a store installs the app, and merchants can turn it off for each installation; installs created by swell app push start with it off, and removing ai turns it off for them. Each version keeps its own ai. See AI.

storefrontobject

Configures the app's storefront features. Any app can declare embeds, data and actions, which add embed blocks, data sources and form actions to Wave storefronts. See Storefront extensions. menus, theme, external, editor, context and theme_updates are for storefront apps only.

themeobject

For theme apps only, configures theme properties including storefront app compatibility, the apps the theme names, its Theme Store listing and style presets.

compatibilitiesobject

For theme apps, a map of storefront app IDs to semver ranges: the versions of each storefront app the theme works with. The CLI uses its keys to find theme apps for a storefront app with storefront.theme.provider: app, and the dashboard checks the range. Each version keeps its own.

frontendobject

Configures how the app's frontend is hosted. See Frontend.

logo_srcstring

Path of the app's icon image, under assets/. Defaults to assets/icon.*. Every app type except theme needs an icon to release.

preview_srcstring

For storefront and theme apps only, path of the desktop preview image shown in the App Store catalog, under assets/. Defaults to assets/preview.*. Required to release a storefront app of kind shop whose storefront.theme.provider isn't app. Release fails if another app type has a preview image.

preview_mobile_srcstring

For storefront and theme apps only, path of the mobile preview image shown in the App Store catalog, under assets/. Defaults to assets/preview-mobile.*.

imagesarray of image

Gallery images shown in the App Store catalog. Each item describes one image and points to a file with image_src. Images are shown in array order and the first four are displayed. At least one image is required to release, except for theme apps.

id: Required. Unique identifier for the image.

title: Optional. Maximum 40 characters. Shown in the gallery.

description: Optional. Maximum 140 characters.

image_src: Required. Path to the image file, for example assets/screenshots/dashboard.png. Image paths, here and in highlights, preview_src, preview_mobile_src, logo_src and theme.styles, must be under assets/; the CLI warns about others.

highlightsarray of highlight

Feature highlights, for any app type, each with a title, a description and an optional image. The dashboard's new-storefront page shows a storefront or theme app's highlights as its features, and the partner dashboard shows them for every app. The App Store listing doesn't show them.

featuresarray of features

For storefront and theme apps only, list of enumerated features to associate with in the App Store catalog.

  • multi_currency: Multi-currency apps support selling in multiple currencies.
  • multi_language: Multi-language apps support selling in multiple languages.
  • bulk_pricing: Bulk pricing apps support selling in bulk.
  • account_pricing: Account pricing apps support selling to different customer groups.

More feature enumerations are coming soon.

Release fails if an app that isn't a storefront or theme sets it.

use_casesarray of use_case

For storefront and theme apps only, list of enumerated use-cases to associate with in the App Store catalog.

  • direct_to_consumer: Direct to consumer apps are designed for selling directly to consumers.
  • wholesale: Wholesale apps are designed for selling to other businesses.
  • marketplace: Marketplace apps are designed for selling products from multiple vendors.
  • digital_goods: Digital goods apps are designed for selling digital products.

More use-case enumerations are coming soon.

Release fails if an app that isn't a storefront or theme sets it.

purchase_optionsarray of purchase_option

For storefront and theme apps only, list of enumerated purchase-options to associate with in the App Store catalog. Release fails if another app type sets it.

standard: Sell one-time purchases.

subscription: Sell recurring purchases on a schedule.

full_descriptionstring

A longer text description of the app's features and capabilities, displayed in the App Store catalog. Optional.

Set from DESCRIPTION.md in the app root, truncated at 20,000 characters. It cannot be set in swell.json.

demo_urlstring

URL of a website where users can see a demonstration of the app's features and capabilities.

For theme apps, the Theme Store's demo is theme.listing.demo_url.

preview_video_urlstring

YouTube embed URL of a video demonstrating the app, shown first in the App Store gallery.

support_urlstring

If the app developer offers support to merchants, URL of the website where a user can get help with the app.

support_emailstring

Email address merchants can contact for help with the app. When empty, the support email of your partner account is shown instead.

documentation_urlstring

If the app provides written documentation to merchants, URL of the website where a user can get read the docs.

repository_urlstring

If the app is open-source, URL of the website where a user can find a Git repository of the app's code base.

extensionsarray of extension

List of extensions the app implements to integrate with core platform features such as payments, shipping, and tax calculation. Extension events are handled by app functions. See the Extensions guide for details.

integrationsarray of integration

An array of identifiers for the areas the app operates in, used to detect conflicts with other apps and with Swell integrations. Values can be the ids of Swell integrations or your own custom ids, such as ["klaviyo", "algolia", "myownid"].

A conflict is reported when an integration is already running under one of the listed ids, or when a running app lists one of this app's ids in its own integrations. Each conflict can be ignored, or the conflicting integrations and apps can be disabled.

Swell checks for conflicts when an app is installed from the marketplace, when a disabled app is enabled again, and when an integration is enabled. The Swell CLI runs the same check when an app is pushed for the first time, when a pushed app's integrations list has changed, and when an app is installed.

No checks are performed when integrations is omitted.

The swell.json model
{
  "id": "honest_reviews",
  "name": "Honest Reviews",
  "description": "Honest reviews from honest people",
  "version": "1.0.6",
  "type": "admin",
  "permissions": [
    "read_orders",
    "write_products",
    "write_accounts"
  ]
}