--- title: Cart Lines API description: >- 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. api_version: 2027-01 source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/target-apis/order-apis/cart-lines-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/target-apis/order-apis/cart-lines-api.md api_name: customer-account-ui-extensions --- # Cart Lines API The Cart Lines API provides read-only access to the line items in an order on the [Order status page](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/targets/order-status). Use this API to read merchandise details, quantities, per-line costs, discount allocations, and [bundle](https://shopify.dev/docs/apps/build/product-merchandising/bundles) components for each item the customer purchased. ### 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/2027-01-rc/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/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/2027-01-rc/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/2027-01-rc/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/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/2027-01-rc/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/2027-01-rc/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/targets/full-page#order-specific-full-page-) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc#target-apis-define-what-your-extension-does) 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. * **lines** **SubscribableSignalLike\** **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. ```ts 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. ```ts () => Promise ``` * 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. ```ts (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. ```ts T ``` ### CartLine * attributes Custom key-value pairs attached to this line item, such as engraving text, gift messages, or personalization options set by the buyer or an app during checkout. ```ts Attribute[] ``` * cost The cost breakdown for this line item, including the total price after any line-level discounts have been applied. ```ts CartLineCost ``` * discountAllocations The list of discounts applied to this specific line item. Each allocation includes the discounted amount and the type of discount (\`code\`, \`automatic\`, or \`custom\`). ```ts CartDiscountAllocation[] ``` * id A unique identifier for the cart line in the format \`gid://shopify/CartLine/\\`. These IDs are not stable and may change after any operations on the line items, so avoid persisting them. ```ts 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. ```ts 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. ```ts Merchandise ``` * quantity The number of units of this merchandise that the buyer purchased. ```ts number ``` ### Attribute * key The identifier for the attribute. Use this to distinguish between different custom attributes on a line item or order. ```ts string ``` * value The value associated with the attribute key. This contains the buyer-provided or app-set data for the custom attribute. Attribute values are always strings. If structured data was stored during checkout, parse it on read with \`JSON.parse()\`. ```ts 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. ```ts Money ``` ### Money * amount The decimal amount of the price. For example, \`29.99\` represents twenty-nine dollars and ninety-nine cents. ```ts number ``` * currencyCode The three-letter currency code in \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) format. ```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 represents a single discount applied to a specific line item or the overall order. When a discount applies to an order, Shopify splits the total discount amount across the affected line items as individual allocations. For example, a "10% off your order" discount is distributed proportionally across each line item rather than appearing as one lump sum. There are three types of discount allocations: - \`CartCodeDiscountAllocation\`: A discount applied using a code the buyer entered at checkout (for example, "SAVE10"). - \`CartAutomaticDiscountAllocation\`: A discount the merchant configured in Shopify admin to apply automatically without a code. - \`CartCustomDiscountAllocation\`: A discount created programmatically by a \[Shopify Function]\(/docs/apps/build/functions). ```ts CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation ``` ### CartCodeDiscountAllocation A discount allocation for a discount that was applied using a code the buyer entered at checkout. * code The discount code string that the buyer entered during checkout, such as "SAVE10" or "FREESHIP". ```ts string ``` * discountedAmount The monetary value that was deducted from the line item or order total by this discount allocation. ```ts Money ``` * type The type of this discount allocation. Always \`'code'\` for discounts applied using a code entered by the buyer. ```ts 'code' ``` ### CartAutomaticDiscountAllocation A discount allocation for a discount that the merchant configured to apply automatically in Shopify admin, without the buyer needing to enter a code. * discountedAmount The monetary value that was deducted from the line item or order total by this discount allocation. ```ts Money ``` * title The merchant-defined title of the automatic discount as displayed to the buyer, such as "Summer Sale 10% Off". ```ts string ``` * type The type of this discount allocation. Always \`'automatic'\` for discounts configured to apply automatically without a code. ```ts 'automatic' ``` ### CartCustomDiscountAllocation A discount allocation for a discount created by a \[Shopify Function]\(/docs/apps/build/functions), such as a custom discount logic app. * discountedAmount The monetary value that was deducted from the line item or order total by this discount allocation. ```ts Money ``` * title The title of the custom discount as defined by the Shopify Function that created it. ```ts string ``` * type The type of this discount allocation. Always \`'custom'\` for discounts created by a Shopify Function. ```ts 'custom' ``` ### CartBundleLineComponent * attributes Custom key-value pairs attached to this bundle component, such as personalization options specific to this item within the bundle. ```ts Attribute[] ``` * cost The cost breakdown for this bundle component, representing the portion of the bundle price attributed to this item. ```ts CartLineCost ``` * id A unique identifier for this component within the bundle, in the format \`gid://shopify/CartLineComponent/\\`. This ID isn't stable and may change after any operation that updates the line items. ```ts string ``` * merchandise The product variant included in this bundle component. Use this to display product details for individual items within a bundle. ```ts Merchandise ``` * quantity The number of units of this component included in the bundle. ```ts number ``` * type The type of line component. Always \`'bundle'\` for bundle line components. ```ts 'bundle' ``` ### Merchandise * id A globally-unique identifier for the product variant in the format \`gid://shopify/ProductVariant/\\`. ```ts string ``` * image The image associated with this product variant. Falls back to the parent product's featured image if the variant doesn't have its own image. ```ts ImageDetails ``` * product The parent product that this variant belongs to. Use this to access the product title, vendor, and type. ```ts Product ``` * requiresShipping Whether this product variant requires physical shipping. Returns \`false\` for digital products, gift cards, and services. ```ts boolean ``` * selectedOptions The list of product options that define this variant, such as size and color. Each entry contains the option name and the selected value. ```ts SelectedOption[] ``` * sellingPlan The selling plan associated with this merchandise, such as a subscription or pre-order plan. The value is \`undefined\` if the item was purchased without a selling plan. ```ts 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. ```ts 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. ```ts 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. ```ts string ``` * type The type of merchandise. Always \`'variant'\` for product variants. ```ts 'variant' ``` ### ImageDetails * altText The alternative text description of the image, used for accessibility. The value is \`undefined\` if the merchant hasn't set alt text for the image. ```ts string ``` * url The fully-qualified URL of the image. Use this to render the product or variant image in your extension. ```ts string ``` ### Product * id A globally-unique identifier for the product in the format \`gid://shopify/Product/\\`. ```ts string ``` * productType A merchant-defined categorization for the product, such as "Accessories" or "Clothing". Commonly used for filtering and organizing products in a storefront. ```ts string ``` * vendor The name of the product's vendor or manufacturer, as set by the merchant in Shopify admin. ```ts string ``` ### SelectedOption * name The name of the product option, such as "Size", "Color", or "Material". ```ts string ``` * value The selected value for this option, such as "Medium", "Blue", or "Cotton". ```ts string ``` ### SellingPlan A selling plan represents a recurring or deferred purchasing option for a product, such as a \[subscription]\(/docs/apps/build/purchase-options/subscriptions), pre-order, or try-before-you-buy arrangement. Selling plans are configured by the merchant and define how and when the buyer is charged. * id A globally-unique identifier for the selling plan in the format \`gid://shopify/SellingPlan/\\`. Use this to reference the specific selling plan associated with a line item. ```ts string ``` ### Cart line item properties The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc#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** **SubscribableSignalLike\** **required** The cart line that this extension is attached to. Use this to read the line item's merchandise, quantity, cost, and attributes. ### Examples * #### Display order items ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const lines = shopify.lines.value; if (!lines || lines.length === 0) { return No items in this order.; } return ( {lines.map((line) => ( {line.merchandise.image?.url && ( )} {line.merchandise.title} Qty: {line.quantity} {line.cost.totalAmount.amount}{' '} {line.cost.totalAmount.currencyCode} ))} ); } ``` * #### Show line-level pricing ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const lines = shopify.lines.value; if (!lines || lines.length === 0) { return null; } return ( {lines.map((line) => ( {line.merchandise.title} Total: {line.cost.totalAmount.amount}{' '} {line.cost.totalAmount.currencyCode} {line.discountAllocations.length > 0 && ( {line.discountAllocations.map( (discount, i) => ( Discount:{' '} {discount.discountedAmount.amount}{' '} { discount.discountedAmount .currencyCode } ), )} )} ))} ); } ``` * #### Detect and display bundle components ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, 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 ( {bundles.map((bundle) => ( {bundle.merchandise.title} (Bundle) Qty: {bundle.quantity} {bundle.lineComponents.map( (component) => ( ↳ {component.merchandise.title} ×{' '} {component.quantity} ), )} ))} ); } ``` *** ## Best 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. *** ## 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. ***