Basket / Cart

This page describes all of the basket methods available within the Limio SDK.

basketItems - Retrieving items in the basket

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 basketItems which are returned from the useBasket method.

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

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

Example basketItems:

[
  {
    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"
      }
    }
  }
]

addToBasket - Adding items to the basket

It's simple to put an item into the basket using the addToBasket method. The addToBasket requires you to pass the item you want to add (see this section for details on offer items), and an options object containing, selectedProducts (if applicable), quantity and the location (redirectUrl) the offer was added from.

Example of adding an item to the basket (this example also uses getOffers to display the offers ready to be added to the basket):

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

const Offers = () => {
  const { offers } = useCampaign()
  const { addToBasket } = useBasket()
  
  // This is used for the Limio checkout to know where return the user should
  // they want to leave the checkout and go back to the landing page.
  let redirectUrl = ""
  if (typeof window !== undefined) {
    const search = qs.parse(window?.location?.search)
    redirectUrl = search["redirect_url"] || ""
  }
  
  return (
    <section>
      {offers.map(offer => (
        <div>
          <h1>{offer.name}</h1>
          <button onClick={() => addToBasket(offer, { quantity: 1, redirectUrl })}>
            Add to basket
          </button>
        </div>
      ))}
    </section>
  )
}

updateCustomField - Updating custom field

You can update a custom, i.e. non Limio field, using the updateCustomField method. The updateCustomField method required you to pass in the name of the new Custom Field as well as the value you wish for it to be set as:

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

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

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"
        }
    }
}

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