Basket (Cart), Promo Code

This page describes all of the basket (or cart) methods available within the Limio SDK.

The Limio basket (also referred to as the cart) is a Limio object used to hold order items as a customer browses, selects offers and add-ons, and input promo codes. It enables users to build their order incrementally—adding, updating, or removing offers— as part of a pricing page, a cart page or a checkout page.

The basket is a key part of the Limio Subscription Commerce Platform and supports complex subscription logic. It is managed via the Limio SDK using hooks such as useBasket, which provides methods like addToBasket, removeFromBasket, redeemPromoCode and access to the current list of items.

orderItems - Retrieving items in the basket

Previously named basketItems (updated in release 109). References to basketItems should be updated where used to orderItems. The underlying data is the same.

You may want to display to users what items they have in their basket, whether this is as part of a navigation bar dropdown, or somewhere else on the page. The items can be retrieved using orderItems which are returned from the useBasket method.

import React from "react"
import { useBasket } from "@limio/sdk"

const Basket = () => {
  const { orderItems } = useBasket()
  
  return (
    <section>
      <h1>Your Basket</h1>
      {orderItems.map(item => (
        <div>
          <h2>{item.name}</h2>
          <p>{item.data.display_description__limio}</p>
          <p>{item.data.display_price__limio}</p>
        </div>
      ))}
    </section>
  )
}

Example orderItems:

[
  {
    id: "4b35bb3e-a50e-4eb2-9946-ebff2876f987",
    quantity: 1,
    offer: {
      id: "d5b8eca9273dba0b971c33d56c3f81c65b6aaa87.97d170e1550eee4afc0af065b78cda302a97674c",
      name: "Dummy Offer",
      path: "/offers/Dummy Campaign/Dummy Offer",
      parent_path: "/offers/Dummy Campaign",
      type: "item",
      data: {
        name: "Dummy Offer",
        tags: ["/tags/dummytag"],
        segments: [],
        attributes: {
          // All configured offer attributes will be returned
          price__limio: [
            {
              delay_interval_type: "months",
              subscription_start_day: "",
              name: "charge_1",
              repeat_interval: 1,
              attributes: [],
              label: "Charge 1",
              trigger: "order_date",
              repeat_interval_type: "months",
              repeat_count: 1,
              type: "recurring",
              value: "10.00",
              currencyCode: "GBP"
            }
          ],
          display_description__limio: "Dummy offer description",
          display_price__limio: "£10 a month forever",
          detailed_display_price__limio: "Pay £10 upfront for your first month, then £10.00 a month thereafter.",
          offer_features__limio:
            "<h3>Dummy offer subscription benefits:</h3><ul><li>Unlimited web access</li><li>Smartphone and tablet apps</li><li>Save articles and share them with friends and family</li><li>Comment on articles and join conversations with our journalists</li><li>Newsletters exclusively for subscribers</li><li>Video exclusives</li></ul>",
          cta_text__limio: "Subscribe Now",
          payment_types__limio: ["zuora_card"],
          display_name__limio: "Dummy Offer",
          group__limio: "Dummy Group",
          checkout__limio: {
            checkout_type: "standard"
          },
          autoRenew__limio: true
        },
        attachments: [
          {
            path: "/assets/Images/Devices",
            name: "Devices",
            type: "image/png",
            url: "/public/f60388d3-28ca-4a5c-ba38-51cf04eb93bd/responsive.png"
          }
        ],
        products: [
          {
            name: "Dummy Product",
            path: "/products/Dummy Product",
            attributes: {
              product_code__limio: "SKU-00000001"
            },
            type: "item"
          }
        ],
        type: "item",
        familyName: "offers"
      }
    },
    upsell: [
      {
        mode: "production",
        path: "/offers2/Essentials 1 Device 1 Year",
        data: {
          name: "Premium Upgrade",
          attributes: {
            display_name__limio: "Essentials Premium"
          }
        }
      }
    ],
    crossSell: [
      {
        mode: "production",
        path: "/offers2/Optimizer - 10 Devices - 1 Year",
        data: {
          name: "Optimizer",
          attributes: {
            display_name__limio: "Optimizer"
          }
        }
      }
    ]
  }
]

