> 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

{% 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                  |

***

## `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)](/developers/limio-sdk/basket.md) — Adding offers to the basket and initiating checkout
* [Page, Offers & Add-Ons](/developers/limio-sdk/page.md) — Accessing offers and page data
* [Express Checkout](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.