Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

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.

Anchor to Use casesUse 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

Anchor to PropertiesProperties

The Cost API object provides the order's cost breakdown. Access the following properties on the API object to read cost data.

Anchor to cost cost 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.
```
StatefulRemoteSubscribable<Money>
```
totalAmount
The total amount the buyer paid for the order, including all line items, shipping, taxes, and discounts.
```
StatefulRemoteSubscribable<Money>
```
totalShippingAmount
The total shipping cost for the order, including any shipping discounts. Returns `undefined` if shipping hasn't been calculated.
```
StatefulRemoteSubscribable<Money | undefined>
```
totalTaxAmount
The total tax amount for the order, including taxes on products and shipping. Returns `undefined` if taxes haven't been calculated.
```
StatefulRemoteSubscribable<Money | undefined>
```

Money

amount
The decimal money amount, such as `29.99`.
```
number
```
currencyCode
The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
```
CurrencyCode
```

CurrencyCode

'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

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',

() => <Extension />,

);

function Extension() {

const {cost} =

useApi<'customer-account.order-status.block.render'>();

const subtotal = cost.subtotalAmount.current;

const total = cost.totalAmount.current;

return (

<Text>

Subtotal: {subtotal.amount} {subtotal.currencyCode}

</Text>

Total: {total.amount} {total.currencyCode}

</Text>

</BlockStack>

);

}

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

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',
  () => <Extension />,
);

function Extension() {
  const {cost} =
    useApi<'customer-account.order-status.block.render'>();

  const subtotal = cost.subtotalAmount.current;
  const total = cost.totalAmount.current;

  return (
    <BlockStack>
      <Text>
        Subtotal: {subtotal.amount} {subtotal.currencyCode}
      </Text>
      <Text emphasis="bold">
        Total: {total.amount} {total.currencyCode}
      </Text>
    </BlockStack>
  );
}

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

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',
  () => <Extension />,
);

function Extension() {
  const {cost} =
    useApi<'customer-account.order-status.block.render'>();

  const shipping = cost.totalShippingAmount.current;
  const tax = cost.totalTaxAmount.current;

  return (
    <BlockStack>
      <Text>
        Shipping:{' '}
        {shipping
          ? `${shipping.amount} ${shipping.currencyCode}`
          : 'Not calculated'}
      </Text>
      <Text>
        Tax:{' '}
        {tax
          ? `${tax.amount} ${tax.currencyCode}`
          : 'Not calculated'}
      </Text>
    </BlockStack>
  );
}

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

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',
  () => <Extension />,
);

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 (
    <BlockStack>
      <Text>Subtotal: {formattedSubtotal}</Text>
      <Text emphasis="bold">Total: {formattedTotal}</Text>
    </BlockStack>
  );
}

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);
  },
);

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

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.

Was this page helpful?