Choose a version:

Cart Lines API

The Cart Lines API provides read-only access to the line items in an order on the Order status page. Use this API to read merchandise details, quantities, per-line costs, discount allocations, and bundle components for each item the customer purchased.

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 shopify global object provides the line items in the order. Access the following properties on shopify to read merchandise details, quantities, per-line costs, discount allocations, and bundle line components.

Anchor to lines lines <[]> required: A list of line items in the order. Each line includes the merchandise, quantity, cost, custom attributes, and discount allocations.

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

CartLine

attributes
Custom key-value attributes attached to this cart line, such as gift messages or engraving text. Use `applyCartLinesChange()` to update these values.
```
Attribute[]
```
cost
The cost breakdown for this line item, including the total price after any line-level discounts have been applied.
```
CartLineCost
```
discountAllocations
Discounts applied to this cart line, including code-based, automatic, and custom discounts. Each allocation shows the discounted amount and how the discount was triggered.
```
CartDiscountAllocation[]
```
id
A unique identifier for the cart line in the format `gid://shopify/CartLine/<id>`. This ID isn't stable and can change after any cart operation, so avoid persisting it. Always look up the current ID before calling `applyCartLinesChange()`, because you'll need it to create a `CartLineChange` object.
```
string
```
lineComponents
The individual components of a [bundle](/docs/apps/build/product-merchandising/bundles) line item. Each component represents a separate product within the bundle. Returns an empty array if the line item isn't a bundle.
```
CartBundleLineComponent[]
```
merchandise
The product variant or other merchandise associated with this line item. Use this to access product details such as the title, image, SKU, and selected options.
```
Merchandise
```
parentRelationship
The parent line item that this line belongs to, or `null` if this is a top-level line item. Used to identify lines added as children of a bundle or other grouped product.
```
CartLineParentRelationship | null
```
quantity
The number of units of this merchandise that the buyer purchased.
```
number
```

Attribute

key
The identifier for the attribute. Each key must be unique within the set of attributes on the cart or checkout. If you call `applyAttributeChange()` with a key that already exists, then the existing value is replaced.
```
string
```
value
The value associated with the attribute key. This is a freeform string that can store any information the buyer or app provides. Attribute values are always strings. To store structured data, serialize it to JSON and parse it when reading.
```
string
```

CartLineCost

totalAmount
The total price the buyer pays for this line item after all line-level discounts have been applied, but before order-level discounts, taxes, and shipping.
```
Money
```

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'

CartDiscountAllocation

A discount allocation applied to the cart. Use the `type` property to determine how the discount was triggered: - `CartCodeDiscountAllocation` (`type: 'code'`): Triggered by a discount code the buyer entered. - `CartAutomaticDiscountAllocation` (`type: 'automatic'`): Applied automatically based on merchant-configured rules. - `CartCustomDiscountAllocation` (`type: 'custom'`): Applied by a [Shopify Function](/docs/api/functions/latest/discount).

CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation

CartCodeDiscountAllocation

code
The discount code string that the buyer entered during checkout, such as `"SAVE10"` or `"FREESHIP"`.
```
string
```
discountedAmount
The monetary value that was deducted from the line item or order total by this discount allocation.
```
Money
```
type
Identifies this as a code-based discount, triggered by a discount code the buyer entered at checkout.
```
'code'
```

CartAutomaticDiscountAllocation

discountedAmount
The monetary value that was deducted from the line item or order total by this discount allocation.
```
Money
```
title
The merchant-defined title of the automatic discount as displayed to the buyer, such as "Summer Sale 10% Off".
```
string
```
type
Identifies this as an automatic discount, applied based on merchant-configured rules without a code.
```
'automatic'
```

CartCustomDiscountAllocation

discountedAmount
The monetary value that was deducted from the line item or order total by this discount allocation.
```
Money
```
title
The title of the custom discount, typically applied by a [Shopify Function](/docs/api/functions/latest/discount).
```
string
```
type
Identifies this as a custom discount applied by a [Shopify Function](/docs/api/functions/latest/discount).
```
'custom'
```

