Apps
Fields
ID of the app, used to identify itself in code. For example, my_app.
Name of the app.
Type of the app. Some configurations apply differently based on the type of app, for example, theme apps cannot define models, content, functions, or settings.
- 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 Proxima.
- channel: Implements an external sales channel. E.g. Amazon marketplace.
Semver-formatted version number. This value can be automatically incremented using the swell app version CLI command. Defaults to "1.0.0".
A brief description of the app, shown as the tagline in the App Store catalog. Maximum 70 characters. Required to release.
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.
For storefront apps only, configures storefront properties including menu and theme structure.
Default navigation menus instantiated when the app is installed.
ID of the menu, may be used to reference specific menus from a storefront app or theme.
Name of the menu for display purposes in the Swell dashboard.
The menu items.
Type of menu item rendered by the storefront app or theme.
- home: Link to the home page.
- search: Link to a search page with an optional pre-defined query.
- product: Link to a product detail page.
- product_list: Link to a page listing all products.
- category: Link to a category of products.
- page: Link to a content page.
- blog: Link to a blog post.
- blog_category: Link to a page listing all blogs in a category.
- content: Link to a content entry.
- content_list: Link to a page listing all content entries.
- url: Link to a specified URL.
- heading: Display a heading above a set of menu items.
Name of the item to be displayed in the storefront app or theme.
For product, category, page, blog, blog_category, content, content_list, and url types only, defines the value used to construct a link in the storefront app or theme. For example, a page item would have a value referencing page.slug.
A sub-menu of items. The sub-items of an item are of the same schema as the top-level items property.
For storefront apps that support themes only, defines attributes of theme support and functionality.
Determines whether the theme is provided by an app or self-contained.
- app: Supports loading separate theme apps.
- self: Provides its own theme, supporting Swell's Theme Editor without a separate theme app.
Note: Support for self contained themes is still a work in progress.
Defines attributes of compatibility between the storefront app and its supported themes, if provider: app.
- version: Indicates that this app only supports themes which are themselves compatible with this storefront app version.
- For example, compatibility.version: 2.* indicates themes which are themselves compatible with storefront app version: 1.* will not be supported.
- conflicts: Indicate paths or files that should be checked for change conflicts before being automatically updated (overwritten) during a theme version upgrade.
- For example, specifying compatibility.conflicts.exclude_files: ['theme/config/**'] indicates that changes to any theme config files will not be overwritten during a theme upgrade and will not count as a conflict.
Semver-formatted version range indicating the version that themes must be compatible with in order to be supported by this storefront app. For example, version: * indicates that all themes are supported, while version: 1.* indicates that only themes made for storefront app version 1.* are supported.
-> See the semver package on npm for a detailed explanation of ranges.
Configures which files or file paths are considered when performing conflict checks during theme version upgrades.
List of files or file paths starting from theme/ that are excluded during theme upgrade conflict checks.
List of files or file paths starting from theme/ that are included during theme upgrade conflict checks.
Map of resources to their respective class names, which are typically instantiated to customize resource logic by the storefront app. If applicable, the app must define a /resources/[slug].json endpoint which allows the Swell Theme Editor to load data from the app when necessary.
-> See the Proxima app documentation for details.
Resources are split into two categories:
- singletons: One-off records such as Account and Cart.
- records: All other resources that may be instantiated multiple times throughout a storefront app.
Map of singleton resources to their respective classes in the storefront app. For example, cart: CartResource.
Resource class name provided by the storefront app, for example CartResource.
Map of record resources to their respective classes in the storefront app. For example, products: ProductResource.
Resource class name provided by the storefront app, for example ProductResource.
List of page templates supported by the storefront app, to be displayed in the Swell Theme Editor.
ID of the page, typically corresponding to its file path within a theme app. For example, index to identify the home page.
Label of the page template displayed in the Swell Theme Editor. For example, Home to indicate the home page.
URL of the page route defined by the storefront app. May contain named segments starting with a colon : that are parsed into page parameters at runtime. For example, /products/:slug would indicate a product page route with a slug parameter.
Optional string indicating the icon to display for the page template in the Swell Theme Editor.
The model collection associated with this page, if applicable. Typically a home page would not have a collection, while a product detail page would specify collection: products for example.
A string used to group pages in the page template menu. For example, you might group all account pages with group: customer.
Indicates the page template has a JSON endpoint for fetching page data by the Swell Theme Editor. A JSON endpoint may be provided by the storefront app to supply objects required to render a page initially. The JSON route defined by the storefront app should match the end-user route, adding .json as a suffix.
For example, a product detail page might have a user-facing route such as /products/[slug], and then the corresponding JSON endpoint must be /products/slug.json and must return valid JSON representing the entire data set used to render the page.
For provider: app storefronts only, an array of forms accepted by themes using the form liquid tag (Shopify reference). The storefront app must implement each form configured by this property, according to its own purpose.
ID of the form, used by the form liquid tag.
URL endpoint defined by the storefront app to accept a POST request when the form is submitted.
For provider: app storefronts only, an optional map of collections that are rendered by record-based page templates. For example, products: product would indicate the product detail page supports alternate templates defined within the products collection, assuming page.id: product.
Defines the relationship between a collection and a page that supports record-based templates. For example, [collection]: [page.id].
For provider: app storefronts only, an optional endpoint defined by the storefront used to cache theme pages. The endpoint will be invoked when ever a theme template or file is updated, allowing the theme to leverage its own cache mechanisms.
For storefront apps that are hosted externally, configures the external URLs used to access the storefront.
URL of an external storefront that would display a merchant's online store when accessed. May include dynamic setting values, for example http://example.com/store/{{ merchant_id }}.
URL of an external checkout interface that would display a merchant's checkout when accessed. May include dynamic setting values, for example http://example.com/checkout/{{ merchant_id }}/{{ checkout_id }}.
Note: At the time of this writing, this feature is not fully supported.
For theme apps only, configures theme properties including storefront app compatibility and style presets.
Defines which storefront app and versions are compatible with this theme.
String ID of the storefront app which supports this theme. For example, proxima.
Defines attributes of compatibility between a theme and the storefront app which supports it.
Semver-formatted version range indicating the version of a storefront app that this theme is compatible with. For example, version: * indicates that all storefront app versions are compatible, while version: 1.* indicates that only storefront app version 1.* is compatible.
Defaults to all versions *.
-> See the semver package on npm for a detailed explanation of ranges.
Optional array of styles to configure theme presets and their preview images and colors, and demo URL, to be displayed in the Storefront Theme catalog. These styles should correlate with presets defined by theme settings.
ID of the theme preset, for example dark or light. Defaults to a slug-formatted version of label.
Label to display as the name of the theme preset.
Primary hexadecimal color value to display as a thumbnail, representing the majority of the color palette in the style preset.
Secondary hexadecimal color value to display as a thumbnail, along with the primary color.
Relative path of an image asset representing the desktop preview of the theme. For example, assets/preview-dark.jpg.
Relative path of an image asset representing the mobile preview of the theme. For example, assets/preview-dark-mobile.jpg.
URL of a demo store showcasing the theme style preset.
For storefront and theme apps only, relative path of an image asset representing the main desktop preview of the app in the App Store catalog. For example, assets/preview-desktop.jpg. Required to release storefront apps, unless the storefront's theme is provided by an app.
For storefront and theme apps only, relative path of an image asset representing the main mobile preview of the app in the App Store catalog. For example, assets/preview-mobile.jpg.
Gallery images shown in the App Store catalog. Each item describes one image and points to a file in the app folder 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.
- description: Optional. Maximum 140 characters.
- image_src: Required. Path to the image file relative to the app root, for example assets/screenshots/dashboard.png. The file can live anywhere in the app folder.
ID of the image. For example, products.
Title to display as the name of the image.
Relative path of the image asset. For example, assets/screenshots/products.jpg.
For theme apps only, list of feature highlights shown in the Storefront Theme catalog. Each highlight has a title, an optional description and an optional image. Highlights are not shown for other app types.
ID of the highlight. Defaults to a slug-formatted version of title.
Title to display as the name of the feature highlight.
Text description of the feature to highlight.
Relative path of an image asset representing the feature highlight. For example, assets/feature-sleek-design.jpg.
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.
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.
For storefront and theme apps only, list of enumerated purchase-options to associate with in the App Store catalog.
- standard: Sell one-time purchases.
- subscription: Sell recurring purchases on a schedule.
- preorder: Sell products before they're available for delivery.
More purchase-option enumerations are coming soon.
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.
URL of a website where users can see a demonstration of the app's features and capabilities.
URL of a video demonstrating the app, shown in the App Store catalog.
If the app developer offers support to merchants, URL of the website where a user can get help with the app.
Email address merchants can contact for help with the app. When empty, the support email of your partner account is shown instead.
If the app provides written documentation to merchants, URL of the website where a user can get read the docs.
If the app is open-source, URL of the website where a user can find a Git repository of the app's code base.
Price the merchant must pay to use the app, charged according to price_interval. Defaults to 0 (free).
Indicates the app is paid for through an external service. When true, the merchant pays for access to the app's features externally and Swell does not charge the price. Defaults to false.
Interval on which the app price is charged. When price is greater than 0, defaults to monthly.
- once: The merchant is charged a one-time price for the app.
- monthly: The merchant is charged the app price on a monthly subscription basis.
Optional number of free trial days before the merchant is first charged for the app. Defaults to no trial period.
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.
Unique ID of the extension, referenced by the functions that implement its events.
Human-friendly name of the extension.
Text description of the extension.
Type of platform feature the extension implements.
- payment: Implements a payment gateway.
- shipping: Implements shipment rating and price calculation.
- tax: Implements tax calculation.
ID of the app setting associated with the extension.
For payment extensions, ID of the payment method. Defaults to the extension id.
For payment extensions, relative path of a logo image asset for the payment method.
For payment extensions, relative path of an icon image asset for the payment method.
For payment extensions, ID of the payment gateway implemented by the extension.
For payment extensions, relative path of a logo image asset for the payment gateway.
For payment extensions, relative path of an icon image asset for the payment gateway.
For shipping extensions, ID of the shipping carrier. Defaults to the extension id.
For shipping extensions, relative path of a logo image asset for the carrier.
For shipping extensions, relative path of an icon image asset for the carrier.
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"
]
}