Frontend API

Retrieve the cart attached to the current session.

Returns the cart object or null if no items have been added yet.

Get a cart
await swell.cart.get()

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.

Returns the updated cart object.

Add an item
// Options as array
await swell.cart.addItem({
  product_id: '5c15505200c7d14d851e510f',
  quantity: 1,
  options: [
    { name: 'Size', value: 'S' },
    { name: 'Color', value: 'Midnight blue' }
  ]
})

// Options as object
await swell.cart.addItem({
  product_id: '5c15505200c7d14d851e510f',
  quantity: 1,
  options: {
    Size: 'S',
    Color: 'Midnight blue'
  }
})

Adding items based on the type of purchase option.

Add an item with a one-time purchase option
await.swell.cart.addItem({
  product_id,
  purchase_option: 'standard'
})
Adding a subscription purchase option with only one plan
await.swell.cart.addItem({
  product_id,
  purchase_option: 'subscription'
})
Adding a subscription purchase option by matching the interval
// This is useful when there's only one plan per interval 
await.swell.cart.addItem({
  product_id,
  purchase_option: {
    plan: 'monthly'
  }
})
Adding a subscription purchase option with its plan_id
// The plan_id is taken from product.purchase_options.subscription.plans.id
await.swell.cart.addItem({
  purchase_option: {
    type: 'subscription',
    plan_id: '...' 
  }
})

Update properties of a single cart item by ID.

Returns the updated cart object.

Update an item
await swell.cart.updateItem('7d51p8ce72f5542e009fa4c8', {
  quantity: 2
})

If you want to update multiple items at once, you can clone cart.items, iterate through the items to perform your operation(s), then use this method to replace cart.items with your updated array.

Returns the updated cart object.

Update all items
await swell.cart.setItems([
  {
    id: '5c15505200c7d14d851e510f',
    quantity: 2,
    options: [{ id: 'Color', value: 'Midnight blue' }]
  },
  {
    id: '5c15505200c7d14d851e510g',
    quantity: 3,
    options: [{ id: 'Color', value: 'Ivory' }]
  },
  {
    id: '5c15505200c7d14d851e510h',
    quantity: 4,
    options: [{ id: 'Color', value: 'Bright red' }]
  }
])

Remove a single item from the cart by ID.

Returns the updated cart object.

Remove an item
await swell.cart.removeItem('5c15505200c7d14d851e510f')

Remove all items from the cart.

Returns the updated cart object.

Empty the cart
await swell.cart.setItems([])

Normally used with an abandoned cart recovery email. The email should have a link to your store with a checkout_id identifying the cart that was abandoned. Calling this method will add the cart to the current session and mark it as recovered.

Returns the recovered cart object.

Recover a cart
await swell.cart.recover('878663b2fb4175b128e40de428cd7b0c')

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 guest=true.
  • If the account has a password set, the cart will have the property account_logged_in=false. You can use this to prompt the user to log in (Link to swell.js account/log-in) to continue. Once the account is logged in, account_logged_in will be true.

Returns the updated cart object.

Update cart account info
await swell.cart.update({
  account: {
    email: 'julia@example.com',
    email_optin: true, // Optional; indicates the customer has consented to receive marketing emails
    password: 'thepassword' // Optional; sets the customer's password if one doesn't exist yet
  }
})

Update the cart with customer shipping information.

Returns the updated cart object.

Update cart shipping info
await swell.cart.update({
  shipping: {
    name: 'Julia Sanchez',
    address1: '560 Olive Drive',
    address2: '',
    city: 'Ellinwood',
    state: 'KS',
    zip: '67526',
    country: 'US', // Two letter ISO country code
    phone: '620-564-3737'
  }
})

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

Returns the updated cart object.

Update cart billing info
await swell.cart.update({
  billing: {
    name: 'Julia Sanchez',
    address1: '560 Olive Drive',
    address2: '',
    city: 'Ellinwood',
    state: 'KS',
    zip: '67526',
    country: 'US', // Two letter ISO country code
    phone: '620-564-3737',
    // Paying with credit card
    card: {
      // Token from swell.card.createToken() or Stripe.js
      token: 'tok_1H0Qu92eZvKYlo2CsKGk6...'
    },
    // Paying with PayPal
    paypal: {
      payer_id: '...',
      payment_id: '...'
    },
    // Paying with Amazon Pay
    amazon: {
      access_token: '...',
      order_reference_id: '...'
    },
    // Paying with Affirm
    affirm: {
      checkout_token: '...'
    }
  }
})

Use the metadata object to store arbitrary values on a cart. As opposed to storing custom fields with the Backend API, the metadata object is publicly accessible, making it easy to add custom data throughout your checkout flow. Note: the metadata object can also be queried and updated using the Backend API.

Returns the updated cart object.

Update cart metadata
await swell.cart.update({
  metadata: {
    any: 'value',
    even: {
      nested: true
    }
  }
})

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 $set operator to override the entire value.

Replace cart metadata array values
await swell.cart.update({
  $set: {
    metadata: {
      my_array: [ ... ]
    }
  }
})

In addition to the top-level metadata field, you can also define metadata on each cart item.

Add metadata to items
await swell.cart.updateItem('7d51p8ce72f5542e009fa4c8', {
  quantity: 2,
  metadata: {
    any: 'value'
  }
})

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
await swell.cart.applyCoupon('SUMMERTIME')

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.

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

Applying a gift card
await swell.cart.applyGiftcard('BUYS SFX4 BMZH YY7N')

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

Remove coupon
await swell.cart.removeCoupon()

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

Remove a gift card
await swell.cart.removeGiftcard('5c15505200c7d14d851e51af')

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 shipping.country 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
await swell.cart.getShippingRates()

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

Applies a shipping service to a cart

// Apply one of the retrieved available shipping services
await swell.cart.update({
"shipping": {  "service": 'my-service' }
}) 

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.

Returns the newly created order.

Submit an order
await swell.cart.submitOrder()

When a cart is submitted, the newly created order will be returned. However, you can use this method if you need to get the order information separately. You can also retrieve an order with a checkout_id, allowing you to display order details from an email containing a link like https://my-store.com/order/{checkout_id}.

Returns order with the passed ID, or if no parameters are passed, the last order placed in the current session.

Get order details
// Get the last order placed in the current session
await swell.cart.getOrder()

// Get an order by checkout_id
await swell.cart.getOrder('878663b2fb4175b128e40de428cd7b0c')

Use to retrieve settings that can affect checkout behavior.

Returns object with:

  • name - Store name
  • currency - Store base currency
  • support_email - Email address for customer support
  • fields - Set of checkout fields to show as optional or required
  • scripts - Custom scripts including script tags
  • accounts - Indicates whether account login is optional, disabled, or required
  • email_optin - Indicates whether email newsletter opt-in should be presented as optional
  • terms_policy - Store terms and conditions
  • refund_policy - Store refund policy
  • privacy_policy - Store privacy policy
  • theme - Checkout style settings
  • countries - List of two letter ISO country codes that have shipping zones configured
  • currencies - List of currencies enabled by the store when using multi-currency
  • payment_methods - List of active payment methods
  • coupons - Indicates whether the store has coupons
  • giftcards - Indicates whether the store has gift cards
Get checkout settings
await swell.cart.getSettings()