Retrieve Order Totals Using Query

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

You may need to retrieve order 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 using Query.

How to Retrieve Order Totals with Query#

To retrieve order totals, you mainly need to pass the total field within the fields option of the Query. This will return the order'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 an order:

The returned order object will look like this:

Code
1{2  "id": "order_01K1GEZ6Y1V9651AJNYG1WV3TC",3  "currency_code": "eur",4  "total": 20,5  "subtotal": 20,6  "tax_total": 0,7  "original_total": 20,8  "original_tax_total": 0,9  "discount_total": 0,10  "discount_tax_total": 0,11  "shipping_total": 10,12  "shipping_subtotal": 10,13  "shipping_tax_total": 0,14  "original_shipping_total": 10,15  "original_shipping_subtotal": 10,16  "original_shipping_tax_total": 0,17  "item_total": 10,18  "item_tax_total": 0,19  "item_subtotal": 10,20  "original_item_total": 10,21  "original_item_tax_total": 0,22  "original_item_subtotal": 10,23  "items": [24    {25      "subtotal": 10,26      "total": 10,27      "original_total": 10,28      "discount_total": 0,29      "discount_subtotal": 0,30      "discount_tax_total": 0,31      "tax_total": 0,32      "original_tax_total": 0,33      "refundable_total_per_unit": 10,34      "refundable_total": 10,35      "fulfilled_total": 0,36      "shipped_total": 0,37      "return_requested_total": 0,38      "return_received_total": 0,39      "return_dismissed_total": 0,40      "write_off_total": 0,41      // ...42    }43  ],44  "shipping_methods": [45    {46      "subtotal": 10,47      "total": 10,48      "original_total": 10,49      "discount_total": 0,50      "discount_subtotal": 0,51      "discount_tax_total": 0,52      "tax_total": 0,53      "original_tax_total": 0,54      // ...55    }56  ],57  "summary": {58    "paid_total": 0,59    "refunded_total": 0,60    "accounting_total": 20,61    "credit_line_total": 0,62    "transaction_total": 0,63    "pending_difference": 20,64    "current_order_total": 20,65    "original_order_total": 2066  }67}

Order Totals#

The order will include the following total fields:

• total: The order's final total after discounts and credit lines, including taxes.
• subtotal: The order's subtotal before discounts, excluding taxes. Calculated as the sum of item_subtotal and shipping_subtotal.
• tax_total: The order's tax total after discounts. Calculated as the sum of item_tax_total and shipping_tax_total.
• original_total: The order's total before discounts, including taxes. Calculated as the sum of original_item_total and original_shipping_total.
• original_subtotal: The order's subtotal before discounts, excluding taxes. Calculated as the sum of original_item_subtotal and original_shipping_subtotal.
• original_tax_total: The order's tax total before discounts. Calculated as the sum of original_item_tax_total and original_shipping_tax_total.
• discount_total: The total amount of discounts applied to the order, including the tax portion of discounts.
• discount_tax_total: The total amount of discounts applied to the order's tax. Represents the tax portion of discounts.
• shipping_total: The sum of all shipping methods' totals after discounts, including taxes.
• shipping_subtotal: The sum of all shipping methods' subtotals before discounts, excluding taxes.
• shipping_tax_total: The sum of all shipping methods' tax totals after discounts.
• original_shipping_total: The sum of all shipping methods' original totals before discounts, including taxes.
• original_shipping_subtotal: The sum of all shipping methods' original subtotals before discounts, excluding taxes.
• original_shipping_tax_total: The sum of all shipping methods' original tax totals before discounts.
• item_total: The sum of all line items' totals after discounts, including taxes.
• item_tax_total: The sum of all line items' tax totals after discounts.
• item_subtotal: The sum of all line items' subtotals before discounts, excluding taxes.
• original_item_total: The sum of all line items' original totals before discounts, including taxes.
• original_item_tax_total: The sum of all line items' original tax totals before discounts.
• original_item_subtotal: The sum of all line items' original subtotals before discounts, excluding taxes.
• gift_card_total: The total amount of gift cards applied to the order.
• gift_card_tax_total: The tax total of the gift cards applied to the order.

Order Line Item Totals#

The items array in the order 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 line item's subtotal before discounts, excluding taxes.
• total: The line item's total after discounts, including taxes.
• original_total: The line item's original total before discounts, including taxes.
• discount_total: The total amount of discounts applied to the line item, including the tax portion of discounts.
• discount_subtotal: The total amount of discounts applied to the line item's subtotal (excluding tax portion).
• discount_tax_total: The total amount of discounts applied to the line item's tax. Represents the tax portion of discounts.
• tax_total: The line item's tax total after discounts.
• original_tax_total: The line item's original tax total before discounts.
• refundable_total_per_unit: The total amount that can be refunded per unit of the line item.
• refundable_total: The total amount that can be refunded for the line item.
• fulfilled_total: The total amount of the line item that has been fulfilled.
• shipped_total: The total amount of the line item that has been shipped.
• return_requested_total: The total amount of the line item that has been requested for return.
• return_received_total: The total amount of the line item that has been received from a return.
• return_dismissed_total: The total amount of the line item that has been dismissed by a return.
  • These items are considered damaged and are not returned to the inventory.
• write_off_total: The total amount of the line item that has been written off.
  • For example, if the order is edited and the line item is removed or its quantity has changed.

Order Shipping Method Totals#

The shipping_methods array in the order 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 shipping method's subtotal before discounts, excluding taxes.
• total: The shipping method's total after discounts, including taxes.
• original_total: The shipping method's original total before discounts, including taxes.
• discount_total: The total amount of discounts applied to the shipping method, including the tax portion of discounts.
• discount_subtotal: The total amount of discounts applied to the shipping method's subtotal (excluding tax portion).
• discount_tax_total: The total amount of discounts applied to the shipping method's tax. Represents the tax portion of discounts.
• tax_total: The shipping method's tax total after discounts.
• original_tax_total: The shipping method's original tax total before discounts.

Order Summary Totals#

The summary object in the order object provides an overview of the order's transactions. It includes the following fields:

• paid_total: The total amount that has been paid for the order.
• refunded_total: The total amount that has been refunded for the order.
• accounting_total: The order's total without the credit-line total.
• credit_line_total: The total amount of credit lines applied to the order.
• transaction_total: The total amount of transactions associated with the order.
• pending_difference: The difference between the order's total and the paid total.
• current_order_total: The current total of the order. It's useful if the order has been edited or modified.
• original_order_total: The original total of the order before any modifications.

Caveats of Retrieving Order Totals#

Using Asterisk (*) in Order Query#

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

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

This will return the order 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 order totals. For example, the following query will not return order totals:

Instead, when you need to retrieve order 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 Order Totals#

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