Basket

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 initiateCheckout, addOfferToBasket, removeFromBasket, redeemPromoCode and access to the current list of items.

useBasket Hook

The useBasket hook returns an object containing basket state and methods:

const {
  // State
  orderItems,        // Current items in the basket
  basketLoading,     // True when an async basket operation is in progress
  formattedTotal,    // Formatted total price string (e.g., "£10.00")
  pageOptions,       // Page configuration options

  // Methods
  initiateCheckout,
  addOfferToBasket,
  removeFromBasket,
  updateItemQuantity,
  swapOffer,
  clearOrderItems,
  navigateToCheckout,
  redeemPromoCode,
  removePromoCode,
  updateCustomField,
  setCheckoutDisabled,
  validateBasket,
  updateBasketDetails,
  selectOfferForSubscriptionUpdate,

  // Legacy (deprecated)
  addToBasket,       // Use initiateCheckout or addOfferToBasket instead
  goToCheckout,      // Use navigateToCheckout instead
} = useBasket()

basketLoading - Check if basket operation is in progress

When an async basket operation is running, basketLoading will be true. Use this to disable buttons and prevent double-submissions.

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

const AddToBasketButton = ({ offer }) => {
  const { initiateCheckout, basketLoading } = useBasket()

  return (
    <button
      disabled={basketLoading}
      onClick={() => initiateCheckout({ offer, quantity: 1 })}
    >
      {basketLoading ? "Adding..." : "Add to Basket"}
    </button>
  )
}

Note: Only one async basket operation can run at a time. Attempting to start another operation while one is in progress will throw an error.

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

initiateCheckout - Start a new checkout

Use initiateCheckout when starting a fresh basket (no existing checkoutId). This creates a new basket on the server and returns the checkout ID.

await initiateCheckout(options: InitiateCheckoutOptions): Promise<InitiateOrderResponse>

Options:

You can pass either a single order item or an order object with multiple items:

// Single item (legacy format, still supported)
{ offer: ElasticOffer, quantity?: number, type?: string }

// Multiple items
{ order: { orderItems: [{ offer, quantity, type }], order_type?: string } }

Example - Basic usage:

import React from "react"
import { useBasket } from "@limio/sdk"
import { getCurrentBasketId } from "@limio/shop/src/shop/checkout/basket"

const OfferCard = ({ offer }) => {
  const { basketLoading, initiateCheckout, addOfferToBasket, navigateToCheckout, pageOptions } = useBasket()

  const checkoutId = getCurrentBasketId()

  async function selectOffer() {
    // Use initiateCheckout for new baskets, addOfferToBasket for existing ones
    if (!checkoutId) {
      await initiateCheckout({ order: { orderItems: [{ offer }] } })
    } else {
      await addOfferToBasket({ offer })
    }

    // Optionally navigate to checkout if configured
    if (pageOptions.pushToCheckout) {
      await navigateToCheckout()
    }
  }

  return (
    <button onClick={selectOffer} disabled={basketLoading}>
      {offer.data.attributes.cta_text__limio || "Subscribe"}
    </button>
  )
}

Example - Multiple items:

const { initiateCheckout } = useBasket()

const handlePurchase = async (mainOffer, addonOffer) => {
  const { id, order } = await initiateCheckout({
    order: {
      orderItems: [
        { offer: mainOffer, quantity: 1 },
        { offer: addonOffer, quantity: 1, parentId: mainOffer.id }
      ]
    }
  })
  console.log("Created basket with items:", order.orderItems)
}

Note: This method automatically:

• Creates a new basket on the server

• Sends add_to_cart analytics events

• Sets tracking tags for the offer

---

addOfferToBasket - Add item to existing basket

Use addOfferToBasket when adding items to an existing basket (checkoutId already exists).

await addOfferToBasket(orderItem: InitialOrderItem): Promise<{ id: string }>

Example:

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

const AddAddonButton = ({ addon, parentItemId }) => {
  const { addOfferToBasket, basketLoading } = useBasket()

  const handleAddAddon = async () => {
    const { id } = await addOfferToBasket({
      offer: addon,
      quantity: 1,
      type: "addon",
      parentId: parentItemId
    })
    console.log("Added addon with id:", id)
  }

  return (
    <button disabled={basketLoading} onClick={handleAddAddon}>
      Add {addon.name}
    </button>
  )
}

---

addToBasket (Legacy) - Adding items to the basket

Deprecated: Use initiateCheckout for new baskets or addOfferToBasket for existing baskets instead.

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

• The offer object you want to add.

• 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. This sends remove actions for all items to the server.

await clearOrderItems(): Promise<void>

Example:

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

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

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

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

---

navigateToCheckout - Navigate to checkout page

Navigate to the checkout page. Use this after adding items to the basket.

await navigateToCheckout(options?: GoToCheckoutOptions): Promise<void>

Options:

type GoToCheckoutOptions = {
  journey?: JourneyFunnel  // Optional journey configuration with checkout settings
}

Example:

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

const CheckoutButton = () => {
  const { navigateToCheckout, orderItems, basketLoading } = useBasket()

  return (
    <button
      onClick={() => navigateToCheckout()}
      disabled={basketLoading || orderItems.length === 0}
    >
      Proceed to Checkout
    </button>
  )
}

Note: This method requires a valid basket ID to exist. If no basket has been initiated, it will throw an error.

---

validateBasket - Validate basket contents

Validate the basket against specific rules.

validateBasket(validationType: string): boolean

Supported validation types:

• "preventMixedRates" - Returns false if basket contains items with mixed billing terms

Example:

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

const CheckoutButton = () => {
  const { validateBasket, navigateToCheckout, orderItems } = useBasket()

  const handleCheckout = async () => {
    const isValid = validateBasket("preventMixedRates")
    if (!isValid) {
      alert("Cannot mix different billing terms in the same order")
      return
    }
    await navigateToCheckout()
  }

  return (
    <button onClick={handleCheckout} disabled={orderItems.length === 0}>
      Checkout
    </button>
  )
}

---

updateBasketDetails - Update basket metadata

Update additional details on the basket (e.g., tracking information, metadata).

await updateBasketDetails(body: UpdateBasketDetailsBody): Promise<void>

Note: This method runs as a parallel operation and won't block other basket operations.

---

selectOfferForSubscriptionUpdate - Select offer for subscription updates

For subscription update checkouts only. Select an offer to update as part of the subscription checkout.

await selectOfferForSubscriptionUpdate(orderItem: Partial<UpdateSubscriptionBasketItem>): Promise<void>

Note: Only one offer can be active in a subscription update checkout at a time. Selecting a new offer will reset your checkout.

Example:

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

const UpgradeOption = ({ upgradeOffer }) => {
  const { selectOfferForSubscriptionUpdate, basketLoading } = useBasket()

  const handleSelect = async () => {
    await selectOfferForSubscriptionUpdate({
      offer: upgradeOffer,
      quantity: 1
    })
  }

  return (
    <button onClick={handleSelect} disabled={basketLoading}>
      Select {upgradeOffer.data.attributes.display_name__limio}
    </button>
  )
}

---

goToCheckout (Legacy)

Deprecated: Use navigateToCheckout instead.

Navigate to checkout, optionally initiating or updating the basket first.

await goToCheckout(basketId?: string, options?: GoToCheckoutOptions): Promise<void>