Build and organize the foundations of your Swell store such as your payments, checkout, shipping, taxes, notifications, users, and more. You can also set advanced user permissions and use developer tools to finely tune your operations. If your business requirements change you can adjust these settings as needed.

You can access and manage your store's general settings by navigating to Settings > General from the dashboard. These configuration items allow you to define various unitary preferences such as weight and currency—as well as manage some customer-facing information for contacting your store.

Update the name of your store or provide customer support contact information in this section in order to drive customer support inquiries to the desired email or telephone number.

The next section is where you will enter your business address. As stated, the address entered here will be used to calculate shipping rates by default. The default shipping rates can be specified to use a separate location should your fulfillment not take place from your business address.

The timezone of your store can be changed to align with the dates you see on your dashboard. You can also configure additional language support for your Swell store by adding locales for languages. See our multi-language guide for more information.

The currency and weight system of the products you sell in your Swell store can also be changed. Here, you can add support for a variety of currencies within your Swell store—choose the appropriate options from their respective drop-down menus. See our multi-currency guide for additional information on setting up multiple currencies.

You can also customize your order number format by adding a prefix and a starting number. Leave this blank if you wish to keep the default settings.

On the account page, you can manage your monthly plan, payment information, and access your account invoices. These settings are found under the Settings > Account within the dashboard.

To change your account plan, click Change on the current plan box. Here you can choose the preferred plan from the options available. You will need to confirm your selection before any change takes place.

If so desired, you can also pause your account at the bottom of the page to disable your store which you can resume at any point.

You can update your billing card on file by clicking the Edit button beside your existing payment information. You will be prompted to provide your new payment credentials.


For enterprise plans, you will need to contact your enterprise support team in order to make changes to your account's billing information.

Your account section also includes a running history of your Swell account's billing invoices. The Invoices table lists each billing cycle's invoice, the invoice amount, the data, and its payment status. To view an individual invoice, click on the invoice number within the table. You can print an invoice from within the page view.

Swell has direct support for a number of payment methods, including credit cards, alternative processors, gift cards, account credits, and generic support for manual payments.

There are two main ways credit cards work within your store: test mode and through a real payment gateway. You may only configure one credit card gateway (at a time) within your store.

To configure a payment gateway, such as Stripe, WorldPay,, Braintree, and others, you’ll need to set up an account with the gateway provider and enable this gateway within your store by providing the credentials to Swell. Each payment gateway has its own configuration requirements—when selecting the gateway, you will be prompted within the window to provide the necessary information or directed through a setup flow. Once properly configured, Swell will use this gateway to process payments for orders that are paid via credit card.


In addition to credit card payments, Swell also offers the ability to use alternative payment methods as your primary means of collecting payments from customers.


When creating a Swell store, the payment gateway is set to a test environment by default.

In addition to processing payment gateways, you may also enable the Test gateway, which should only be used when initially configuring your store. It is exclusively for internal development or testing. When the Test gateway is selected, you may simulate credit card payments within the checkout flow by providing the credit card number 4242 4242 4242 4242 4242, any security code, and any future expiry date.

You can change to a test gateway any time by going to Settings > Payments, selecting Edit settings on the credit card section, and switching the Live mode toggle to the off position.


Credit card numbers other than 4242 4242 4242 4242 4242 will fail to work when the Test gateway is enabled.

External alternative methods include methods such as Klarna, PayPal, Paysafecard, Affirm, and Amazon Pay. To use these services, you’ll need to authorize your Swell store with the third-party payment provider, so you’ll need to set up an account with them. Multiple external methods can be used simultaneously, and they can be used alongside credit card payment gateways as well.

In addition to the external methods, Swell offers internal payment methods: gift cards, account credits, and generic manual payments. Each of these methods can be enabled or disabled independently of other payment configurations.

  • Gift cards are pre-paid balances associated with specific card codes, to be used at checkout, in lieu of (or in addition to) regular payment methods.
  • Account credits are associated with specific accounts within your store, and at checkout, an account holder with a credit balance can choose to use it to pay (in part or whole) for their order. Account credits are automatically applied towards a purchase.
  • Manual payments are a generic way for you to set up other payment methods for your store. These payments are used for processes external to your Swell store, such as “Cash on Delivery” or “Paid by Check”. It is up to you to manage the status of orders paid with these methods, as the actual payment takes place outside of your Swell store. You may add multiple manual payment methods, or remove them entirely. These transactions will need to be marked on the order status manually from within the Swell dashboard.

