Checkout

This page describes the pricing methods and state available within the Limio SDK for displaying order totals, subtotals, and tax information.

Your Limio environment must be on at least v108 to use the pricing features described below.

Limio provides real-time calculations for order totals, including subtotals, discounts, taxes, and final totals. It provides a preview of tax calculations for countries requiring address based tax determination and includes formatted currency values for display.

Pricing in Limio is managed through three main exports:

• useCheckout — Provides access to checkout state including orderTotals and orderItems
• usePreview — Manages tax preview states and loading indicators
• useOrderTotal — Formats and derives discount/tax display values from order totals

These are also used in Limio's https://docs.limio.com/components/component-library/cart-components.

useCheckout is imported from @limio/internal-checkout-sdk — it is part of the internal checkout SDK and is available inside any component rendered within a checkout context (e.g. checkout pages, cart summaries, order confirmations).

---

useCheckout — Accessing checkout state

The useCheckout hook returns a useCheckoutSelector function that lets you select slices of the checkout Redux state.

import { useCheckout } from "@limio/internal-checkout-sdk"

const { useCheckoutSelector } = useCheckout({ redirectOnFailure: true })

Options:

Param	Type	Description
redirectOnFailure	boolean	Redirect to the shop if the checkout session is invalid
allowEmptyBasketSession	boolean	Allow the checkout to initialise without items in the basket

Reading order totals

The orderTotals object contains all pricing-related data for the current checkout session:

import React from "react"
import { useCheckout } from "@limio/internal-checkout-sdk"
import { formatCurrencyForCurrentLocale } from "@limio/sdk"

const PricingSummary = () => {
  const { useCheckoutSelector } = useCheckout({ redirectOnFailure: true })
  const orderTotals = useCheckoutSelector((state) => state.display.orderTotal)

  const { orderSubtotal, orderTotal, currency, taxSummary } = orderTotals

  return (
    <div>
      <p>Subtotal: {formatCurrencyForCurrentLocale(orderSubtotal, currency)}</p>
      {taxSummary?.map((tax) => (
        <p key={tax.taxCode}>
          Tax ({(tax.taxRate * 100).toFixed(2)}%): {formatCurrencyForCurrentLocale(tax.taxAmount, currency)}
        </p>
      ))}
      <p>Total: {formatCurrencyForCurrentLocale(orderTotal, currency)}</p>
    </div>
  )
}

orderTotals properties:

display.orderTotal is the single source of truth for display. Its base fields are written whenever the basket changes:

Field	Type	Description
currency	string	Currency code (e.g. "USD")
orderSubtotal	number	Order subtotal before discounts and tax
totalOrderDiscounts	number	Order-level discount applied to the subtotal
orderTotal	number	Final order total (orderSubtotal - totalOrderDiscounts)

The tax fields are added only once a preview has run, and are cleared when it is invalidated. Expect them to be undefined before then — see usePreview below:

Field	Type	Description
taxAmount	number	Calculated tax amount
taxSummary	array	Tax breakdowns — each with taxCode, taxAmount, taxRate
totalWithTax	number	Order total including tax
amountWithoutTax	number	Amount excluding tax

amount, totalDiscount and amountBeforeDiscount are also present, but only for backwards compatibility with shops built before release 109. amount is a legacy alias of orderTotal. Prefer orderTotal and totalOrderDiscounts in new code.

Reading order items

You can also select the current order items from the checkout state — for example, to check if the basket is empty or to access blocked products:

import { useCheckout } from "@limio/internal-checkout-sdk"

const CartStatus = () => {
  const { useCheckoutSelector } = useCheckout({ redirectOnFailure: true })

  const orderItems = useCheckoutSelector((state) => state.order.orderItems)
  const isBasketEmpty = orderItems.length === 0
  const blockedProducts = useCheckoutSelector((state) => state.order.blockedProducts)

  if (blockedProducts?.length) {
    return <p>Some items in your basket are not available.</p>
  }

  return <p>{isBasketEmpty ? "Your basket is empty" : `${orderItems.length} item(s) in basket`}</p>
}

Common state selectors:

Selector	Type	Description
state.display.orderTotal	object	Order totals (see above)
state.order.orderItems	array	Items currently in the checkout basket
state.order.blockedProducts	array	Products blocked from purchase (e.g. already owned)
state.order.country	string	Customer's country
state.order.hasDelivery	boolean	Whether any item requires delivery

---

useOrderTotal — Formatting discount and total display values

