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
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"
}
}
}
]
addToBasket
- Adding items to the basket
addToBasket
- Adding items to the basketYou 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:selectedProducts
: An array of selected product identifiers (if applicable).quantity
: The number of units to add.redirectUrl
: The location the user should be redirected to after adding the item (for example the checkout).
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()
// 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>
)
}
removeFromBasket
- Removing items to the basket
removeFromBasket
- Removing items to the basketJust 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
updateCustomField
- Updating custom fieldYou 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
setCheckoutDisabled
- Disable / Enable the checkoutYou 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
expiresAt
- Get the expiration time and date of a BasketBaskets 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>
)
}
Last updated
Was this helpful?