You can configure additional settings for order payments when they are submitted by a customer. They provide control for determining how your store handles payment with new orders.


Access these settings in your dashboard under Settings > Orders.

Orders (other than manual payments), by default, will be charged automatically when they are submitted by the customer. If you prefer, you can turn this setting off to delay charges. This could be useful in situations where the product is created on-demand, and you don’t want to charge the customer until it’s ready to ship.

Orders will also be “authorized” against your payment gateway by default. This means that the gateway will be asked to reserve funds in the card holder’s account, but the transaction will not actually be completed (funds transferred from the card’s account to your account) until the transaction is completed. If you’d like to allow orders to go through your store without this requirement, you can turn off payment authorization.

You can configure additional settings for subscription payments such as dunning rules for failed payments and automatic invoice billing. These provide control for determining how your store handles capturing subscriptions payments each billing cycle.


Access these settings in your dashboard under Settings > Subscriptions.

The last type of payment configuration is for subscriptions. By default, subscription invoices will automatically be charged to customers when they become due, but this can be turned off if you’d prefer to handle this manually.

When subscription payments fail, you can create a dunning schedule to help you manage retries: the number of times to retry, the number of days between retries, and how to handle invoices that fail after retries are exhausted (do nothing, mark as unpaid, or cancel subscription). For more information on dunning rules, see our subscriptions guide.

Swell’s hosted checkout is included with every Swell store. You can customize several aspects of how your store handles checkouts—and you can always implement your own custom checkout solution should you wish to. You can manage your Checkout settings by navigating to Settings > Checkout on the dashboard.

Changes to the visual elements of the checkout process can be made through the storefront’s visual editor. You can access the checkout customization through the visual editor under Design & global settings > Checkout or through the dashboard under Settings > Checkout with the Customize checkout button.

You can choose whether to require a customer to log in to their account on your store to complete a checkout. By making it optional, you allow guest checkouts, which can increase conversion for first-time customers and decrease the number of account sign-ups. You can also disable accounts entirely if your needs are simple enough not to benefit from the customer accounts feature.

Requiring that a customer be logged in helps identify repeat customers for promotions and business analytics and for customers to track order history, subscriptions, account credit, etc.

You can choose whether to display an email opt-in during checkout and whether its default state is opt-in or opt-out. A customer who opts in permits you to send promotional emails, which can be a helpful sales and communication tool for your store.

Different jurisdictions and business requirements have different needs for collecting data from customers. Swell makes it easy to configure these inputs when customers are completing their checkout.

It is often smoother and more accessible for customers depending on the information you wish to capture during the checkout process. It is recommended to require only what is necessary in order to provide a seamless checkout experience—there is a higher chance of conversion when requiring minimal input from the customer.

The field display options are as follows:

  • You can require a customer to enter their last name, or their first and last name.
  • For accounting and shipping reasons, it is often necessary to require that a customer enter their company name. This field can be required, optional, or hidden.
  • Phone numbers can also be required, optional, or hidden. Many shipping carriers require a phone number, so they can contact the address to which they are delivering.
  • For addresses, some customers will expect to be able to split their address into two lines (such as “Unit 42” on the second line), but this is not always needed and can be set to hidden (it can also be optional or required).
  • You can optionally provide a place for customer comments on orders. This is sometimes used by vendors to customize orders and could be used for other purposes such as recording delivery instructions or a space to say “Thanks!”.

Swell provides a field for entering custom JavaScript to the order confirmation page. Scripts can be used for many purposes—vendors often use them to track that an order has been completed through analytics tooling, such as campaign tracking in Google Tag Manager.

By default, the checkout return URL is set to your store’s homepage URL. This can be changed by enabling the custom return link, then entering the desired return URL in the input field. Doing this allows you to specify where the user is taken within your store after they checkout.

By enabling the custom order receipt page, you can add the URL for a custom receipt page to be displayed to the user in place of the default Swell receipt page. This dynamically generates the receipt page by referencing a Swell order id.

You can specify your store’s Refund policy and Privacy policy, as well as your Terms of service. If added, they will be displayed to the customer (as linked pages) at checkout. For more information on how to populate these, see our articles in the Privacy and security section.

You can define rules and logic for shipping price calculation within your store by navigating to Settings > Shipping within the dashboard. From here, you can create and define geographically based rules and configure your offered shipping services.

