Methods to retrieve and manage cart items and update cart details like shipping and billing information.

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. Items can also be added as a variant with the variant_id.

Returns the updated cart object.

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

Adding items based on the type of purchase option.

Add an item with a purchase option
await swell.cart.addItem({
  product_id: '5e19fefef0295d688e8fa34d',
  purchase_option: {
    type: 'standard'
  }
});

Update properties of a single cart item by the existing item.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.

This setItem operation is only valid for use with cart items that have an existing item.id.

Returns the updated cart object.

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

Remove a single item from the cart with the item.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 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({
  metadata: {
    my_array: {
      $set: [ ... ]
    }
  }
})

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'
  }
})

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'
  }
})