Choose a version:

Cost API

The Cost API provides access to the cost breakdown of the current checkout, including subtotal, shipping, tax, and total amounts. Use this API to display order summaries, track spending thresholds, and show cost-related information to the buyer.

All cost values are read-only. There are no methods to modify pricing from a checkout extension.

Some values are conditionally available. totalShippingAmount is undefined until the buyer selects a shipping method, and totalTaxAmount is undefined when taxes haven't been calculated or aren't available for the buyer's region.

Anchor to Use casesUse cases

Display an order cost summary: Show the buyer a breakdown of subtotal, shipping, tax, and total amounts.
Show progress toward free shipping: Compare the cart subtotal against a threshold and display how much more the buyer needs to spend.
Track spending thresholds: Use the subtotal or total amount to trigger conditional UI based on cart value.

Support

Targets (31)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides cost data for the current checkout. Access the following properties on shopify to read the cost breakdown. Available to purchase extension targets.

Anchor to cost cost required: The cost breakdown for the current checkout, including subtotal, shipping, tax, and total amounts. These values update as the buyer progresses through checkout and costs like shipping and tax are calculated.

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 function extension() {

render(<Extension />, document.body);

}

function Extension() {

const subtotal = shopify.cost.subtotalAmount.value;

const totalShipping = shopify.cost.totalShippingAmount.value;

const totalTax = shopify.cost.totalTaxAmount.value;

const total = shopify.cost.totalAmount.value;

return (

<s-stack>

<s-text>

Subtotal: {subtotal.amount}{' '}

{subtotal.currencyCode}

</s-text>

{totalShipping && (

<s-text>

Shipping: {totalShipping.amount}{' '}

{totalShipping.currencyCode}

</s-text>

)}

{totalTax && (

<s-text>

Tax: {totalTax.amount}{' '}

{totalTax.currencyCode}

</s-text>

)}

<s-text type="strong">

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

</s-text>

</s-stack>

);

}

Examples

Description

Render a full cost breakdown with subtotal, shipping, tax, and total. This example reads the cost properties from `shopify.cost` and conditionally renders shipping and tax, which might be unavailable on earlier checkout steps.

jsx

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

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

function Extension() {
  const subtotal = shopify.cost.subtotalAmount.value;
  const totalShipping = shopify.cost.totalShippingAmount.value;
  const totalTax = shopify.cost.totalTaxAmount.value;
  const total = shopify.cost.totalAmount.value;

  return (
    <s-stack>
      <s-text>
        Subtotal: {subtotal.amount}{' '}
        {subtotal.currencyCode}
      </s-text>
      {totalShipping && (
        <s-text>
          Shipping: {totalShipping.amount}{' '}
          {totalShipping.currencyCode}
        </s-text>
      )}
      {totalTax && (
        <s-text>
          Tax: {totalTax.amount}{' '}
          {totalTax.currencyCode}
        </s-text>
      )}
      <s-text type="strong">
        Total: {total.amount} {total.currencyCode}
      </s-text>
    </s-stack>
  );
}

Description

Track the buyer's progress toward a free shipping threshold. This example compares `shopify.cost.subtotalAmount` against a target value and switches to a success banner once the buyer qualifies.

jsx

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

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

const FREE_SHIPPING_THRESHOLD = 100;

function Extension() {
  const subtotal = shopify.cost.subtotalAmount.value;
  const remaining =
    FREE_SHIPPING_THRESHOLD - subtotal.amount;

  if (remaining <= 0) {
    return (
      <s-banner tone="success">
        You qualify for free shipping!
      </s-banner>
    );
  }

  return (
    <s-banner>
      Add {remaining.toFixed(2)}{' '}
      {subtotal.currencyCode} more to get free
      shipping
    </s-banner>
  );
}

Anchor to Best practicesBest practices

Label totalAmount as an estimate on early steps: The totalAmount excludes costs not yet negotiated, such as delivery fees before a shipping method is selected. On steps where costs are incomplete, label the value accordingly (for example, "Estimated total") so the buyer understands the final amount might change.
Use subtotalAmount for threshold calculations: The subtotal is always available and reflects the value of items in the cart, making it a reliable basis for free shipping thresholds or minimum order checks.

Was this page helpful?