To get started, you’ll need to determine your shipping zones—or the geographic areas and grouped shipping destinations. Shipping zones let you define what shipping services and pricing rules should be applied based on the destination address of an order. It’s common to have one shipping zone match the country you’re located in, a regional one (e.g., Europe), and a catch-all “rest of world” zone for everywhere else.

Swell offers a flexible and straightforward approach to configuring shipping zones, so no matter how simple or complex your needs are, we’ve got you covered. For each zone you want to add, you can include one or more countries or include all remaining areas (i.e., the rest of the world—everywhere not already included in a shipping zone). And for each country, you can include or exclude specific regions (such as specific states or ZIP codes within the United States). Once you have your shipping zones defined, you’re ready to define your shipping services.

Navigate Settings > Shipping from the Swell dashboard and select Add shipping zone to create a shipping zone. A new window will open for you to define the shipping zone’s regions and provide a name for the shipping zone. Press Save to finalize your selections once you have configured the shipping zone.

You can Edit and Remove shipping zones as needed from the list of zones found under Settings > Shipping in the Swell dashboard. You can also drag and reorder the shipping zones into any configuration you prefer within the shipping zones table.

Shipping services are the options presented to your customers when choosing a shipping service during checkout. The service name is what your customers see (e.g., “UPS” or “FedEx”), and the description may or may not display based on your template. For each service, define a price, a maximum package weight, and whether the price and max weight applies to the entire order or each individual package (consignment). Then, define what zones this service is valid for, and we’ll take care of the rest.

Each shipping service can also feature particular rules that are configured when creating or editing a shipping service. Use these rules to specify price overrides or add fees to a shipping service based on a variety of conditions such as the number of packages in the order, the package weight, customer groups, shipping addresses or regions, and more. These rules enable you to further refine a shipping service that may increase shipping cost due to different reasons and pass that additional cost (or discount) on to the customer once an order meets the set conditions for the shipping rule.

Navigate Settings > Shipping from the Swell dashboard and select Add shipping service to create a shipping zone. A new window will open for you to define the shipping zone’s regions and provide a name for the shipping zone. You can also add shipping rules to the service by selecting Add rule. Press Save to finalize your selections once you have configured the shipping zone.

Shipping services can be enabled or disabled by selecting the service and selecting the Enabled toggle within the shipping service configuration window. You can see which services are currently enabled or disabled under the Status column from the shipping services table.

You can Edit and Remove shipping services as needed from the list found under Settings > Shipping in the Swell dashboard. You can also drag and reorder the shipping zones into any configuration you prefer within the shipping services table.

Swell also offers the ability to use product-specific shipping. This can be helpful if you sell some products that require more expensive shipping fees due to their bulk, for example.

To define shipping rules that apply to a specific product, use the Shipping tab on the product page. From there, you can add a shipping rule that will override your default shipping settings. This matches based on the conditions you set, and if those conditions are met, you can either override the price or simply add a fee to the standard shipping price.

Swell’s shipping services can be configured to set prices per package. When configuring the package quantity, this informs the system of the maximum amount of items that can fit per package. It uses the quantity and weight of that number of items to determine how many packages will be used in shipping—dynamically calculating the price based on both variables. This provides the ability to control the number of items shipped in each package and limits the shipment weight for those packages to more effectively calculate total shipping costs.

Swell offers the ability to manage tax settings within your store, and also provides integration capabilities for third-party tax experts, such as TaxJar and Avalara. Store tax configuration (without using one of the integrations) is broken up into two sections: tax rules and calculation options. To access your store's tax settings, navigate to Settings > Taxes in the Swell dashboard.

You may add multiple tax rules for Swell to use to calculate taxes for your store’s orders. Each rule has a name, the rule can be applied to specific product categories (as defined in the store’s and also), and product locations (defined as Store locations in the store’s shipping settings). You can also specify whether to apply this tax rule to an order’s shipping price.

Additionally, you can choose which product tax classes—whether a product has been defined as physical (Standard) or digital (Digital)—as well as to which customer tax classes this tax rule should be applied.

Each rule has priority. Taxes for a rule are either added to other rules with the same priority or compounded with rules of a lower priority. Different jurisdictions require different applications of tax rules, and the priority setting gives you a tool to assist with this calculation.

Priorities are best illustrated with examples. For each of these examples, let’s assume an order taxable amount of $100. These can be configured in more complex forms than the provided examples, but let’s cover three of the most common use cases.

