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:

Cart Lines API

The Cart Lines API provides the line items in the order, including product details, quantities, costs, and discounts. Use it to display order contents or calculate item totals on the Order status page.

Anchor to Use casesUse cases

Display order items: Show the list of products purchased, including titles, images, selected options, and quantities.
Show line-level pricing: Display the cost breakdown for individual line items, including any discounts applied to specific lines.
Handle bundles: Detect and display bundle products by checking each cart line for bundled sub-items.

Support

Targets (10)

Supported targets

Anchor to PropertiesProperties

The Cart Lines API object provides the line items from the order. Access the following properties on the API object to read line item data.

Anchor to lines lines StatefulRemoteSubscribable<[]> required: The line items in the order, including product details, quantities, costs, and any applied discounts.

CartLine

attributes
Custom key-value pairs attached to this line item, such as engraving text or gift messages.
```
Attribute[]
```
cost
The cost breakdown for this line item, including the total amount after discounts.
```
CartLineCost
```
discountAllocations
The discounts allocated to this line item, including code-based, automatic, and custom discounts.
```
CartDiscountAllocation[]
```
id
A unique identifier for the cart line. This ID isn't guaranteed to be stable across operations.
```
string
```
lineComponents
The individual components of a [bundle](/docs/apps/build/product-merchandising/bundles) line item. Returns an empty array if the line item isn't a bundle.
```
CartBundleLineComponent[]
```
merchandise
The product variant being purchased in this line item.
```
Merchandise
```
quantity
The quantity of the merchandise being purchased.
```
number
```

Attribute

key
The attribute name. Keys are unique within the attribute list.
```
string
```
value
The attribute value as a string.
```
string
```

CartLineCost

totalAmount
The total amount for the line item after all discounts have been applied.
```
Money
```

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'

CartDiscountAllocation

A discount allocation applied to the order or a line item. There are three types: - `CartCodeDiscountAllocation`: A discount applied via a code entered by the buyer. - `CartAutomaticDiscountAllocation`: An automatic discount applied by Shopify based on merchant-configured rules. - `CartCustomDiscountAllocation`: A custom discount applied by a Shopify Script or discount function.

CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation

CartCodeDiscountAllocation

code
The discount code that the buyer entered at checkout.
```
string
```
discountedAmount
The monetary amount deducted from the order by this discount allocation.
```
Money
```
type
The type of discount allocation. Always `'code'` for code-based discounts.
```
'code'
```

CartAutomaticDiscountAllocation

discountedAmount
The monetary amount deducted from the order by this discount allocation.
```
Money
```
title
The merchant-defined title of the automatic discount, such as "Buy 2 Get 1 Free".
```
string
```
type
The type of discount allocation. Always `'automatic'` for automatic discounts.
```
'automatic'
```

CartCustomDiscountAllocation

discountedAmount
The monetary amount deducted from the order by this discount allocation.
```
Money
```
title
The title of the custom discount applied by a Shopify Script or discount function.
```
string
```
type
The type of discount allocation. Always `'custom'` for custom discounts.
```
'custom'
```

CartBundleLineComponent

attributes
Custom key-value pairs attached to this bundle component.
```
Attribute[]
```
cost
The cost breakdown for this bundle component.
```
CartLineCost
```
id
A unique identifier for the bundle line component. This ID isn't stable and may change if line items are modified.
```
string
```
merchandise
The product variant included in this bundle component.
```
Merchandise
```
quantity
The quantity of this product variant within the bundle.
```
number
```
type
Always `'bundle'` for bundle line components.
```
'bundle'
```

Merchandise

id
A globally-unique identifier for the product variant.
```
string
```
image
The image associated with this product variant. Falls back to the product's featured image if no variant-specific image is available.
```
ImageDetails
```
product
The parent product that this variant belongs to.
```
Product
```
requiresShipping
Whether this product variant requires physical shipping.
```
boolean
```
selectedOptions
The product options selected for this variant, such as size and color.
```
SelectedOption[]
```
sellingPlan
The selling plan associated with this line item, such as a subscription or pre-order plan.
```
SellingPlan
```
sku
The product variant's stock keeping unit (SKU), used for inventory tracking.
```
string
```
subtitle
A secondary title for the product variant, typically showing selected option values.
```
string
```
title
The product variant’s title.
```
string
```
type
Always `'variant'` for product variant merchandise.
```
'variant'
```

ImageDetails

altText
The alternative text for the image, used for accessibility and displayed when the image can't be loaded.
```
string
```
url
The fully-qualified URL of the image.
```
string
```

Product

id
A globally-unique identifier for the product.
```
string
```
productType
A product classification used for filtering and organization, set by the merchant in the Shopify admin.
```
string
```
vendor
The product’s vendor name.
```
string
```

SelectedOption

name
The name of the product option, such as "Size" or "Color".
```
string
```
value
The selected value for the option, such as "Large" or "Blue".
```
string
```

SellingPlan

id
A globally-unique identifier for the selling plan.
```
string
```
recurringDeliveries
Whether purchasing the selling plan will result in multiple deliveries.
```
boolean
```