CartBundleLineComponent

An individual component within a bundled cart line. Each `CartLine` that represents a bundle has a `lineComponents` array containing these components.

attributes
Custom key-value pairs attached to this bundle component, such as personalization options specific to this item within the bundle.
```
Attribute[]
```
cost
The cost breakdown for this bundle component, including the total amount after any per-item discounts.
```
CartLineCost
```
id
A unique identifier for this component within the bundle, in the format `gid://shopify/CartLineComponent/<id>`. This ID isn't stable and might change after any operation that updates the line items.
```
string
```
merchandise
The product variant included in this bundle component. Use this to display product details for individual items within a bundle.
```
Merchandise
```
quantity
The number of units of this component included in the bundle.
```
number
```
type
Identifies this as a bundle line component. This is currently the only component type.
```
'bundle'
```

Merchandise

id
A globally-unique identifier for the product variant in the format `gid://shopify/ProductVariant/<id>`.
```
string
```
image
The image associated with the product variant. Falls back to the product image if the variant doesn't have its own. The value is `undefined` if neither the variant nor the product has an image.
```
ImageDetails
```
product
The parent product that this variant belongs to. Use this to access the product's ID, vendor, and type.
```
Product
```
requiresShipping
Whether this product variant requires physical shipping. When `true`, the buyer must provide a shipping address. Returns `false` for digital products, gift cards, and services.
```
boolean
```
selectedOptions
The product options applied to this variant, such as size, color, or material. Each entry contains the option name and the selected value.
```
SelectedOption[]
```
sellingPlan
The [selling plan](/docs/apps/build/purchase-options/subscriptions) associated with this variant, such as a subscription or pre-order plan. The value is `undefined` if the item isn't being purchased through a selling plan.
```
SellingPlan
```
sku
The stock keeping unit (SKU) assigned to this variant by the merchant, used for inventory tracking. The value is `undefined` if no SKU has been set.
```
string
```
subtitle
A secondary description for the variant that provides additional context, such as a color or size combination. The value is `undefined` if no subtitle is available.
```
string
```
title
The display title of the product variant, such as "Small" or "Red / Large". This is the variant-specific label, not the parent product title.
```
string
```
type
Identifies the merchandise as a product variant. This is currently the only merchandise type in checkout.
```
'variant'
```

ImageDetails

altText
The alternative text for the image, used for accessibility. The value is `undefined` if the merchant hasn't provided alt text.
```
string
```
url
The fully-qualified URL of the image. Use this to render the product or variant image in your extension.
```
string
```

Product

id
A globally-unique identifier for the product in the format `gid://shopify/Product/<id>`.
```
string
```
productType
A merchant-defined categorization for the product, such as "Accessories" or "Clothing". Commonly used for filtering and organizing products in a storefront.
```
string
```
vendor
The name of the product's vendor or manufacturer, as set by the merchant in Shopify admin.
```
string
```

SelectedOption

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

SellingPlan

A [selling plan](/docs/apps/build/purchase-options/subscriptions) represents a recurring or deferred purchasing option for a product, such as a subscription, pre-order, or try-before-you-buy plan. The merchant configures selling plans to define how and when the buyer is charged.

id
A globally-unique identifier for the selling plan in the format `gid://shopify/SellingPlan/<id>`. Use this to reference the specific selling plan associated with a line item.
```
string
```
recurringDeliveries
Whether purchasing through this selling plan results in multiple deliveries. `true` for subscription plans with recurring fulfillment, `false` for one-time pre-orders or try-before-you-buy plans.
```
boolean
```

CartLineParentRelationship

parent
The parent cart line that a cart line is associated with.
```
{ id: string; }
```

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 <> required: The cart line that this extension is attached to. Use this to read the line item's merchandise, quantity, cost, and attributes.

Examples

jsx

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

import {render} from 'preact';

export default async () => {

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

};

