{metadata.title}

In this guide, you'll learn how to show the cart totals in the checkout flow. This is usually shown as part of the checkout and cart pages.

Cart Total Fields

The Cart object has various fields related to its totals, which you can check out in the Store API reference.

The fields that are most commonly used are:

<Table> <Table.Header> <Table.Row> <Table.HeaderCell>Field</Table.HeaderCell> <Table.HeaderCell>Description</Table.HeaderCell> </Table.Row> </Table.Header> <Table.Body> <Table.Row> <Table.Cell> `subtotal` </Table.Cell> <Table.Cell> The cart's subtotal before discounts, excluding taxes. Calculated as the sum of `item_subtotal` and `shipping_subtotal`. </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> `discount_total` </Table.Cell> <Table.Cell> The total amount of discounts applied to the cart, including the tax portion of discounts. </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> `shipping_total` </Table.Cell> <Table.Cell> The sum of all shipping methods' totals after discounts, including taxes. </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> `tax_total` </Table.Cell> <Table.Cell> The cart's tax total after discounts. Calculated as the sum of `item_tax_total` and `shipping_tax_total`. </Table.Cell> </Table.Row> <Table.Row> <Table.Cell> `total` </Table.Cell> <Table.Cell> The cart's final total after discounts and credit lines, including taxes. </Table.Cell> </Table.Row> </Table.Body> </Table>

Example: Show Cart Totals in React Storefront

Here's an example of how you can show the cart totals in a React component:

This example uses the useCart hook from the Cart Context to retrieve the cart.

</Note>

export const highlights = [ ["3", "useCart", "The useCart hook was defined in the Cart React Context documentation."], ["8", "formatPrice", "A function to format a price using the Intl.NumberFormat API."], ["23", "formatPrice", "Show the cart's subtotal"], ["27", "formatPrice", "Show the total discounts"], ["31", "formatPrice", "Show the shipping total"], ["35", "formatPrice", "Show the tax total"], ["39", "formatPrice", "Show the total amount"], ]

tsx

"use client" // include with Next.js 13+

import { useCart } from "@/providers/cart"

export default function CartTotals() {
  const { cart } = useCart()

  const formatPrice = (amount: number): string => {
    return new Intl.NumberFormat("en-US", {
      style: "currency",
      currency: cart?.currency_code || "USD",
    })
    .format(amount)
  }

  return (
    <div>
      {!cart && <span>Loading...</span>}
      {cart && (
        <ul>
          <li>
            <span>Subtotal (excl. taxes)</span>
            <span>{formatPrice(cart.subtotal ?? 0)}</span>
          </li>
          <li>
            <span>Discounts</span>
            <span>{formatPrice(cart.discount_total ?? 0)}</span>
          </li>
          <li>
            <span>Shipping</span>
            <span>{formatPrice(cart.shipping_total ?? 0)}</span>
          </li>
          <li>
            <span>Taxes</span>
            <span>{formatPrice(cart.tax_total ?? 0)}</span>
          </li>
          <li>
            <span>Total</span>
            <span>{formatPrice(cart.total ?? 0)}</span>
          </li>
        </ul>
      )}
    </div>
  )
}

In the example, you first retrieve the cart using the Cart Context. Then, you define the formatPrice function to format the total amounts.

Finally, you render the cart totals in a list, showing the subtotal, discounts, shipping, taxes, and the total amount.

Retrieve and Show Cart Item Totals

You can also show the totals specific to each item in the cart. This is useful when you want to show the price breakdown for each item, such as price before and after discounts.

The cart item totals aren't included by default in the cart object. You need to explicitly expand the items.* relation when retrieving the cart. This will add item totals like total, subtotal, tax_total, and discount_total to each item object in the cart. You can learn about other total fields in the Store API reference.

For example, when retrieving the cart, you can expand the items.* relation like this:

sdk.store.cart.retrieve(cartId, {
  fields: "+items.*",
  // TIP: You can also expand both items and shipping methods at the same time
  // fields: "+items.*, +shipping_methods.*",
})
.then(({ cart: dataCart }) => {
  setCart(dataCart)
})

Then, you can show the item totals in a React component like this:

tsx

"use client" // include with Next.js 13+

import { HttpTypes } from "@medusajs/types"

type CartItemTotalsProps = {
  cart: HttpTypes.StoreCart
}

export default function CartItemTotals({
  cart,
}: CartItemTotalsProps) {
  const formatPrice = (amount: number): string => {
    return new Intl.NumberFormat("en-US", {
      style: "currency",
      currency: cart.currency_code,
    })
    .format(amount)
  }

  return (
    <ul>
      {cart.items.map((item) => (
        <li key={item.id}>
          <span>{item.title}</span>
          <span>{formatPrice(item.total!)}</span>
          <span>(Subtotal: {formatPrice(item.subtotal!)})</span>
          <span>(Discounts: {formatPrice(item.discount_total!)})</span>
          <span>(Taxes: {formatPrice(item.tax_total!)})</span>
        </li>
      ))}
    </ul>
  )
}

In the example, you receive the cart with the expanded item totals as a prop. Then, you define the formatPrice function to format the total amounts.

Finally, you render the cart items in a list, showing each item's title, total, subtotal, discounts, and taxes.

Retrieve and Show Shipping Method Totals

You can also show the totals specific to each shipping method in the cart. This is useful when you want to show the price breakdown for each shipping method, such as price before and after discounts.

The cart shipping method totals aren't included by default in the cart response. You need to explicitly expand the shipping_methods.* relation when retrieving the cart. This will add shipping method totals like total, subtotal, tax_total, and discount_total to each shipping method object in the cart. You can learn about other total fields in the Store API reference.

For example, when retrieving the cart, you can expand the shipping_methods.* relation like this:

sdk.store.cart.retrieve(cartId, {
  fields: "+shipping_methods.*",
  // TIP: You can also expand both items and shipping methods at the same time
  // fields: "+items.*, +shipping_methods.*",
})
.then(({ cart: dataCart }) => {
  setCart(dataCart)
})

Then, you can show the shipping method totals in a React component like this:

tsx

"use client" // include with Next.js 13+

import { HttpTypes } from "@medusajs/types"

type CartShippingMethodTotalsProps = {
  cart: HttpTypes.StoreCart
}

export default function CartShippingMethodTotals({
  cart,
}: CartShippingMethodTotalsProps) {
  const formatPrice = (amount: number): string => {
    return new Intl.NumberFormat("en-US", {
      style: "currency",
      currency: cart.currency_code,
    })
    .format(amount)
  }

  return (
    <ul>
      {cart.shipping_methods.map((method) => (
        <li key={method.id}>
          <span>{method.name}</span>
          <span>{formatPrice(method.total!)}</span>
          <span>(Subtotal: {formatPrice(method.subtotal!)})</span>
          <span>(Discounts: {formatPrice(method.discount_total!)})</span>
          <span>(Taxes: {formatPrice(method.tax_total!)})</span>
        </li>
      ))}
    </ul>
  )
}

In the example, you receive the cart with the expanded shipping method totals as a prop. Then, you define the formatPrice function to format the total amounts.

Finally, you render the cart shipping methods in a list, showing each method's name, total, subtotal, discounts, and taxes.