---
title: Cart Lines API
description: >-
  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.
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/cart-lines-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/cart-lines-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.

# 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.

### Use 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

* [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 Cart Lines API object provides the line items from the order. Access the following properties on the API object to read line item data.

* **lines**

  **StatefulRemoteSubscribable\<CartLine\[]>**

  **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.

  ```ts
  Attribute[]
  ```

* cost

  The cost breakdown for this line item, including the total amount after discounts.

  ```ts
  CartLineCost
  ```

* discountAllocations

  The discounts allocated to this line item, including code-based, automatic, and custom discounts.

  ```ts
  CartDiscountAllocation[]
  ```

* id

  A unique identifier for the cart line. This ID isn't guaranteed to be stable across operations.

  ```ts
  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.

  ```ts
  CartBundleLineComponent[]
  ```

* merchandise

  The product variant being purchased in this line item.

  ```ts
  Merchandise
  ```

* quantity

  The quantity of the merchandise being purchased.

  ```ts
  number
  ```

### Attribute

* key

  The attribute name. Keys are unique within the attribute list.

  ```ts
  string
  ```

* value

  The attribute value as a string.

  ```ts
  string
  ```

### CartLineCost

* totalAmount

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

  ```ts
  Money
  ```

### 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'
```

### 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.

```ts
CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation
```

### CartCodeDiscountAllocation

* code

  The discount code that the buyer entered at checkout.

  ```ts
  string
  ```

* discountedAmount

  The monetary amount deducted from the order by this discount allocation.

  ```ts
  Money
  ```

* type

  The type of discount allocation. Always \`'code'\` for code-based discounts.

  ```ts
  'code'
  ```

### CartAutomaticDiscountAllocation

* discountedAmount

  The monetary amount deducted from the order by this discount allocation.

  ```ts
  Money
  ```

* title

  The merchant-defined title of the automatic discount, such as "Buy 2 Get 1 Free".

  ```ts
  string
  ```

* type

  The type of discount allocation. Always \`'automatic'\` for automatic discounts.

  ```ts
  'automatic'
  ```

### CartCustomDiscountAllocation

* discountedAmount

  The monetary amount deducted from the order by this discount allocation.

  ```ts
  Money
  ```

* title

  The title of the custom discount applied by a Shopify Script or discount function.

  ```ts
  string
  ```

* type

  The type of discount allocation. Always \`'custom'\` for custom discounts.

  ```ts
  'custom'
  ```

### CartBundleLineComponent

* attributes

  Custom key-value pairs attached to this bundle component.

  ```ts
  Attribute[]
  ```

* cost

  The cost breakdown for this bundle component.

  ```ts
  CartLineCost
  ```

* id

  A unique identifier for the bundle line component. This ID isn't stable and may change if line items are modified.

  ```ts
  string
  ```

* merchandise

  The product variant included in this bundle component.

  ```ts
  Merchandise
  ```

* quantity

  The quantity of this product variant within the bundle.

  ```ts
  number
  ```

* type

  Always \`'bundle'\` for bundle line components.

  ```ts
  'bundle'
  ```

### Merchandise

* id

  A globally-unique identifier for the product variant.

  ```ts
  string
  ```

* image

  The image associated with this product variant. Falls back to the product's featured image if no variant-specific image is available.

  ```ts
  ImageDetails
  ```

* product

  The parent product that this variant belongs to.

  ```ts
  Product
  ```

* requiresShipping

  Whether this product variant requires physical shipping.

  ```ts
  boolean
  ```

* selectedOptions

  The product options selected for this variant, such as size and color.

  ```ts
  SelectedOption[]
  ```

* sellingPlan

  The selling plan associated with this line item, such as a subscription or pre-order plan.

  ```ts
  SellingPlan
  ```

* sku

  The product variant's stock keeping unit (SKU), used for inventory tracking.

  ```ts
  string
  ```

* subtitle

  A secondary title for the product variant, typically showing selected option values.

  ```ts
  string
  ```

* title

  The product variant’s title.

  ```ts
  string
  ```

* type

  Always \`'variant'\` for product variant merchandise.

  ```ts
  'variant'
  ```

### ImageDetails

* altText

  The alternative text for the image, used for accessibility and displayed when the image can't be loaded.

  ```ts
  string
  ```

* url

  The fully-qualified URL of the image.

  ```ts
  string
  ```

### Product

* id

  A globally-unique identifier for the product.

  ```ts
  string
  ```

* productType

  A product classification used for filtering and organization, set by the merchant in the Shopify admin.

  ```ts
  string
  ```

* vendor

  The product’s vendor name.

  ```ts
  string
  ```

### SelectedOption

* name

  The name of the product option, such as "Size" or "Color".

  ```ts
  string
  ```

* value

  The selected value for the option, such as "Large" or "Blue".

  ```ts
  string
  ```

### SellingPlan

* id

  A globally-unique identifier for the selling plan.

  ```ts
  string
  ```

* recurringDeliveries

  Whether purchasing the selling plan will result in multiple deliveries.

  ```ts
  boolean
  ```

### Cart line item properties

The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07#target-apis-define-what-your-extension-does) provides the following additional properties on `shopify` for extensions registered for the `cart-line-item` extension targets.

* **target**

  **StatefulRemoteSubscribable\<CartLine>**

  **required**

  The cart line that this extension is attached to. Use this to read the line item's merchandise, quantity, cost, and attributes.

Examples

### 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

  ```tsx
  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

  ```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

  ```tsx
  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

  ```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

  ```tsx
  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

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

***

## Best practices

* **Check for bundle components**: Use `lineComponents` to detect and display [bundle](https://shopify.dev/docs/apps/build/product-merchandising/bundles) 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.

***

## Limitations

* Cart lines don't include fulfillment or shipping status. To determine whether items have been shipped, use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql) through a backend service.

***