---
title: Cart Lines API
description: >-
  The Cart Lines API provides access to the line items in the buyer's cart
  during checkout. Use this API to display item details, calculate totals, and
  modify cart line items.
api_version: 2026-04
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/cart-lines-api
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/cart-lines-api.md
---

# Cart Lines API

The Cart Lines API provides access to the line items in the buyer's cart during checkout. Use this API to display item details, calculate totals, and modify cart line items.

### Use cases

* **Display cart line item details**: Show each item's title, quantity, and price to the buyer.
* **Calculate cart totals**: Aggregate quantities or amounts across all line items.
* **Modify cart line items**: Add, remove, or update items in the buyer's cart programmatically.

### Support Targets (31)

### Supported targets

* [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target)
* [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target)
* [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets)
* [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-)
* purchase.​checkout.​chat.​render
* [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target)
* [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-)
* [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets)
* [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target)
* [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target)
* [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-)
* [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets)
* [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-)
* [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets)
* [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target)
* [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-)
* [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets)
* [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-)
* [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets)
* [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets)
* [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-)
* [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-)
* [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets)
* [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-)
* [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target)
* [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets)
* [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-)
* purchase.​thank-you.​chat.​render
* [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target)
* [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target)
* [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target)

### Properties

The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides cart line data for the current checkout. Access the following properties on `shopify` to read the items in the buyer's cart. Available to `purchase` extension targets.

* **lines**

  **SubscribableSignalLike\<CartLine\[]>**

  **required**

  The list of line items the buyer intends to purchase. Each entry includes the merchandise, quantity, cost, and any custom attributes. Use `applyCartLinesChange()` to add, remove, or update line items.

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

  ```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 attributes attached to this cart line, such as gift messages or engraving text. Use \`applyCartLinesChange()\` to update these values.

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

  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.

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

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

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

  ```ts
  CartLineParentRelationship | null
  ```

* quantity

  The number of units of this merchandise that the buyer purchased.

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

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

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

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

### CartCodeDiscountAllocation

* 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

  Identifies this as a code-based discount, triggered by a discount code the buyer entered at checkout.

  ```ts
  'code'
  ```

### CartAutomaticDiscountAllocation

* 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

  Identifies this as an automatic discount, applied based on merchant-configured rules without a code.

  ```ts
  'automatic'
  ```

### CartCustomDiscountAllocation

* 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, typically applied by a \[Shopify Function]\(/docs/api/functions/latest/discount).

  ```ts
  string
  ```

* type

  Identifies this as a custom discount applied by a \[Shopify Function]\(/docs/api/functions/latest/discount).

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

  ```ts
  Attribute[]
  ```

* cost

  The cost breakdown for this bundle component, including the total amount after any per-item discounts.

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

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

  Identifies this as a bundle line component. This is currently the only component type.

  ```ts
  'bundle'
  ```

### Merchandise

* id

  A globally-unique identifier for the product variant in the format \`gid://shopify/ProductVariant/\<id>\`.

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

  ```ts
  ImageDetails
  ```

* product

  The parent product that this variant belongs to. Use this to access the product's ID, vendor, and type.

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

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

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

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

  Identifies the merchandise as a product variant. This is currently the only merchandise type in checkout.

  ```ts
  'variant'
  ```

### ImageDetails

* altText

  The alternative text for the image, used for accessibility. The value is \`undefined\` if the merchant hasn't provided alt text.

  ```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/\<id>\`.

  ```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 "Color" or "Size".

  ```ts
  string
  ```

* value

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

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

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

  ```ts
  boolean
  ```

### CartLineParentRelationship

* parent

  The parent cart line that a cart line is associated with.

  ```ts
  { id: string; }
  ```

### Cart line item properties

The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#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\<CartLine>**

  **required**

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

  Available only on the corresponding item target. Shipping option item targets expose shipping option properties; pickup location item targets expose pickup location properties.

  **Note:** Until version \<code>2023-04\</code>, this property was a \<code>\<span class="PreventFireFoxApplyingGapToWBR">Readonly\<wbr/>Signal\<wbr/>Like\&lt;Presentment\<wbr/>Cart\<wbr/>Line\&gt;\</span>\</code>.

### Methods

The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides methods to modify cart line data. Access the following methods on `shopify` to apply cart line changes. Available to `purchase.checkout` extension targets.