The useOrderTotal hook takes the raw orderTotals object and returns formatted values for display, including discount calculations.

import { useOrderTotal, formatCurrencyForCurrentLocale } from "@limio/sdk"

import React from "react"
import { useCheckout } from "@limio/internal-checkout-sdk"
import { useOrderTotal, formatCurrencyForCurrentLocale } from "@limio/sdk"

const CartSummary = () => {
  const { useCheckoutSelector } = useCheckout({ redirectOnFailure: true })
  const orderTotals = useCheckoutSelector((state) => state.display.orderTotal)

  const { orderSubtotal, orderTotal, currency } = orderTotals
  const { hasDiscount, discountString, calculatedDiscount, isSpecificItemDiscount } = useOrderTotal(orderTotals)

  return (
    <div>
      <div>
        <span>Subtotal</span>
        <span>{formatCurrencyForCurrentLocale(orderSubtotal, currency)}</span>
      </div>
      {hasDiscount && !isSpecificItemDiscount && (
        <div>
          <span>Discount {discountString}</span>
          <span>-{calculatedDiscount}</span>
        </div>
      )}
      <div>
        <span>Total</span>
        <span>{formatCurrencyForCurrentLocale(orderTotal, currency)}</span>
      </div>
    </div>
  )
}

Returns:

Field	Type	Description
amount	string	Formatted total amount
amountWithoutTax	string	Formatted total excluding tax
taxAmount	string	Formatted tax amount
calculatedDiscount	string	Formatted discount amount
amountBeforeDiscount	string	Formatted total before discount
hasDiscount	boolean	Whether a discount is applied
discountString	string | null	Human-readable discount description (e.g. "(-20%)" or "Saved $5.80"). null when there is no discount.
isSpecificItemDiscount	boolean	Whether the discount is item-specific rather than order-level
discountValue	number	Raw discount value
currency	string	Currency code

---

usePreview — Managing tax calculation states

The usePreview hook provides state for handling tax preview behaviour, particularly important for regions where tax must be calculated based on the customer's address (e.g. US states with varying tax rates).

import { usePreview } from "@limio/ui-preview-context"

Returns:

Field	Type	Description
loadingPreview	boolean	true when the preview API call is in progress (e.g. applying promo codes, recalculating tax)
isTaxPreviewCountry	boolean	true when the customer's country requires address-based tax calculation
taxCalculated	boolean	true when tax has been successfully calculated for the current order

Loading states

Use loadingPreview to show a skeleton while pricing is being recalculated:

import React from "react"
import { useCheckout } from "@limio/internal-checkout-sdk"
import { usePreview } from "@limio/ui-preview-context"
import { formatCurrencyForCurrentLocale } from "@limio/sdk"

const PricingDisplay = () => {
  const { loadingPreview } = usePreview()
  const { useCheckoutSelector } = useCheckout({ redirectOnFailure: true })
  const { orderTotal, currency } = useCheckoutSelector((state) => state.display.orderTotal)

  if (loadingPreview) {
    return <div className="skeleton" />
  }

  return <p>Total: {formatCurrencyForCurrentLocale(orderTotal, currency)}</p>
}

Tax-excluded regions

Use isTaxPreviewCountry and taxCalculated together to handle regions where tax is calculated at checkout:

import React from "react"
import { useCheckout } from "@limio/internal-checkout-sdk"
import { usePreview } from "@limio/ui-preview-context"
import { formatCurrencyForCurrentLocale } from "@limio/sdk"

const TotalWithTax = () => {
  const { isTaxPreviewCountry, taxCalculated } = usePreview()
  const { useCheckoutSelector } = useCheckout({ redirectOnFailure: true })
  const { orderTotal, currency, taxSummary } = useCheckoutSelector((state) => state.display.orderTotal)

  return (
    <div>
      <p>Total: {formatCurrencyForCurrentLocale(orderTotal, currency)}</p>

      {isTaxPreviewCountry && !taxCalculated && (
        <p>Tax excluded — calculated at checkout</p>
      )}

      {taxSummary?.map((tax) => (
        <p key={tax.taxCode}>
          Tax ({(tax.taxRate * 100).toFixed(2)}%): {formatCurrencyForCurrentLocale(tax.taxAmount, currency)}
        </p>
      ))}
    </div>
  )
}

---

See also

• Basket (Cart) — Adding offers to the basket and initiating checkout
• Page, Offers & Add-Ons — Accessing offers and page data
• Express Checkout — Apple Pay and Google Pay integration