For this example, we have a single tax rule with a priority of 1. This rule has an effective rate (see rates, below, for more fine-grained implementation) of 5%.

Since there’s a single tax rule, the calculation is simple: a taxable amount of $100 plus 5% is $105.

In this case, let’s apply a provincial or state tax of 4% and a federal tax of 3%. Both taxes have a priority of 1 in this case, so the taxes are added together:

  • 4% of the taxable amount of $100 is $4 (this is the provincial/state tax)
  • 3% of the taxable amount of $100 is $3 (this is the federal tax)
  • the total applicable taxes, in this case, is $4 + $3 = $7
  • for a total of $107

Most taxes in the US (state, county, city, special) are calculated using this method.

Some jurisdictions require taxes to compound. Let’s apply the same rates as the previous example: a provincial/state tax of 4% and a federal tax of 3%. The provincial/state tax has a priority of 1 and the federal tax has a priority of 2:

  • 4% of the taxable amount of $100 is $4 (this is the provincial/state tax)
  • However, the federal tax has a larger priority number (2), so this amount is calculated on the applicable taxed amount of the provincial/state tax: 3% of the taxable amount of $104 is $3.12 (this is the federal tax)
  • The total applicable taxes, in this case, is $4 + $3.12 = $7.12
  • For a total of $107.12

Observant readers might notice that the customer is required to pay tax on tax in this scenario. This is a less common implementation, but (as an example) it was the case in the Canadian province of Québec until 2013.

Each tax rule can have multiple tax rates, which are additional configurations that tell Swell how to apply taxes to specific locations. Tax rates have a name, a rate percent, and a specific location (country and state/province). Tax rate locations can even apply to a specific postal or ZIP code.

These options allow you to configure your store to comply with your local tax regulations or your own preferences for how taxes are applied. In order to access all of the following calculation options, select Show advanced options.

  • Product prices include tax: indicates if the prices you’ve specified for your store’s products include applicable taxes
  • Shipping prices include tax: this is to configure shipping prices to include applicable taxes; note that for some jurisdictions, shipping taxes depend on multiple factors such as where an item is shipping from, or shipping to, and both of those could indicate whether or not taxes need to be charged on a shipping fee, and can be partially determined by Taxable location
  • Apply taxes after discounts: should taxes be applied before discounts are subtracted or after (this is the default behavior)
  • Apply discounts after taxes: enable if discounts should be calculated after taxes are added
  • Taxable location: the location that should be used for determining the tax location for an item (either shipping or billing address)
  • Calculation source: determines which value is used for tax calculation (Order total, Item total, or Product price)

Swell provides several settings and options for sending customers (and in some cases, store admin) notifications for different events that occur within your store. You can manage the content and settings of your notifications by navigating to Settings > Notifications in the Swell dashboard. Here you will find all notifications sorted by the following areas of your store:

  • Orders: contains confirmations, order status updates, and abandoned cart recovery emails.
  • Shipping: provides confirmations and updates for shipping to customers.
  • Customers: welcome new users when they create accounts and send password reset emails.
  • Subscriptions: notices for new subscriptions, changes to subscriptions, and dunning rules.
  • Payments: send payment confirmations to customers.
  • Admin: notify your Swell store’s admin when new orders are received.

You can enable or disable notifications for your store by switching the toggle to the desired state.


Please note that some notifications cannot be disabled.

All store notifications can be edited and styled to your liking. To begin editing a notification, click on its purple title. This will open an editor window with several tabs. Each tab and its function are outlined below:

  • Preview: The preview tab displays a visual mock-up of the email notification for quick reference of any changes made to the notification.
  • Fields: In this tab, you can customize the text fields populated on the notification and their contents. Enable the Edit fields toggle at the bottom left of the window to manage the fields. You will be able to add, edit, remove and rearrange the fields on the notification.
  • Template: This tab allows you to view and change the notification email's Email subject line and allows for customizing and formatting the notifications HTML in the Email body.
  • Settings: Here, you can designate the From email and BCC emails for each notification. The From email will be displayed as the return address, and any email addresses listed in the BCC emails field will receive a copy of the notification when it is sent. Both of these are optional, and the From email defaults to your store's Customer support email, which is accessed under Settings > General.
  • Test email: To confirm your email is displaying as desired, you can send test emails by entering the desired address to receive the email and selecting Send. You can also change the locale for the test email to test various languages if you have them enabled in your store.