* **applyCartLinesChange**

  **(change: CartLineChange) => Promise\<CartLineChangeResult>**

  **required**

  Adds, removes, or updates line items in the cart. The returned promise resolves when the change has been applied by the server, and the [`lines`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/cart-lines#properties-propertydetail-lines) property updates with the new state.

  Accepts a single change per call. To make multiple changes, call this method separately for each one.

  **Note:** This method returns an error if the \<a href="/docs/api/checkout-ui-extensions/latest/apis/cart-instructions#properties-propertydetail-instructions">cart instruction\</a> \<code>\<span class="PreventFireFoxApplyingGapToWBR">lines.can\<wbr/>Add\<wbr/>Cart\<wbr/>Line\</span>\</code> is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

### CartLineChange

The input for \`applyCartLinesChange()\`. Use the \`type\` property to specify the operation. - \`CartLineAddChange\` (\`type: 'addCartLine'\`): Adds a new line item to the cart. - \`CartLineRemoveChange\` (\`type: 'removeCartLine'\`): Removes an existing line item. - \`CartLineUpdateChange\` (\`type: 'updateCartLine'\`): Updates an existing line item's quantity, variant, or attributes.

```ts
CartLineAddChange | CartLineRemoveChange | CartLineUpdateChange
```

### CartLineAddChange

Adds a new line item to the cart. Pass this to \`applyCartLinesChange()\` to add a product variant with a specified quantity and optional attributes.

* attributes

  Custom key-value attributes to attach to the new line item.

  ```ts
  Attribute[]
  ```

* merchandiseId

  The globally-unique identifier of the product variant to add.

  ```ts
  string
  ```

* parent

  The parent cart line to associate the new item with, identified by either \`lineId\` or \`merchandiseId\`. Use this when adding child items to a bundle.

  ```ts
  {lineId: string} | {merchandiseId: string}
  ```

* quantity

  The number of items to add. Must be a positive integer.

  ```ts
  number
  ```

* sellingPlanId

  The identifier of the \[selling plan]\(/docs/apps/build/purchase-options/subscriptions) to associate with this line item, such as a subscription or pre-order plan.

  ```ts
  string
  ```

* type

  Identifies this as a line item addition. Set this when creating a change to add a new product to the cart.

  ```ts
  'addCartLine'
  ```

### CartLineRemoveChange

Removes an existing line item from the cart. Pass this to \`applyCartLinesChange()\` to remove a specified quantity of a line item.

* id

  The unique identifier of the cart line to remove. Look up the current ID from \`lines\` before calling, because cart line IDs aren't stable.

  ```ts
  string
  ```

* quantity

  The number of items to remove from this line.

  ```ts
  number
  ```

* type

  Identifies this as a line item removal. Set this when creating a change to remove a product from the cart.

  ```ts
  'removeCartLine'
  ```

### CartLineUpdateChange

Updates an existing line item in the cart. Pass this to \`applyCartLinesChange()\` to change a line item's quantity, variant, selling plan, or attributes.

* attributes

  The new custom key-value attributes for this line item. Replaces all existing attributes when provided.

  ```ts
  Attribute[]
  ```

* id

  The unique identifier of the cart line to update. Look up the current ID from \`lines\` before calling, because cart line IDs aren't stable.

  ```ts
  string
  ```

* merchandiseId

  The new product variant to swap in for this line item. Only provide this if you want to change the variant.

  ```ts
  string
  ```

* parent

  The parent cart line to associate this item with. Use this when updating the parent relationship for bundled items.

  ```ts
  {lineId: string} | {merchandiseId: string}
  ```

* quantity

  The new quantity for this line item. Only provide this if you want to change the quantity.

  ```ts
  number
  ```

* sellingPlanId

  The \[selling plan]\(/docs/apps/build/purchase-options/subscriptions) to associate with this line item. Pass \`null\` to remove the item from its current selling plan.

  ```ts
  SellingPlan['id'] | null
  ```

* type

  Identifies this as a line item update. Set this when creating a change to modify a line item's quantity, variant, or attributes.

  ```ts
  'updateCartLine'
  ```

### CartLineChangeResult

The result of calling \`applyCartLinesChange()\`. Use the \`type\` property to determine whether the change succeeded or failed.

```ts
CartLineChangeResultSuccess | CartLineChangeResultError
```

### CartLineChangeResultSuccess

The result of a successful cart line change. The \`type\` property is \`'success'\`.

* type

  Indicates that the cart line change was applied successfully.

  ```ts
  'success'
  ```

### CartLineChangeResultError

The result of a failed cart line change. Check the \`message\` property for details about what went wrong.

* message

  A message that explains the error. This message is useful for debugging. It isn't localized and shouldn't be displayed to the buyer. Render your own localized error text rather than displaying this message to the buyer.

  ```ts
  string
  ```

* type

  Indicates that the line item wasn't changed successfully. Refer to the \`message\` property for details about the error.

  ```ts
  'error'
  ```

Examples

### Examples

* ####

  ##### Description

  Retrieve the current line item from a cart line extension target. This example uses \`shopify.target\` to get the merchandise title and displays it as inline text.

  ##### jsx

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

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

  function Extension() {
    return (
      <s-text>
        Line item title:{' '}
        {shopify.target.value.merchandise.title}
      </s-text>
    );
  }
  ```

* ####

  ##### Description

  Render a breakdown of all items in the buyer's cart. This example reads \`shopify.cartLines\` and displays each line's merchandise title, quantity, and total price, with a summary count at the top.

  ##### jsx

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

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

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

    const totalQuantity = cartLines.reduce(
      (sum, line) => sum + line.quantity,
      0,
    );

    return (
      <s-stack>
        <s-text type="strong">
          {totalQuantity}{' '}
          {totalQuantity === 1 ? 'item' : 'items'}{' '}
          in your cart
        </s-text>
        {cartLines.map((line) => (
          <s-stack
            key={line.id}
            direction="inline"
            gap="small-200"
          >
            <s-text>
              {line.merchandise.title} × {line.quantity}
            </s-text>
            <s-text>
              {line.cost.totalAmount.amount}{' '}
              {line.cost.totalAmount.currencyCode}
            </s-text>
          </s-stack>
        ))}
      </s-stack>
    );
  }
  ```

***

## Best practices

* **Read the latest `lines` before mutating**: Cart line IDs aren't stable across updates. Always read the current `lines` value immediately before passing a line ID to `applyCartLinesChange` to avoid referencing a stale ID.
* **Check the relevant cart instruction for each operation**: The [Cart Instructions API](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions) exposes `lines.canAddCartLine`, `lines.canRemoveCartLine`, and `lines.canUpdateCartLine`. Check the specific instruction that matches your intended operation.

***

## Limitations

* Cart line changes aren't available when the buyer uses an accelerated checkout method such as Apple Pay or Google Pay.

***
