Retrieve Cart Totals using Query

In this guide, you'll learn how to retrieve cart totals in your Medusa application using Query.

You may need to retrieve cart totals in your Medusa customizations, such as workflows or custom API routes, to perform custom actions with them. The ideal way to retrieve totals is with Query.

How to Retrieve Cart Totals with Query#

To retrieve cart totals, you mainly need to pass the total field within the fields option of the Query. This will return the cart's grand total, along with the totals of its line items and shipping methods. You can also pass additional total fields that you need for your use case.

For example, to retrieve all totals of a cart:

The returned cart object will look like this:

Code
1{2  "id": "cart_123",3  "currency_code": "usd",4  "total": 10,5  "subtotal": 10,6  "tax_total": 0,7  "discount_total": 0,8  "discount_subtotal": 0,9  "discount_tax_total": 0,10  "original_total": 10,11  "original_tax_total": 0,12  "item_total": 10,13  "item_subtotal": 10,14  "item_tax_total": 0,15  "original_item_total": 10,16  "original_item_subtotal": 10,17  "original_item_tax_total": 0,18  "shipping_total": 10,19  "shipping_subtotal": 10,20  "shipping_tax_total": 0,21  "original_shipping_tax_total": 0,22  "original_shipping_subtotal": 10,23  "original_shipping_total": 10,24  "credit_line_subtotal": 0,25  "credit_line_tax_total": 0,26  "credit_line_total": 0,27  "items": [28    {29      "id": "cali_123",30      // ...31      "unit_price": 10,32      "subtotal": 10,33      "total": 0,34      "original_total": 10,35      "discount_total": 0,36      "discount_subtotal": 0,37      "discount_tax_total": 0,38      "tax_total": 0,39      "original_tax_total": 0,40    }41  ],42  "shipping_methods": [43    {44      "id": "casm_01K10AYZDKZGQXE8WXW3QP9T22",45      // ...46      "amount": 10,47      "subtotal": 10,48      "total": 10,49      "original_total": 10,50      "discount_total": 0,51      "discount_subtotal": 0,52      "discount_tax_total": 0,53      "tax_total": 0,54      "original_tax_total": 0,55    }56  ]57}

Cart Totals#

The cart will include the following total fields:

• total: The grand total of the cart, including all line items, shipping methods, taxes, and discounts.
• subtotal: The cart's total excluding taxes, including promotions.
• tax_total: The total tax amount applied to the cart.
• discount_total: The total amount of discounts applied to the cart.
• discount_subtotal: The total amount of discounts applied to the cart's subtotal.
• discount_tax_total: The total amount of discounts applied to the cart's tax.
• original_total: The cart's total including taxes, excluding promotions.
• original_tax_total: The cart items' tax total including promotions.
• item_total: The cart items' total including taxes and promotions.
• item_subtotal: The cart items' total excluding taxes, including promotions.
• item_tax_total: The cart items' tax total including promotions.
• original_item_total: The cart items' total including taxes, excluding promotions.
• original_item_subtotal: The cart items' total excluding taxes, including promotions.
• original_item_tax_total: The cart items' tax total excluding promotions.
• shipping_total: The cart's shipping total including taxes and promotions.
• shipping_subtotal: The cart's shipping total excluding taxes, including promotions.
• shipping_tax_total: The total taxes applied to the cart's shipping amount.
• original_shipping_tax_total: The total taxes applied to the cart's shipping amount, excluding promotions.
• original_shipping_subtotal: The cart's shipping total excluding taxes, including promotions.
• original_shipping_total: The cart's shipping total including taxes, excluding promotions.
• credit_line_subtotal: The subtotal of the credit line applied to the cart.
• credit_line_tax_total: The total tax amount applied to the credit line.
• credit_line_total: The total amount of the credit line applied to the cart.

Cart Line Item Totals#

The items array in the cart object contains total fields for each line item:

• unit_price: The price of a single unit of the line item. This field is not calculated and is stored in the database.
• subtotal: The total price of the line item before any discounts or taxes.
• total: The total price of the line item after applying discounts and taxes.
• original_total: The total price of the line item before any discounts.
• discount_total: The total amount of discounts applied to the line item.
• discount_subtotal: The total amount of discounts applied to the line item's subtotal.
• discount_tax_total: The total amount of discounts applied to the line item's tax.
• tax_total: The total tax amount applied to the line item.
• original_tax_total: The total tax amount applied to the line item before any discounts.

Cart Shipping Method Totals#

The shipping_methods array in the cart object contains total fields for each shipping method:

• amount: The amount charged for the shipping method. This field is not calculated and is stored in the database.
• subtotal: The total price of the shipping method before any discounts or taxes.
• total: The total price of the shipping method after applying discounts and taxes.
• original_total: The total price of the shipping method before any discounts.
• discount_total: The total amount of discounts applied to the shipping method.
• discount_subtotal: The total amount of discounts applied to the shipping method's subtotal.
• discount_tax_total: The total amount of discounts applied to the shipping method's tax.
• tax_total: The total tax amount applied to the shipping method.
• original_tax_total: The total tax amount applied to the shipping method before any discounts.

Caveats of Retrieving Cart Totals#

Using Asterisk (*) in Cart's Query#

Cart totals are calculated based on the cart's line items, shipping methods, taxes, and any discounts applied. They are not stored in the Cart data model.

For that reason, you cannot retrieve cart totals by passing * to the Query's fields. For example, the following query will not return cart totals:

This will return the cart data stored in the database, but not the calculated totals.

You also can't pass * along with total in the Query's fields option. Passing * will override the total field, and you will not retrieve cart totals. For example, the following query will not return cart totals:

Instead, when you need to retrieve cart totals, explicitly pass the total field in the Query's fields option, as shown in the previous section. You can also include other fields and relations you need, such as email and items.*.

Applying Filters on Cart Totals#

You can't apply filters directly on the cart totals, as they are not stored in the Cart data model. You can still filter the cart based on its properties, such as id, email, or currency_code, but not on the calculated totals.