addToBasket - Adding items to the basket

You can add an item to the basket using the addToBasket method. This method requires two parameters:

• The offer object you want to add (see Working with Offers for details on configuring offers).

• An options object that may include:

  • quantity: The number of units to add.

Example

The following example combines getOffers to display a list of available offers and addToBasket to allow a user to add an offer to their basket:

import React from "react"
import { useCampaign, useBasket } from "@limio/sdk"

const Offers = () => {
  const { offers } = useCampaign()
  const { addToBasket } = useBasket()
  
  return (
    <section>
      {offers.map(offer => (
        <div>
          <h1>{offer.name}</h1>
          <button onClick={() => addToBasket(offer, { quantity: 1 })}>
            Add to basket
          </button>
        </div>
      ))}
    </section>
  )
}

removeFromBasket - Removing items to the basket

Just as you can add an item to the basket using the addToBasket method, you can remove an item using removeFromBasket.

The removeFromBasket method requires a single parameter: an object containing the id of the item you want to remove. This id corresponds to the OrderItem that was previously added to the basket.

Example

The following example displays an item in the user's basket and allows them to remove it using the removeFromBasket method from the Limio SDK. The component receives an individual OrderItem (referred to as basketItem), retrieves the offer and product details, and renders the item label. It also includes a button to remove the item from the basket.

This is commonly used in Limio Checkout pages to display the current basket state and provide users with control over their selections.

import type { OrderItem } from "@limio/types"
import * as React from "react"
import { useBasket } from "@limio/sdk"
import { Button, Icon, Text } from "@limio/component-library"
import { faTimes } from "@fortawesome/free-solid-svg-icons"

type CartItemProps = {
  item: OrderItem
}

const CartItem = ({ basketItem }: CartItemProps): React.JSX.Element => {
  const offerAttributes = basketItem.offer.data.attributes
  const product = basketItem.offer.data.products[0]
  const { removeFromBasket } = useBasket()

  const onRemove = async () => {
    await removeFromBasket({ id: basketItem.id })
  }

  return (
    <div>
      <div>
        <div>
          <div>
            <Text size="medium" weight="emphasised">
              {product.attributes.display_name__limio} - {offerAttributes.display_name__limio}
            </Text>
          </div>
          <div>
            <Button size="icon" variant="text" onClick={onRemove}>
              <Icon icon={faTimes} size="lg" />
            </Button>
          </div>
        </div>
      </div>
    </div>
  )
}

export default CartItem

updateCustomField - Updating custom field

You can add a custom field to the Limio order payload - and send it to third-party systems such as Zuora - by using the updateCustomField method. To do this, provide the name of the custom field and the value you want to assign. This value can be user-provided, such as from a field in the Limio Modular Checkout.

import React from "react"
import { useBasket } from "@limio/sdk"

const CustomField = () => {
  const { updateCustomField } = useBasket()
  
  const updatePartnershipNumber = (partnershipNumber) => {
    return updateCustomField("partnershipNumber", partnershipNumber)
  }
  
  return (
    <section>
      <div>
        <h1>Partnership Number</h1>
        <input onChange={(e) => updatePartnershipNumber(e.target.value)} />
      </div>
    </section>
  )
}

If you use Zuora as the integrated billing system, Limio will automatically set those Custom Fields on the Subscription object with Zuora. You can also specify other objects by appending .account to the custom field, as follow:

updateCustomField("userNumber.account", userNumber)

Finally, you will be able to find your custom fields in the customFields object within the order object:

{
    order: {
        customerDetails: {...},
        billingDetails: {...},
        deliveryDetails: {...},
        orderItems: [...],
        customFields: {
            "partnershipNumber": "123456",
            "userNumber.account": "789012" 
        }
    }
}

setCheckoutDisabled - Disable / Enable the checkout

You can enable/disable the Limio checkout, using the setCheckoutDisabled method. This will allow for the checkout to be disabled until additional logic is carried out in an independent component, for example. The setCheckoutDisabled method requires a boolean argument to set the state of the checkout and can be called as follows:

