> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/developers/limio-sdk/checkout.md).

# Checkout

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

{% hint style="info" %}
Your Limio environment must be on at least v108 to use the pricing features described below.
{% endhint %}

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](https://docs.limio.com/components/component-library/cart-components "mention").

{% hint style="info" %}
`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).
{% endhint %}

***

## `useCheckout` — Accessing checkout state

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

```typescript
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:

```tsx
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`](#usepreview-managing-tax-calculation-states) 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                                         |

{% hint style="warning" %}
`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.
{% endhint %}

### 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:

```tsx
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                  |

### Reading the completed order on the Order Complete page

In a custom component on the Order Complete page, use `useCompleteCheckoutSession`. The standard [Order Complete Details](https://docs.limio.com/components/component-library/cart-components/component-order-complete-details) component uses the same hook. The hook is `useCheckout` with the page type set to `complete`, and it returns the same `useCheckoutSelector` function.

```tsx
import React from "react"
import { useCompleteCheckoutSession } from "@limio/internal-checkout-sdk"

const OrderThanks = () => {
  const { useCheckoutSelector } = useCompleteCheckoutSession()
  const order = useCheckoutSelector((state) => state.order)
  const { order_reference, customerDetails } = order

  return (
    <div>
      {order_reference && <p>Order #{order_reference}</p>}
      {customerDetails?.email && <p>Email: {customerDetails.email}</p>}
    </div>
  )
}
```

| Selector                                                    | Type     | Description                                       |
| ----------------------------------------------------------- | -------- | ------------------------------------------------- |
| `state.order.order_reference`                               | `string` | Reference of the completed order                  |
| `state.order.customerDetails.email`                         | `string` | Email address of the customer                     |
| `state.order.customerDetails.firstName`, `lastName`         | `string` | Name of the customer                              |
| `state.order.billingDetails`, `state.order.deliveryDetails` | `object` | Billing address and delivery address of the order |

The hook suspends your component until the order loads. A value can be absent, so make sure that each value is there before you render it.

***

## `useOrderTotal` — Formatting discount and total display values

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

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

```tsx
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).

```typescript
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:

```tsx
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:

```tsx
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)](https://docs.limio.com/developers/limio-sdk/basket.md) — Adding offers to the basket and initiating checkout
* [Page, Offers & Add-Ons](https://docs.limio.com/developers/limio-sdk/page.md) — Accessing offers and page data
* [Express Checkout](https://docs.limio.com/developers/limio-sdk/advanced-methods/express-checkout.md) — Apple Pay and Google Pay integration


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.limio.com/developers/limio-sdk/checkout.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
