Swell.js is a universal JavaScript SDK for Swell's Frontend API, providing helper methods for common data and actions needed to create storefronts and checkout flows.

Fetch products, categories, store settings, nav menus, and custom content

Create, recover, and update shopping carts

Build custom checkout and subscription flows

Authenticate customers and allow them to edit account details, orders, and subscriptions

Resolve linked content to dynamically generate page URLs

Introduction

The library can be used in any bundled JavaScript application, in server or client contexts.

Add swell-js dependency to your project:

The client uses your store ID and public key for authorization. You can find these in your dashboard under 

If your application uses camelCase, you can set a flag to transform the API's snake_case responses. This works on objects you pass to it as well.

Example

Setup

 prefix when the method returns a promise. All other methods are synchronous. We're using ES6 async/await syntax here, but you can use regular Promises, too.

Basic usage

 is a ready-to-go progressive web app (PWA) storefront built with Nuxt.js. It is configured and hosted automatically when creating a new store, but can be re-configured and replaced by a custom storefront, or hosted by another provider such as 

For custom builds, Origin storefront serves as an ideal starting point or example implementation using Swell.js.

Storefront theme

Use settings to make storefront apps responsive to admin preferences such as store name, locale, currency, etc. In addition to 

 properties described below, app-specific settings are included in the result set.

Example settings

Methods to retrieve settings may return a promise if all settings haven't been 

Returns the entire store settings object.

Get all settings

Returns a value from the store settings object using path notation, with an optional default if the value is undefined.

Get settings by path

Returns an object representing store settings, and saves it to an internal cache for accessing synchronously.

 when initially loading a storefront so that all other calls to 

Load all settings

Returns an array containing store navigation menus, and saves it to an internal cache for accessing synchronously.

Retrieve all nav menus

Get nav menu by ID

Returns an object representing payment settings and saves it to an internal cache for use with 

Retrieve payment settings

Settings

Returns all products, with offset pagination using 

List products

Returns all products and their active variants, with offset pagination using 

List products with variants

Returns products in a specific category, with offset pagination using 

List products by category

Get a product

Returns a single product variation matching selected options.

 values based on the customer's chosen options. Typically you would 

(link to retrieve a product) earlier in the page's lifecycle and pass it to this method along with the options. Options can be either an array or an object with option name/value pairs.

Returns a new object with product and option/variant values merged together.

Get a product variation

Perform a full text search with a string. The search operation is performed using AND syntax, where all words must be present in at least one field of the product.

Returns products matching the search query string, with offset pagination using 

Search for products

Methods to simplify product filtering, typically as part of a search or category page. The type of filters supported include price range, categories, and attributes.

Returns an array of filters given a list of products as input.

List filters

Price and category filters are identified explicitly by 

 IDs, respectively. Other filters are identified by their attribute ID.

Product filters

 object when retrieving products. Each property represents a filter by ID, and an array of values to filter the resulting product list.

Applying filtering

Products

Retrieve product attributes to display in a storefront.

Returns a list of product attributes, with offset pagination using 

List attributes

Get an attribute

Attributes

Retrieve product categories to display in a storefront.

Returns a list of product categories, with offset pagination using 

List categories

Get a category

Get a cart

Add a single item to the cart. Item options can be either an array of product options or an object with product option name/value pairs.

Add an item

Adding items based on the type of purchase option. 

Add an item with a one-time purchase option

Adding a subscription purchase option with only one plan

Adding a subscription purchase option by matching the interval

Adding a subscription purchase option with its plan_id

Update properties of a single cart item by ID.

Update an item

If you want to update multiple items at once, you can clone 

, iterate through the items to perform your operation(s), then use this method to replace 

Update all items

Remove a single item from the cart by ID.

Remove an item

Empty the cart

Normally used with an abandoned cart recovery email. The email should have a link to your store with a 

 identifying the cart that was abandoned. Calling this method will add the cart to the current session and mark it as 

Recover a cart

Add customer account information to the cart, either for checking out as a guest or setting up a full customer account with a password before submitting the order.

Accounts are assigned to a cart by email address.

If the account has no password set, it's considered a guest checkout and the cart will have the property 

If the account has a password set, the cart will have the property 

. You can use this to prompt the user to 

 (Link to swell.js account/log-in) to continue. Once the account is logged in, 

Update cart account info

Update the cart with customer shipping information.

Update cart shipping info

Update the cart with customer billing information. This method can update both shipping and billing at once if desired.

Update cart billing info

 object to store arbitrary values on a cart. As opposed to storing custom fields with the 

, the metadata object is publicly accessible, making it easy to add custom data throughout your checkout flow. Note: the 

 object can also be queried and updated using the Backend API.

