Choose a version:

Cost API

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.

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 shopify global object provides the cost breakdown for the order. Access the following properties on shopify to read the subtotal, total shipping, total tax, and total amounts.

Anchor to cost cost 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.
```
SubscribableSignalLike<Money>
```
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.
```
SubscribableSignalLike<Money>
```
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).
```
SubscribableSignalLike<Money | undefined>
```
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.
```
SubscribableSignalLike<Money | undefined>
```

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.
```
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.
```
() => Promise<void>
```
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.
```
(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.
```
T
```

Money

amount
The decimal amount of the price. For example, `29.99` represents twenty-nine dollars and ninety-nine cents.
```
number
```
currencyCode
The three-letter currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
```
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

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, 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 (

<s-box>

<s-stack>

<s-stack direction="inline">

<s-text>Subtotal</s-text>

<s-text>

{subtotal.amount}{' '}

{subtotal.currencyCode}

</s-text>

</s-stack>

{shipping && (

<s-stack direction="inline">

<s-text>Shipping</s-text>

<s-text>

{shipping.amount}{' '}

{shipping.currencyCode}

</s-text>

</s-stack>

)}

{tax && (

<s-stack direction="inline">

<s-text>Tax</s-text>

<s-text>

{tax.amount} {tax.currencyCode}

</s-text>

</s-stack>

)}

<s-divider />

<s-stack direction="inline">

<s-text type="strong">Total</s-text>

<s-text type="strong">

{total.amount} {total.currencyCode}

</s-text>

</s-stack>

</s-box>

);

}

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

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, 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 (
    <s-box>
      <s-stack>
        <s-stack direction="inline">
          <s-text>Subtotal</s-text>
          <s-text>
            {subtotal.amount}{' '}
            {subtotal.currencyCode}
          </s-text>
        </s-stack>
        {shipping && (
          <s-stack direction="inline">
            <s-text>Shipping</s-text>
            <s-text>
              {shipping.amount}{' '}
              {shipping.currencyCode}
            </s-text>
          </s-stack>
        )}
        {tax && (
          <s-stack direction="inline">
            <s-text>Tax</s-text>
            <s-text>
              {tax.amount} {tax.currencyCode}
            </s-text>
          </s-stack>
        )}
        <s-divider />
        <s-stack direction="inline">
          <s-text type="strong">Total</s-text>
          <s-text type="strong">
            {total.amount} {total.currencyCode}
          </s-text>
        </s-stack>
      </s-stack>
    </s-box>
  );
}

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

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const shipping =
    shopify.cost.totalShippingAmount.value;

  if (!shipping) {
    return (
      <s-text color="subdued">
        Shipping costs not available.
      </s-text>
    );
  }

  const isFreeShipping = shipping.amount === 0;

  return (
    <s-banner
      tone={isFreeShipping ? 'success' : 'info'}
    >
      {isFreeShipping ? (
        <s-text type="strong">
          Free shipping applied!
        </s-text>
      ) : (
        <s-text>
          Shipping: {shipping.amount}{' '}
          {shipping.currencyCode}
        </s-text>
      )}
    </s-banner>
  );
}

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

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, 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 (
    <s-box>
      <s-stack>
        <s-stack direction="inline">
          <s-text>Subtotal</s-text>
          <s-text>{formatMoney(subtotal)}</s-text>
        </s-stack>
        <s-divider />
        <s-stack direction="inline">
          <s-text type="strong">Total</s-text>
          <s-text type="strong">
            {formatMoney(total)}
          </s-text>
        </s-stack>
      </s-stack>
    </s-box>
  );
}

Anchor to Best practicesBest practices

Format currency using the Localization API: Use the 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 and the Gift Cards API to display a full breakdown of the order's pricing.

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?