--- title: Cost API description: >- The Cost API provides the order's cost breakdown, including subtotal, shipping, tax, and total amounts. Use it to display order totals or format cost data for the buyer on the Order status page. api_version: 2025-07 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/cost-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/cost-api.md --- Migrate to Polaris Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension. # Cost API The Cost API provides the order's cost breakdown, including subtotal, shipping, tax, and total amounts. Use it to display order totals or format cost data for the buyer on the Order status page. ### 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/2025-07/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-) ### Properties The Cost API object provides the order's cost breakdown. Access the following properties on the API object to read cost data. * **cost** **CartCost** **required** The cost breakdown for the order, including subtotal, shipping, tax, and total amounts. ### CartCost * subtotalAmount The subtotal cost of all line items in the order before shipping, taxes, and discounts. ```ts StatefulRemoteSubscribable ``` * totalAmount The total amount the buyer paid for the order, including all line items, shipping, taxes, and discounts. ```ts StatefulRemoteSubscribable ``` * totalShippingAmount The total shipping cost for the order, including any shipping discounts. Returns \`undefined\` if shipping hasn't been calculated. ```ts StatefulRemoteSubscribable ``` * totalTaxAmount The total tax amount for the order, including taxes on products and shipping. Returns \`undefined\` if taxes haven't been calculated. ```ts StatefulRemoteSubscribable ``` ### Money * amount The decimal money amount, such as \`29.99\`. ```ts number ``` * currencyCode The \[ISO 4217]\(https://www\.iso.org/iso-4217-currency-codes.html) currency code. ```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 Read the cost breakdown from the order and display the subtotal, shipping, tax, and total amounts. This example subscribes to the \`cost\` properties and format each value with the currency code. ##### React ```tsx import { reactExtension, useApi, } from '@shopify/ui-extensions-react/customer-account'; import { BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const {cost} = useApi<'customer-account.order-status.block.render'>(); const subtotal = cost.subtotalAmount.current; const total = cost.totalAmount.current; return ( Subtotal: {subtotal.amount} {subtotal.currencyCode} Total: {total.amount} {total.currencyCode} ); } ``` ##### TS ```ts import { extension, BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, api) => { const subtotal = api.cost.subtotalAmount.current; const total = api.cost.totalAmount.current; const stack = root.createComponent(BlockStack, {}); stack.appendChild( root.createComponent( Text, {}, `Subtotal: ${subtotal.amount} ${subtotal.currencyCode}`, ), ); stack.appendChild( root.createComponent( Text, {emphasis: 'bold'}, `Total: ${total.amount} ${total.currencyCode}`, ), ); root.appendChild(stack); }, ); ``` * #### ##### Description Read the shipping and tax amounts from the order cost and display them separately. This example checks for \`undefined\` values since shipping and tax may not be calculated yet. ##### React ```tsx import { reactExtension, useApi, } from '@shopify/ui-extensions-react/customer-account'; import { BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const {cost} = useApi<'customer-account.order-status.block.render'>(); const shipping = cost.totalShippingAmount.current; const tax = cost.totalTaxAmount.current; return ( Shipping:{' '} {shipping ? `${shipping.amount} ${shipping.currencyCode}` : 'Not calculated'} Tax:{' '} {tax ? `${tax.amount} ${tax.currencyCode}` : 'Not calculated'} ); } ``` ##### TS ```ts import { extension, BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, api) => { const shipping = api.cost.totalShippingAmount.current; const tax = api.cost.totalTaxAmount.current; const stack = root.createComponent(BlockStack, {}); stack.appendChild( root.createComponent( Text, {}, `Shipping: ${shipping ? `${shipping.amount} ${shipping.currencyCode}` : 'Not calculated'}`, ), ); stack.appendChild( root.createComponent( Text, {}, `Tax: ${tax ? `${tax.amount} ${tax.currencyCode}` : 'Not calculated'}`, ), ); root.appendChild(stack); }, ); ``` * #### ##### Description Format the cost amounts using the buyer's locale and currency settings. This example combines the Cost API with \`Intl.NumberFormat\` for locale-aware money formatting. ##### React ```tsx import { reactExtension, useApi, useI18n, } from '@shopify/ui-extensions-react/customer-account'; import { BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const {cost} = useApi<'customer-account.order-status.block.render'>(); const i18n = useI18n(); const total = cost.totalAmount.current; const subtotal = cost.subtotalAmount.current; const formattedTotal = i18n.formatCurrency(total.amount, { currency: total.currencyCode, }); const formattedSubtotal = i18n.formatCurrency( subtotal.amount, {currency: subtotal.currencyCode}, ); return ( Subtotal: {formattedSubtotal} Total: {formattedTotal} ); } ``` ##### TS ```ts import { extension, BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, api) => { const total = api.cost.totalAmount.current; const subtotal = api.cost.subtotalAmount.current; const formattedTotal = api.i18n.formatCurrency(total.amount, { currency: total.currencyCode, }); const formattedSubtotal = api.i18n.formatCurrency( subtotal.amount, {currency: subtotal.currencyCode}, ); const stack = root.createComponent(BlockStack, {}); stack.appendChild( root.createComponent(Text, {}, `Subtotal: ${formattedSubtotal}`), ); stack.appendChild( root.createComponent( Text, {emphasis: 'bold'}, `Total: ${formattedTotal}`, ), ); root.appendChild(stack); }, ); ``` *** ## Best practices * **Handle undefined shipping and tax amounts**: The `totalShippingAmount` and `totalTaxAmount` properties may be `undefined` if they haven't been calculated yet. Always check for `undefined` before rendering. * **Use `totalAmount` for the final price**: The `totalAmount` already accounts for all discounts, taxes, and shipping charges. *** ## 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. ***