function Extension() {

const lines = shopify.lines.value;

if (!lines || lines.length === 0) {

return <s-text>No items in this order.</s-text>;

}

return (

<s-stack>

{lines.map((line) => (

<s-box key={line.id}>

<s-stack direction="inline">

{line.merchandise.image?.url && (

<s-image

src={line.merchandise.image.url}

alt={line.merchandise.title}

)}

<s-stack>

<s-text type="strong">

{line.merchandise.title}

</s-text>

<s-text>Qty: {line.quantity}</s-text>

<s-text>

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

{line.cost.totalAmount.currencyCode}

</s-text>

</s-stack>

</s-box>

))}

</s-stack>

);

}

Examples

Description

Render a list of purchased items showing the product title, quantity, and total cost. This example iterates over `shopify.lines` and displays each line's `merchandise.title`, `quantity`, and `cost.totalAmount`.

jsx

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

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

function Extension() {
  const lines = shopify.lines.value;

  if (!lines || lines.length === 0) {
    return <s-text>No items in this order.</s-text>;
  }

  return (
    <s-stack>
      {lines.map((line) => (
        <s-box key={line.id}>
          <s-stack direction="inline">
            {line.merchandise.image?.url && (
              <s-image
                src={line.merchandise.image.url}
                alt={line.merchandise.title}
              />
            )}
            <s-stack>
              <s-text type="strong">
                {line.merchandise.title}
              </s-text>
              <s-text>Qty: {line.quantity}</s-text>
              <s-text>
                {line.cost.totalAmount.amount}{' '}
                {line.cost.totalAmount.currencyCode}
              </s-text>
            </s-stack>
          </s-stack>
        </s-box>
      ))}
    </s-stack>
  );
}

Description

Display the cost breakdown for individual line items, including any applied discounts. This example reads each line's `cost.totalAmount` and iterates over `discountAllocations` to show per-line discount details.

jsx

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

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

function Extension() {
  const lines = shopify.lines.value;

  if (!lines || lines.length === 0) {
    return null;
  }

  return (
    <s-stack>
      {lines.map((line) => (
        <s-box key={line.id}>
          <s-text type="strong">
            {line.merchandise.title}
          </s-text>
          <s-text>
            Total: {line.cost.totalAmount.amount}{' '}
            {line.cost.totalAmount.currencyCode}
          </s-text>
          {line.discountAllocations.length > 0 && (
            <s-stack>
              {line.discountAllocations.map(
                (discount, i) => (
                  <s-text
                    color="subdued"
                    key={i}
                  >
                    Discount:{' '}
                    {discount.discountedAmount.amount}{' '}
                    {
                      discount.discountedAmount
                        .currencyCode
                    }
                  </s-text>
                ),
              )}
            </s-stack>
          )}
          <s-divider />
        </s-box>
      ))}
    </s-stack>
  );
}

Description

Identify bundle products and display their individual sub-items. This example checks each cart line for `lineComponents` and renders the parent product with its bundled components underneath.

jsx

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

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

function Extension() {
  const lines = shopify.lines.value;
  const bundles = lines?.filter(
    (line) => line.lineComponents.length > 0,
  );

  if (!bundles || bundles.length === 0) {
    return null;
  }

  return (
    <s-stack>
      {bundles.map((bundle) => (
        <s-box key={bundle.id}>
          <s-text type="strong">
            {bundle.merchandise.title} (Bundle)
          </s-text>
          <s-text>Qty: {bundle.quantity}</s-text>
          <s-divider />
          <s-stack>
            {bundle.lineComponents.map(
              (component) => (
                <s-text key={component.id}>
                  ↳ {component.merchandise.title} ×{' '}
                  {component.quantity}
                </s-text>
              ),
            )}
          </s-stack>
        </s-box>
      ))}
    </s-stack>
  );
}

Anchor to Best practicesBest practices

Group related lines by product: Multiple cart lines can reference the same product with different variants or options. Group by merchandise.product.id if you need to show a product-level summary.

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?