import React from "react"
import { useBasket } from "@limio/sdk"

const DisableCheckout = () => {
  const { setCheckoutDisabled } = useBasket()
  
  return (
    <section>
      <div>
        <button onClick={(e) => setCheckoutDisabled(true)} />
      </div>
    </section>
  )
}

expiresAt - Get the expiration time and date of a Basket

Baskets can expire based on how the original Session was requested. By default this is two weeks after the Session was requested. A customer can use the Basket's expiresAt attribute to understand when the Session is no longer valid and handle it on the frontend. The expiresAt attribute is returned as a UTC ISO timestamp e.g. 2023-09-20T14:50:14.679Z

import React from "react"
import { useBasket } from "@limio/sdk"

const ExpiredCheckout = () => {
  const { expiresAt } = useBasket()
  const now = new Date().toISOString()
  const basketExpired = expiresAt < now
  
  if(basketExpired) {
    alert("Basket expired!")
  }
  
  return (
    <section>
      <div>
        <button disabled={basketExpired} onClick={() => checkout()}>Checkout</button>
      </div>
    </section>
  )
}

redeemPromoCode - validate and add discount to basket

This function allows you to validate a promo code and apply the associated discount to the basket. A valid promo code name must be passed to the function in order to successfully validate.

import React from "react"
import { useBasket } from "@limio/sdk"

const PromoCodeRedeem = () => {
  const { redeemPromoCode } = useBasket()
  
  const onSubmit = async () => {
      const { id: limioCheckoutId } = await redeemPromoCode(promoCode)
  }

  return (
    <section>
      <div>
        <button onClick={onSubmit}>Redeem</button>
      </div>
    </section>
  )
}

removePromoCode - remove promo code from basket

This can remove an applied promo code from a basket. A customer can then either reapply that same promo code, apply a different promo code, or apply no promo code and checkout successfully.

import React from "react"
import { useBasket } from "@limio/sdk"

const PromoCodeRemove = () => {
  const { removePromoCode } = useBasket()
  
  const onRemove = async () => {
      const { id: limioCheckoutId } = await removePromoCode(promoCode)
  }

  return (
    <section>
      <div>
        <button onClick={onRemove}>Remove Promo Code</button>
      </div>
    </section>
  )
}

swapOffer

Swap an existing order item with a different offer (useful for upgrades/downgrades).

await swapOffer(itemId: string, offer: ElasticOffer): Promise<void>

Example:

import React from "react"
import { useBasket } from "@limio/sdk"

const SwapOfferComponent = ({ currentItemId, newOffer }) => {
  const { swapOffer } = useBasket()

  const handleSwap = async () => {
    await swapOffer(currentItemId, newOffer)
  }

  return (
    <button onClick={handleSwap}>
      Upgrade to Premium
    </button>
  )
}

Note: This method:

• Removes the old item from the basket

• Adds the new offer with the same item ID

• Sends both remove_from_cart and add_to_cart data layer events

• Automatically syncs the basket with the server

---

updateItemQuantity

Update the quantity of an existing order item.

await updateItemQuantity(itemId: string, quantity: number): Promise<void>

Example:

import React from "react"
import { useBasket } from "@limio/sdk"

const QuantitySelector = ({ item }) => {
  const { updateItemQuantity } = useBasket()

  const handleQuantityChange = async (newQuantity) => {
    await updateItemQuantity(item.id, newQuantity)
  }

  return (
    <div>
      <button onClick={() => handleQuantityChange(item.quantity - 1)}>-</button>
      <span>{item.quantity}</span>
      <button onClick={() => handleQuantityChange(item.quantity + 1)}>+</button>
    </div>
  )
}

---

clearOrderItems

Remove all items from the basket.

clearOrderItems(): void

Example:

import React from "react"
import { useBasket } from "@limio/sdk"

const ClearBasketButton = () => {
  const { clearOrderItems, orderItems } = useBasket()

  const handleClear = () => {
    if (confirm(`Remove all ${orderItems.length} items from basket?`)) {
      clearOrderItems()
    }
  }

  return (
    <button onClick={handleClear}>
      Clear Basket
    </button>
  )
}

---