One of Swell’s unique features for notifications is the Abandoned cart recovery sequence. You can create abandoned cart emails to help recover customers who have left your store before finishing their purchase. These notifications are sent after a set duration of customer inactivity to customers who have items in their cart, prompting them to complete their order.

To customize your Abandoned cart recovery section, ensure that the toggle for Abandoned cart notifications is Enabled.

  • Each notification can be scheduled and sent at the desired date and time after inactivity.
  • Add follow-up email will create another email for the abandoned cart recovery sequence.
  • Clicking on the notification's title will open the editor window for formatting and customizing the template.

Like abandoned cart emails, the subscription dunning sequence is intended to recover missed payments on subscription plans that encounter expired payment information. You can create a series of emails and payment processing behavior to notify customers and retry payment methods should the initial charge not go through. See our dunning rules section in our subscription guide for more info.

Your store's notifications can include a logo image for branding purposes. Add your logo under the Branding section by clicking Add image or by dragging and dropping the image you would like to use in the window. You can also adjust the formatting of the Logo width and designate a Primary color for UI elements such as buttons within the notifications. More information about hex color codes can be found at the HTML color codes website.

On Swell, users are individuals who have been granted access to your Swell store's backend. While logged in, these users can access and complete various tasks (based on their permissions level) within the dashboard for store operations and upkeep. These users can also be store admin, which have comprehensive access to a particular store.

Each pricing plan has a set number of admin users you can add:

  • The community plan supports up to 3 admin users
  • The standard plan supports 10 admin users
  • The enterprise plan gives you an unlimited number of users

If you have more than one store owner or wish to grant access to other users, navigate to Settings > Users on the dashboard and click the Invite user button on the top right of the page. Enter the user's email address and adjust the permissions according to your preference. Press Save to finalize and send the invitation.


By default, new users invited to a store will receive full access.

Once an invitation has been sent, you can adjust a user's permissions by selecting the user within the User tab in the dashboard. From there, disable the Full permission toggle, and select the areas from the list for which you want the user to have access (the user will not be able to access unchecked areas). Press Save to update the permissions.

For users that wish to utilize the developer tools, they will need to enable it either during their account creation or alternatively, they can enable it from within their user profile under Settings > Users. Once enabled, they will have access to the Developer tools section within the dashboard. Read more

Each user can also choose to enable notifications for orders that are placed within the store. With this feature enabled, they will receive an email notification each time a customer places an order.

You can change your name, email address, and other information on your user profile by visiting your profile page. This can be accessed by clicking the drop-down beside your name on the dashboard and selecting Your profile.


You are able to configure your preferences for Developer tools and order notifications within your profile as well.

We recommend setting a secure password and changing it on a regular basis to maximize account security. You can change your password by clicking the Change password button, entering a new one, and clicking Save.

Change the profile picture on your account by clicking the blank icon beside your name and email. You will be prompted to choose an image on your computer and it will be set as your profile picture.

Enterprise accounts have the ability to further customize permissions for their users working within the Swell dashboard.


This feature is only available for Enterprise accounts.

Allow users to only access what they need within the Swell dashboard by configuring user roles and permissions. Roles can restrict viewing certain areas of the dashboard, provide limited access, or allow full control over specific content.

Each role is configured by a defined set of permissions, and each area of the dashboard is assigned its own permission level. The permission level determines what level of access a user with a given role will have for a specific area of the dashboard.

There are four permission levels used to define the access permissions for each default or custom role within the dashboard:

  1. Full: provides complete control to view, create, delete, and edit
  2. Manage: provides the ability to access and edit existing entries
  3. View: only allows viewing of existing entries in a respective area of the dashboard
  4. Restrict: prevents the user from accessing that part of the dashboard

There are several roles that are included by default for Enterprise accounts. These roles can be used immediately and require no prior configuration before assignment. These default roles can also be edited and customized based on your company's specific needs.

Default roles and their permissions levels:

  • Admin: Full access across all areas of the dashboard.
  • Developer: Full access for Integrations, Storefront, Developer, and Settings / General; View access for all other areas of the dashboard.
  • Marketing: Full access for Promotions, Manage access for Coupons, and View access for all other areas of the dashboard.
  • Merchandiser: Manage access for Products, Orders, Subscriptions, Promotions, Settings / Orders, and Settings / Subscriptions; View access for all other areas of the dashboard.
  • Operations: Full control for Orders and Subscriptions, Restrict access for Storefront and Developer, and View access for all areas of the dashboard.
  • Read-only: View access for all areas of the dashboard.

