Apps
Fields
id
stringrequiredID of the app, used to identify itself in code. For example, my_app.
name
stringrequiredName of the app.
type
stringType 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.
version
stringSemver-formatted version number. This value can be automatically incremented using the swell app version CLI command. Defaults to "1.0.0".
description
stringA brief description of the app.
permissions
array of permissionAn 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.
storefront
objectFor storefront apps only, configures storefront properties including menu and theme structure.
storefront.menus
array of menuDefault navigation menus instantiated when the app is installed.
menu.id
stringrequiredID of the menu, may be used to reference specific menus from a storefront app or theme.
menu.name
stringrequiredName of the menu for display purposes in the Swell dashboard.
menu.items
array of itemThe menu items.
item.type
stringrequiredType 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.
item.name
stringrequiredName of the item to be displayed in the storefront app or theme.
item.value
stringrequiredFor 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.
item.items
array of itemA sub-menu of items. The sub-items of an item are of the same schema as the top-level items property.
item.item
objectstorefront.theme
objectFor storefront apps that support themes only, defines attributes of theme support and functionality.
theme.provider
stringDetermines 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.
theme.compatibility
objectDefines 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.
compatibility.version
stringSemver-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.
compatibility.conflicts
objectConfigures which files or file paths are considered when performing conflict checks during theme version upgrades.
conflicts.exclude_files
array of pathList of files or file paths starting from theme/ that are excluded during theme upgrade conflict checks.
conflicts.include_files
array of pathList of files or file paths starting from theme/ that are included during theme upgrade conflict checks.
theme.resources
objectMap 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.
resources.singletons
objectMap of singleton resources to their respective classes in the storefront app. For example, cart: CartResource.
singletons.*
stringResource class name provided by the storefront app, for example CartResource.
resources.records
objectMap of record resources to their respective classes in the storefront app. For example, products: ProductResource.
records.*
stringResource class name provided by the storefront app, for example ProductResource.
theme.pages
array of pageList of page templates supported by the storefront app, to be displayed in the Swell Theme Editor.
page.id
stringrequiredID of the page, typically corresponding to its file path within a theme app. For example, index to identify the home page.
page.label
stringrequiredLabel of the page template displayed in the Swell Theme Editor. For example, Home to indicate the home page.
page.url
stringrequiredURL 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.
page.icon
stringOptional string indicating the icon to display for the page template in the Swell Theme Editor.
page.collection
stringThe 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.
page.group
stringA string used to group pages in the page template menu. For example, you might group all account pages with group: customer.
page.json
booleanIndicates 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.
theme.forms
array of formFor 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.
form.id
stringrequiredID of the form, used by the form liquid tag.
form.url
stringrequiredURL endpoint defined by the storefront app to accept a POST request when the form is submitted.
theme.template_collections
objectFor 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.
template_collections.*
stringDefines the relationship between a collection and a page that supports record-based templates. For example, [collection]: [page.id].
theme.cache_hook
stringFor 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.
storefront.external
objectFor storefront apps that are hosted externally, configures the external URLs used to access the storefront.
external.url
stringURL 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 }}.
external.checkout_url
stringURL 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.
theme
objectFor theme apps only, configures theme properties including storefront app compatibility and style presets.
theme.storefront
objectDefines which storefront app and versions are compatible with this theme.
storefront.app
stringString ID of the storefront app which supports this theme. For example, proxima.
storefront.compatibility
objectDefines attributes of compatibility between a theme and the storefront app which supports it.
compatibility.version
stringSemver-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.
theme.styles
array of styleOptional 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.
style.id
stringautoID of the theme preset, for example dark or light. Defaults to a slug-formatted version of label.
style.label
stringrequiredLabel to display as the name of the theme preset.
style.color
stringrequiredPrimary hexadecimal color value to display as a thumbnail, representing the majority of the color palette in the style preset.
style.color_alt
stringSecondary hexadecimal color value to display as a thumbnail, along with the primary color.
style.preview_src
stringRelative path of an image asset representing the desktop preview of the theme. For example, assets/preview-dark.jpg.
style.preview_mobile_src
stringRelative path of an image asset representing the mobile preview of the theme. For example, assets/preview-dark-mobile.jpg.
style.demo_url
stringURL of a demo store showcasing the theme style preset.
preview_src
stringFor 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.
preview_mobile_src
stringFor 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.
images
array of imageList of images to display for the app in the App Store catalog.
image.id
stringID of the image. For example, products.
image.title
stringTitle to display as the name of the image.
image.image_src
stringRelative path of the image asset. For example, assets/screenshots/products.jpg.
highlights
array of highlightList of feature highlights to display for the app in the App Store catalog.
highlight.id
stringautoID of the highlight. Defaults to a slug-formatted version of label.
highlight.title
stringrequiredTitle to display as the name of the feature highlight.
highlight.description
stringText description of the feature to highlight.
highlight.image_src
stringRelative path of an image asset representing app feature highlight. For example, assets/feature-sleek-design.jpg.
features
array of featuresFor 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.
use_cases
array of use_caseFor 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.
purchase_options
array of purchase_optionFor 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.
full_description
stringA longer text description of the app's features and capabilities, to be displayed in the App Store catalog. Supports up to 3,500 characters.
demo_url
stringURL of a website where users can see a demonstration of the app's features and capabilities.
support_url
stringIf the app developer offers support to merchants, URL of the website where a user can get help with the app.
documentation_url
stringIf the app provides written documentation to merchants, URL of the website where a user can get read the docs.
repository_url
stringIf the app is open-source, URL of the website where a user can find a Git repository of the app's code base.
price
currencyPrice the merchant must pay to use the app, charged according to price_interval. Defaults to 0 (free).
price_external
booleanIndicates 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.
price_interval
stringInterval 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.
price_trial_days
intOptional number of free trial days before the merchant is first charged for the app. Defaults to no trial period.
extensions
array of extensionList 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.
extension.id
stringrequiredUnique ID of the extension, referenced by the functions that implement its events.
extension.name
stringHuman-friendly name of the extension.
extension.description
stringText description of the extension.
extension.type
stringrequiredType of platform feature the extension implements.
- payment: Implements a payment gateway.
- shipping: Implements shipment rating and price calculation.
- tax: Implements tax calculation.
extension.setting
stringID of the app setting associated with the extension.
extension.method
stringFor payment extensions, ID of the payment method. Defaults to the extension id.
extension.method_logo_src
stringFor payment extensions, relative path of a logo image asset for the payment method.
extension.method_icon_src
stringFor payment extensions, relative path of an icon image asset for the payment method.
extension.gateway
stringFor payment extensions, ID of the payment gateway implemented by the extension.
extension.gateway_logo_src
stringFor payment extensions, relative path of a logo image asset for the payment gateway.
extension.gateway_icon_src
stringFor payment extensions, relative path of an icon image asset for the payment gateway.
extension.carrier
stringFor shipping extensions, ID of the shipping carrier. Defaults to the extension id.
extension.carrier_logo_src
stringFor shipping extensions, relative path of a logo image asset for the carrier.
extension.carrier_icon_src
stringFor shipping extensions, relative path of an icon image asset for the carrier.
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"
]
}