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:
useQueryGraphStep in workflows, and query.graph in custom API routes, scheduled jobs, and subscribers.The returned order object will look like this:
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 grand total of the order, including all line items, shipping methods, taxes, and discounts.subtotal: The order's total excluding taxes, including promotions.tax_total: The order's tax total including promotions.original_total: The order's total including taxes, excluding promotions.original_subtotal: The order's total excluding taxes, including promotions.original_tax_total: The order's tax total excluding promotions.discount_total: The order's discount or promotions total.discount_tax_total: The tax total of the order's discount or promotion.shipping_total: The order's shipping total including taxes and promotions.shipping_subtotal: The order's shipping total excluding taxes, including promotions.shipping_tax_total: The tax total of the order's shipping.original_shipping_total: The order's shipping total including taxes, excluding promotions.original_shipping_subtotal: The order's shipping total excluding taxes, including promotions.original_shipping_tax_total: The tax total of the order's shipping excluding promotions.item_total: The total of all line items in the order, including taxes and promotions.item_tax_total: The tax total of all line items in the order, including promotions.item_subtotal: The subtotal of all line items in the order, excluding taxes, including promotions.original_item_total: The total of all line items in the order, including taxes, excluding promotions.original_item_tax_total: The tax total of all line items in the order, excluding promotions.original_item_subtotal: The subtotal of all line items in the order, excluding taxes, including promotions.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 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.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 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.
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.
