--- title: Cost API description: >- The Cost API provides read-only access to the cost breakdown of an order on the Order status page. Use this API to read the subtotal, total shipping, total tax, and total amounts, each returned as a Money object with an amount and currencyCode. api_version: 2026-04 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/cost-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/cost-api.md --- # Cost API The Cost API provides read-only access to the cost breakdown of an order on the [Order status page](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status). Use this API to read the subtotal, total shipping, total tax, and total amounts, each returned as a `Money` object with an `amount` and `currencyCode`. ### Use cases * **Display an order summary**: Show a breakdown of the order cost, including the subtotal, shipping, tax, and total. * **Highlight shipping costs**: Display the shipping cost for the order, accounting for any shipping discounts that were applied. * **Show tax details**: Display the total tax amount for the order, or indicate when tax information is unavailable. ### Support Targets (10) ### Supported targets * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-item-render-after-) * [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-list-render-after-) * [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#payments-and-returns-targets) * [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#return-details-render-after-) * [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#target-apis-define-what-your-extension-does) provides the cost breakdown for the order. Access the following properties on `shopify` to read the subtotal, total shipping, total tax, and total amounts. * **cost** **CartCost** **required** A breakdown of the costs for the order, including the subtotal, shipping, tax, and total amounts. ### CartCost * subtotalAmount The sum of all line item prices at the current step of checkout, before shipping and taxes are applied. Use this value to display the base cost of the items the buyer purchased. ```ts SubscribableSignalLike ``` * totalAmount The minimum total at the current step of checkout. Costs not yet calculated, such as shipping on the information step, aren't included. Gift cards and store credits are excluded from this total. ```ts SubscribableSignalLike ``` * totalShippingAmount The total shipping cost after shipping discounts have been applied. The value is \`undefined\` if shipping hasn't been calculated yet, such as when the buyer is still on the information step. \`undefined\` until the buyer selects a shipping method (typically after the information step). ```ts SubscribableSignalLike ``` * totalTaxAmount The total tax the buyer can expect to pay, or the total tax already included in product and shipping prices (for tax-inclusive regions). The value is \`undefined\` if taxes haven't been calculated yet. \`undefined\` when taxes haven't been calculated or aren't available for the buyer's region. ```ts SubscribableSignalLike ``` ### SubscribableSignalLike Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends \`ReadonlySignalLike\` with deprecated fields that are still supported for backwards compatibility. * current The current value of the signal. Equivalent to \`.value\`, accessing this property subscribes to changes when used in a reactive context. ```ts T ``` * destroy Cleans up the subscription and releases any resources held by this signal. After calling \`destroy()\`, the signal stops receiving updates from the main thread. ```ts () => Promise ``` * subscribe Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value. ```ts (fn: (value: T) => void) => () => void ``` * value The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup. ```ts T ``` ### Money * amount The decimal amount of the price. For example, \`29.99\` represents twenty-nine dollars and ninety-nine cents. ```ts number ``` * currencyCode The three-letter currency code in \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) format. ```ts CurrencyCode ``` ### CurrencyCode ```ts 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL' ``` Examples ### Examples * #### ##### Description Show a full breakdown of the order cost, including the subtotal, shipping, tax, and total. This example reads \`shopify.cost.subtotalAmount\`, \`totalShippingAmount\`, \`totalTaxAmount\`, and \`totalAmount\` and formats each as a currency string. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const subtotal = shopify.cost.subtotalAmount.value; const shipping = shopify.cost.totalShippingAmount.value; const tax = shopify.cost.totalTaxAmount.value; const total = shopify.cost.totalAmount.value; return ( Subtotal {subtotal.amount}{' '} {subtotal.currencyCode} {shipping && ( Shipping {shipping.amount}{' '} {shipping.currencyCode} )} {tax && ( Tax {tax.amount} {tax.currencyCode} )} Total {total.amount} {total.currencyCode} ); } ``` * #### ##### Description Display the shipping cost and detect when shipping is free. This example reads \`shopify.cost.totalShippingAmount\` and conditionally renders a "Free shipping" banner when the amount is zero. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const shipping = shopify.cost.totalShippingAmount.value; if (!shipping) { return ( Shipping costs not available. ); } const isFreeShipping = shipping.amount === 0; return ( {isFreeShipping ? ( Free shipping applied! ) : ( Shipping: {shipping.amount}{' '} {shipping.currencyCode} )} ); } ``` * #### ##### Description Format order cost amounts using the buyer's currency. This example reads the currency code from \`shopify.localization\` and uses \`Intl.NumberFormat\` to display properly formatted money values. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const currency = shopify.localization.currency.value; const total = shopify.cost.totalAmount.value; const subtotal = shopify.cost.subtotalAmount.value; const formatMoney = (money) => new Intl.NumberFormat(undefined, { style: 'currency', currency: currency.isoCode, }).format(money.amount); return ( Subtotal {formatMoney(subtotal)} Total {formatMoney(total)} ); } ``` *** ## Best practices * **Format currency using the Localization API**: Use the [Order Status Localization API](https://shopify.dev/docs/api/customer-account-ui-extensions/target-apis/order-apis/order-status-localization-api) to determine the buyer's currency and format money values appropriately. * **Show a complete cost summary**: Combine the Cost API with the [Discounts API](https://shopify.dev/docs/api/customer-account-ui-extensions/target-apis/order-apis/discounts-api) and the [Gift Cards API](https://shopify.dev/docs/api/customer-account-ui-extensions/target-apis/order-apis/gift-cards-api) to display a full breakdown of the order's pricing. *** ## Limitations * The Cost API doesn't include refund amounts. If the order has been partially or fully refunded, those adjustments aren't reflected in the cost properties. ***