User roles can only be edited by users who have the appropriate permissions level for Settings / Users. Those with access can assign, manage, remove, and customize role permissions and users' roles in the dashboard.

Additional roles can be created and customized by navigating to Settings > Users and selecting New role. From there, enter the role name, the desired permission levels for each entry, and save the role. Once saved, it can be assigned to existing users and used in email invitations when adding new users.

For existing users, roles can be updated by selecting the particular user for which you wish to assign a role, choosing the role from the drop-down, and saving the changes. When inviting new users, select the desired role from within the invitation window before sending the invite.

Swell's developer tools are located in the Developer section of the dashboard. These tools include access to Models, Explorer, Webhooks, API keys, and Console. Below is an overview of each of the areas within the Developer tools.


If you don't see the Developer menu in the dashboard navigation, you must enable Dev tools on your Swell user profile.

Developer models can be used to create and manage models and fields with the API. The Models section also allows you to see your changes occur in real-time from the dashboard. While you cannot delete the standard set of models, you can reset them to their default states to remove any unwanted changes. You can create, edit, and delete custom fields and models.

The model explorer allows you to experience your store's data model structures and changes in real-time. View, organize, and interact with your models through a visual interface within the dashboard.

All of your store's data models are represented in the model explorer, including store settings and custom models. Here, you can search for models, fields, and relationships (edges) between models. Field descriptions (like name, type, and the field's definitions) are displayed. Clicking a field displays the JSON representation directly from the database.

Webhooks allow developers to add custom functions to their Swell store. You can add webhooks by navigating to Developer > Webhooks on the dashboard and clicking Add webhook.

You will then need to enter the URL of the webhook, an alias, and events. When you are finished, click the Save on the popup window and Save changes on the settings page.

API access is located under Developer > API keys on the Swell dashboard. Here you can access both your public and secret keys. Add a new key by selecting the Add secret key or Add public key button. This will generate a new key and add it to the list of existing keys.

The developer console allows you to run API requests on your store's backend using GET, PUT, POST, and DELETE functions.

Swell supports the ability to sell globally with the ability to configure localization for language and currency. Learn more about setting up our multi-language and multi-currency features within your store.

You can configure multiple locales to enter and display content in any language. Only locales enabled by you will be visible to customers in a storefront. On the frontend, a storefront may use Swell.js to retrieve and display localized content.

Navigate to Settings > General and find the link to Enable multi-language under the heading Locale and timezone. Clicking this link will enable settings for your default locale and reveal a new action labeled Add locale.

In the Add locale window, you may customize the label used in a storefront to represent the locale selection. Once multiple locales are configured, it's possible to change your default locale using the Set as default action from the Edit window.


Changing your default locale will not affect any existing content, but it will immediately affect the content displayed in a storefront when no specific locale is selected.

Toggle Require content for this locale in order to force the dashboard interface to require a value when saving changes, if the field is normally required. Choose any Fallback locale to cause storefront content to default to this value if a content field is left empty.

Disabling a locale will hide it from the storefront, while it will continue to be available in the dashboard for content editing. To disable multi-language, remove each of the configured locales one by one.

In the Swell dashboard, users can select locales to edit content in place by clicking the locale icon in the top portion of a page or modal window. Extra input fields will be present for each selected locale. This way, any standard or custom text field can be localized, including email notification fields.

Under the Fields tab of the notification edit window (for example, Settings > Notifications > Order confirmation), users have the ability to customize and localize text used in a notification template. Toggle Edit fields to add, remove, or re-order existing notification fields. Preview notification content and send test emails in any configured locale.

A storefront app can configure settings and content types with a localized property to enable the localization of text fields in the Swell storefront editor. Swell Checkout has its own language fields that can be edited by navigating to Design & global settings > Checkout > Language.

Developers can manage localized content for custom interfaces using the Swell API. For more details, read the API reference.

Swell's multi-currency allows you to accept payments in multiple currencies, set conversion fallback logic, and choose price conversion behavior. Customers can view prices and make purchases in enabled currencies within your storefront.