Update cart metadata

When updating nested arrays in metadata, you may notice the default behavior is to merge instead of replacing values. To replace array values, use the 

Replace cart metadata array values

 field, you can also define metadata on each cart item.

Add metadata to items

Use to apply a coupon or gift card code to the cart (works with both so you can have a single input field). A cart can have one coupon and multiple gift card codes applied at once. Codes are not case-sensitive.

Returns the updated cart object if code is valid. Otherwise, returns a validation error.

Applying a coupon/giftcard

Use to apply a gift card code to the cart. A cart can have multiple gift card codes applied at once. Codes are not case-sensitive.

Applying a gift card

Use to remove the coupon code from the cart, if one was applied.

Remove coupon

Use to remove a gift card from the cart; pass the ID that was assigned to 

Remove a gift card

A shipment rating contains all available shipping services and their price, based on cart items and the customer's shipping address. The cart must have at least 

 set to generate a rating. Shipping services must be configured through the Swell backend. 

Returns an object with shipping services and rates.

Get shipping rates

A shipment service can be added to the cart by referencing it directly. 

When a customer has entered all the information needed to finalize their order, call this method to process their payment and convert the cart to an order.

Submit an order

Carts

Authenticate customers, fetch and manage their account data.

Use to authenticate a customer with their email address and password. If the email/password combo is correct, their account will be added to the session, making customer-specific methods available. This will set 

Log in

Use to disconnect the account from the current session. This will set 

Log out

Use to get information about the customer currently logged in.

Get logged in account

Use to create a new customer account and attach it to the current session.

Returns the newly created account object.

Create an account

Use to update properties of the account that is currently logged in.

Returns the updated account object if successful. Otherwise, returns a validation error.

Update the account

 object to store arbitrary values on an account. As opposed to storing custom fields with the

, the metadata object is publicly accessible, making it easy to add custom data throughout your customer flow. Note: the 

 object can also be queried and updated using the Backend API. 

Update the account metadata

Replace array values for account updates

 method to send an email to the customer with a link to reset their password. If the email address provided doesn't exist in the system, no email will be sent.

Send a password reset email

To customize the password reset URL sent to the customer in an email, pass the optional parameter 

, including a placeholder for the password reset key: 

. Swell will automatically generate and substitute the password reset key in the URL before sending an email.

Customize reset password URL

Use to set the customer's new password. This requires the 

 from the recovery email (see above). The password recovery email should link to your storefront with 

 as a URL parameter that you can pass to this method.

Reset an account password

Use to get a list of addresses on file for the account. These are stored automatically when a non-guest user checks out and chooses to save their information for later.

Returns all addresses, with offset pagination using 

List addresses

Returns the newly created address object.

Create an address

Use to remove an existing address from the account by ID.

Delete an address

Use to get a list of credit cards on file for the account. These are stored automatically when a non-guest user checks out and chooses to save their information for later.

List saved credit cards

Use to save a tokenized credit card to the account for future use. Credit card tokens can be created using 

Create a new credit card

Use to remove a saved credit card from the account by ID.

Delete a credit card

Return a list of orders placed by a customer.

List account orders

Get an account order

Return a list of orders placed by a customer including shipments with tracking information.

Returns all orders, with offset pagination using 

List account orders with shipments

Accounts

Manage subscriptions associated with the logged-in customer's 

Return a list of active and canceled subscriptions for an account.

Returns all subscriptions, with offset pagination using 

List subscriptions

Get a subscription

Subscribe the customer to a new product for recurring billing.

Create a new subscription

Update a subscription

Change subscription plan

Pauses a subscription indefinitely or skip a billing cycle.

Pause a subscription

Cancel a subscription

Add an invoice item

Update an invoice item on a subscription.

Update an invoice item

Update all invoice items on a subscription.

Update all invoice items

Remove all items

Subscriptions

Render third-party payment elements with settings configured by your Swell store. This method dynamically loads third-party libraries such as Stripe, Braintree, and PayPal, in order to standardize the way payment details are captured.

Render Stripe elements to capture credit card information. You can choose between a unified 

Render a Stripe card element

Rendering separate Stripe card elements

Rendering iDeal

Render a Paypal checkout button

 with Stripe, it's necessary to tokenize card details before submitting a payment form. Some payment methods such as PayPal will auto-submit once the user completes authorization via PayPal, but tokenizing is always required for credit card elements.

 will automatically update the cart with relevant payment details. Otherwise, returns a validation error.

Tokenize elements

Payments

Reference for Swell's client-side Frontend API. 

Filter

Categories

List categories

Get a category