Anchor to Cart line item propertiesCart line item properties

The shopify global object provides the following additional properties on shopify for extensions registered for the cart-line-item extension targets.

Anchor to target target StatefulRemoteSubscribable<> required: The cart line that this extension is attached to. Use this to read the line item's merchandise, quantity, cost, and attributes.

Examples

import {

reactExtension,

useCartLines,

} 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 lines = useCartLines();

return (

<Text emphasis="bold">Order items ({lines.length})</Text>

{lines.map((line) => (

{line.merchandise.title} × {line.quantity} —{' '}

{line.cost.totalAmount.amount}{' '}

{line.cost.totalAmount.currencyCode}

</Text>

))}

</BlockStack>

);

}

Examples

Description

Read all line items from the order and display each product with its quantity and price. This example uses the `useCartLines` hook and formats each line with the product title and cost.

React

import {
  reactExtension,
  useCartLines,
} 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 lines = useCartLines();

  return (
    <BlockStack>
      <Text emphasis="bold">Order items ({lines.length})</Text>
      {lines.map((line) => (
        <Text key={line.id}>
          {line.merchandise.title} × {line.quantity} —{' '}
          {line.cost.totalAmount.amount}{' '}
          {line.cost.totalAmount.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 lines = api.lines.current;

    const stack = root.createComponent(BlockStack, {});
    stack.appendChild(
      root.createComponent(
        Text,
        {emphasis: 'bold'},
        `Order items (${lines.length})`,
      ),
    );

    for (const line of lines) {
      stack.appendChild(
        root.createComponent(
          Text,
          {},
          `${line.merchandise.title} × ${line.quantity} — ${line.cost.totalAmount.amount} ${line.cost.totalAmount.currencyCode}`,
        ),
      );
    }
    root.appendChild(stack);
  },
);

Description

Calculate the total number of items across all line items in the order. This example uses `useCartLines` to sum the `quantity` property across all lines.

React

import {
  reactExtension,
  useCartLines,
} from '@shopify/ui-extensions-react/customer-account';
import {
  Banner,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const lines = useCartLines();

  const totalItems = lines.reduce(
    (sum, line) => sum + line.quantity,
    0,
  );

  return (
    <Banner status="info">
      <Text>
        This order contains {totalItems} item
        {totalItems !== 1 ? 's' : ''} across{' '}
        {lines.length} line item
        {lines.length !== 1 ? 's' : ''}.
      </Text>
    </Banner>
  );
}

TS

import {
  extension,
  Banner,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const lines = api.lines.current;

    const totalItems = lines.reduce(
      (sum, line) => sum + line.quantity,
      0,
    );

    const banner = root.createComponent(Banner, {status: 'info'});
    banner.appendChild(
      root.createComponent(
        Text,
        {},
        `This order contains ${totalItems} item${totalItems !== 1 ? 's' : ''} across ${lines.length} line item${lines.length !== 1 ? 's' : ''}.`,
      ),
    );
    root.appendChild(banner);
  },
);

Description

Identify bundle line items and display their individual components. This example checks the `lineComponents` array on each cart line to detect and render bundle contents.

React

import {
  reactExtension,
  useCartLines,
} 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 lines = useCartLines();
  const bundleLines = lines.filter(
    (line) => line.lineComponents.length > 0,
  );

  if (bundleLines.length === 0) {
    return null;
  }

  return (
    <BlockStack>
      <Text emphasis="bold">Bundle details</Text>
      {bundleLines.map((line) => (
        <BlockStack key={line.id}>
          <Text>{line.merchandise.title}</Text>
          {line.lineComponents.map((component) => (
            <Text key={component.id} appearance="subdued">
              ↳ {component.merchandise.title} ×{' '}
              {component.quantity}
            </Text>
          ))}
        </BlockStack>
      ))}
    </BlockStack>
  );
}

TS

import {
  extension,
  BlockStack,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const lines = api.lines.current;
    const bundleLines = lines.filter(
      (line) => line.lineComponents.length > 0,
    );

    if (bundleLines.length === 0) return;

    const stack = root.createComponent(BlockStack, {});
    stack.appendChild(
      root.createComponent(Text, {emphasis: 'bold'}, 'Bundle details'),
    );

    for (const line of bundleLines) {
      const lineStack = root.createComponent(BlockStack, {});
      lineStack.appendChild(
        root.createComponent(Text, {}, line.merchandise.title),
      );
      for (const component of line.lineComponents) {
        lineStack.appendChild(
          root.createComponent(
            Text,
            {appearance: 'subdued'},
            `↳ ${component.merchandise.title} × ${component.quantity}`,
          ),
        );
      }
      stack.appendChild(lineStack);
    }
    root.appendChild(stack);
  },
);

Anchor to Best practicesBest practices

Check for bundle components: Use lineComponents to detect and display bundle contents. The array is empty for non-bundle items.
Use line item costs for accurate totals: The cost.totalAmount on each line item already includes line-level discounts.

Anchor to LimitationsLimitations

Cart lines don't include fulfillment or shipping status. To determine whether items have been shipped, use the GraphQL Admin API through a backend service.

Was this page helpful?