On the frontend, a storefront can use Swell.js to format and convert display prices. When a currency is selected, a method is used to format and convert prices to one of those currencies. Display conversions are performed using exchange rates provided by Swell which are updated daily from data.

Aside from your default currency, you can add and configure additional currencies for your store. To add currencies to your store, multi-currency must be enabled. This is found by navigating to the Currency and weights section under Settings > General. Once enabled, you can add currencies by choosing Add currency below the currency table.

When creating new currencies there are several configuration options:

  • Decimal digits: Specifies how many decimal digits the currency displays.
  • Label: Allows for display names to be specified in enabled languages.
  • Enabled toggle: Enables or disables the currency. This determines whether it is active within the dashboard and the storefront.
  • Priced: Enabling allows for transactions in the currency if selected during checkout. Disabling makes the currency display-only and transactions will be made in your store's base currency.
  • Require values for the currency: Requires that prices are defined for this currency.
  • Use conversion rate as fallback: Enables live conversion rates if a price is not defined. This determines how the conversion rounds to the chosen decimal.

It is possible to change your store's base currency by selecting the Set as default action from a currency's Edit window.


Be aware that changing your store's base currency will affect all new records including orders. New products will be denominated in the updated base currency without affecting existing ones. To disable multi-currency, remove each currency from the list.

There are three states for currencies within your store. Each currency's state determines its level of function and is displayed within the Kind column within the Currency table.

This is the default currency of your store. The base currency is used to determine all conversions rates for other currencies and the prices displayed within your store.

Currencies with the Priced toggle disabled will be designated as display currencies. This allows for the currency to be shown in the store, but it will not be supported for payments. Purchases made with display currencies will be charged with your base currency.

Currencies added with the Priced toggle enabled are designated as priced. Transactions can be made with these currencies during checkout.

For transactions with priced currencies to be successful, your payment gateway must also support those currencies. Customer purchases with a paid currency that are not supported by your payment gateway will result in an error.

When a storefront uses Swell.js to manage currency selection, carts associated with an active customer session will automatically be tied to the customer's chosen currency. This causes Swell Checkout to reflect prices accordingly. In addition to converting prices for display currencies, a notice informs the customer that their payment method will be charged in the amount of the base currency. This notice is only shown when conducting a transaction with display currencies. Currencies that are priced will be charged in the appropriate currency if the payment gateway supports them.


It's important to inform users of the actual total in your base currency. They may incur a fee from their payment provider for performing a currency conversion during the sale. If your storefront uses a custom checkout, consider adding a similar notice to inform customers of this potential.

For example, your base currency is set to USD, and a customer chooses to view display prices in EUR. The Swell Checkout will show a notice under the cart total stating: "Your payment method will be charged USD $19.95".

Once your currencies have been configured, you can use them throughout your dashboard when defining explicit pricing for things like products and shipping rates. All areas where currency pricing can be specified will feature a drop-down icon in the top right. Selecting a currency and enabling it from the drop-down will add a field for inputting the price in each selected currency.

Access and customize your models and create custom fields directly from the dashboard within the model editor. This tool can be found by navigating to the Developer > Models tab within the dashboard's left-hand navigation menu.

The model editor performs identically to the existing methods of creating and managing models and fields through the API. It also provides the ability to see your changes occur in real-time from the dashboard.

From the Models tab, you can view and edit your models and their associated fields. While you cannot delete the standard set of models, you can reset them to their default states to remove any unwanted changes. Custom models you have created can be deleted.

To create a new model, click the New model button on the top right of the window. This will bring you to the new model creation page. Here, you can specify the:

  • Model name: The name of your cool, new model.
  • API endpoint: This will be the endpoint for which you can post to the model via the API. Defaults to the model name.
  • Namespace: Can be None, Custom, or Content. Custom allows you to designate a preferred name, while Content assigns to it to the .content namespace—allowing the data to be accessed via a public API key.
  • Description (optional): A description of the model and its intention.
  • Custom fields: Add custom fields and input types for the model.

Once you have configured your model to your preference, press Save. Your model will now be accessible via the Models table to view or edit as needed.

To edit a model, select it from the table within the Models tab. When editing an existing model, you can:

  • Add additional fields under the Content fields tab
  • View the model's data fields under Data fields
  • See the model's entire JSON configuration via the JSON tab

You can add fields directly to new or existing models by clicking Add field from within a model's options. This allows you to customize the data stored within a model and tailor them to your particular store's information needs.

