Carts

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.

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.

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.

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.

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.

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.

await swell.cart.removeItem('5c15505200c7d14d851e510f')

Remove all items from the cart.

Returns the updated cart object.

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.

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.

Returns the updated cart object.

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.

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.

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.

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.

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.

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.

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