When creating a new field, the first step is to choose the field type. You have several field types to choose from for capturing a variety of inputs.

Available field types:

  • Short text: field for a single line of text
  • Long text: field for multiple lines of text
  • Number: field for numerical values
  • Select: choose from a list of options
  • Boolean: toggle a value on or off
  • Date: field for date and time input
  • Media: choose an asset from a media library
  • Tags: field to input a set of tags
  • Color: field to pick a color value
  • Icon: choose from a list of icons
  • Lookup: choose an existing record
  • Collection: a collection of multiple fields

When adding to a model that displays in the dashboard menu (i.e., orders, products, customers, subscriptions, etc.), you can select a field location to specify where the field shows up on the page for editing.

After choosing the field type, designate the field's Label and Field ID in the Settings tab. The Field location can be added once the label has been created. If needed, you can choose a different field type by clicking the Change the field type button.

  • The Localization toggle can be used to support additional languages.
  • The Default value toggle will revert the field type to its original state.
  • The Change field type button will take you back to the field selection.

You can also designate whether a custom field is shown and editable within the admin dashboard. Choose Hidden under the Admin field location section if you wish to prevent this from being a visible and editable field within the dashboard.

Similar to models, you can create an API namespace for the custom field. Custom provides the ability to give a preferred name while Content will assign the public .content namespace, allowing that data to be accessed via a public API key.

Preview and tweak the field's UI in real-time within the custom fields User interface tab. All edits made within the window are reflected in the Preview section. You can also access basic HTML and Rich HTML variants of the field. Certain fields also support a Placeholder for the field, and you can designate a Description to provide additional context for the field that will display within a hoverable tool tip.

From the Validation rules tab, you can access and set different validation rules for the field type. To enable any validation rule, click the toggle to its enabled state.

Validation rules can specify:

  • Whether a field is a required value.
  • Whether the value must be unique.
  • Other parameters particular to the field tyle (e.g., character count limits for text fields).

Though there are many ways to utilize custom fields to implement your business logic, here are a few real-world examples to help get your creative juices flowing.

Have a new item planned for release at a particular time? Are certain products only available during a specific season, month, or day? Add in date fields to specify a product's availability time-frames in the collections model.

If you are operating a marketplace or feature products being sold by different vendors or brands, you can create a new model to capture any desired custom fields specific to a vendor or seller and relate them to their products.

Provide users the ability to shop within a store to purchase items from the same location by customizing product categories. This allows shipments to be combined rather than shipping from two different sellers or locations.

There are many more ways to implement this feature, and its overall design is intended to provide you with the flexibility and convenience of adding new fields when a need for one arises.

A new visualization tool that enables you to get the most out of Swell's data models. This tool can be found by navigating to the Settings tab.

The model explorer provides a new way for you to experience your store's data model structures. View, organize, and interact with your models through a visual interface within the dashboard. All of your store's data models are represented in the model explorer, including store settings and custom models.


  • Canvas view that displays within the dashboard
  • Search for models, fields, and relationships (edges) between models
  • Displays field descriptions like name, type, and the field's definitions
  • Clicking a field displays the JSON representation directly from the database
  • Reflects changes to data models in real-time

You can move and arrange the models by selecting and dragging them within the model explorer. Any models that have a relation to another model keep their relationship intact while being moved.


The arrangement of models does not persist beyond a current session, so reloading the model explorer will return your models to their original positions.

You can move around the canvas by clicking and dragging. Alternatively, you can move vertically by scrolling. Holding Ctrl while scrolling up will zoom in, and holding Ctrl and scrolling down will zoom out.

The explorer also features navigation UI such as a mini-map and a navigation menu. With the navigation menu, use:

  • The plus sign to zoom in closer
  • The minus sign to zoom out
  • The framed corners to expand the view to fill the entire screen
  • The lock icon to lock the currently selected model, preventing it from being moved until the model is unlocked

The search results are categorized and displayed by type. Results show models, fields, and edges–the relationships between models. All parts of a model are searchable and can be found through the search bar. Selecting a result will take you to that instance's location within the model explorer.

Interrelated models are represented within the model explorer by a purple thread featuring a name based on the relation type.

When selecting a specific field, the model explorer displays the JSON field definition. This can be used as a reference to see backend values for a particular field or array.

The model explorer is a new way of visualizing the relationships between your store schema. Use it as a reference for insight into your store's functionality, and see how specific changes may impact the rest of your models.