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 API for interacting with the cart lines.

Anchor to StandardApiStandardApi

The base API object provided to purchase extension targets.

Anchor to lines lines StatefulRemoteSubscribable<[]> required: A list of lines containing information about the items the customer intends to purchase.

CartLine

attributes
The line item additional custom attributes.
```
Attribute[]
```
cost
The details about the cost components attributed to the cart line.
```
CartLineCost
```
discountAllocations
Discounts applied to the cart line.
```
CartDiscountAllocation[]
```
id
These line item IDs are not stable at the moment, they might change after any operations on the line items. You should always look up for an updated ID before any call to `applyCartLinesChange` because you'll need the ID to create a `CartLineChange` object.
```
string
```
lineComponents
Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
```
CartBundleLineComponent[]
```
merchandise
The merchandise being purchased.
```
Merchandise
```
quantity
The quantity of the merchandise being purchased.
```
number
```

Attribute

key
The key for the attribute.
```
string
```
value
The value for the attribute.
```
string
```

CartLineCost

totalAmount
The total amount after reductions the buyer can expect to pay that is directly attributable to a single cart line.
```
Money
```

Money

amount
The price amount.
```
number
```
currencyCode
The ISO 4217 format for the currency.
```
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

CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation

CartCodeDiscountAllocation

code
The code for the discount
```
string
```
discountedAmount
The money amount that has been discounted from the order
```
Money
```
type
The type of the code discount
```
'code'
```

CartAutomaticDiscountAllocation

discountedAmount
The money amount that has been discounted from the order
```
Money
```
title
The title of the automatic discount
```
string
```
type
The type of the automatic discount
```
'automatic'
```

CartCustomDiscountAllocation

discountedAmount
The money amount that has been discounted from the order
```
Money
```
title
The title of the custom discount
```
string
```
type
The type of the custom discount
```
'custom'
```

CartBundleLineComponent

attributes
Additional custom attributes for the bundle line component.
```
Attribute[]
```
cost
The cost attributed to this bundle line component.
```
CartLineCost
```
id
A unique identifier for the bundle line component. This ID is not stable. If an operation updates the line items in any way, all IDs could change.
```
string
```
merchandise
The merchandise of this bundle line component.
```
Merchandise
```
quantity
The quantity of merchandise being purchased.
```
number
```
type
```
'bundle'
```

Merchandise

id
A globally-unique identifier.
```
string
```
image
Image associated with the product variant. This field falls back to the product image if no image is available.
```
ImageDetails
```
product
The product object that the product variant belongs to.
```
Product
```
requiresShipping
Whether or not the product requires shipping.
```
boolean
```
selectedOptions
List of product options applied to the variant.
```
SelectedOption[]
```
sellingPlan
The selling plan associated with the merchandise.
```
SellingPlan
```
sku
The product variant's sku.
```
string
```
subtitle
The product variant's subtitle.
```
string
```
title
The product variant’s title.
```
string
```
type
```
'variant'
```

ImageDetails

altText
The alternative text for the image.
```
string
```
url
The image URL.
```
string
```

Product

id
A globally-unique identifier.
```
string
```
productType
A categorization that a product can be tagged with, commonly used for filtering and searching.
```
string
```
vendor
The product’s vendor name.
```
string
```

SelectedOption

name
The name of the merchandise option.
```
string
```
value
The value of the merchandise option.
```
string
```

SellingPlan

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

Anchor to useCartLines
useCartLines()

Returns the current line items for the checkout, and automatically re-renders your component if line items are added, removed, or updated.

Anchor to useCartLines-returnsReturns

[]

Anchor to CheckoutApiCheckoutApi

The API object provided to purchase.checkout extension targets.

Anchor to applyCartLinesChange applyCartLinesChange (change: ) => Promise<> required: Performs an update on the merchandise line items. It resolves when the new line items have been negotiated and results in an update to the value retrieved through the lines property.

Note
This method will return an error if the cart instruction lines.canAddCartLine is false, or the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.
Note: This method will return an error if the <a href="/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions">cart instruction</a> <code>lines.canAddCartLine</code> is false, or the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

CartLineChange

CartLineAddChange | CartLineRemoveChange | CartLineUpdateChange

CartLineAddChange

attributes
The attributes associated with the line item.
```
Attribute[]
```
merchandiseId
The merchandise ID being added.
```
string
```
quantity
The quantity of the merchandise being added.
```
number
```
sellingPlanId
The identifier of the selling plan that the merchandise is being purchased with.
```
string
```
type
An identifier for changes that add line items.
```
'addCartLine'
```

CartLineRemoveChange

id
Line Item ID.
```
string
```
quantity
The quantity being removed for this line item.
```
number
```
type
An identifier for changes that remove line items.
```
'removeCartLine'
```

CartLineUpdateChange

attributes
The new attributes for the line item.
```
Attribute[]
```
id
Line Item ID.
```
string
```
merchandiseId
The new merchandise ID for the line item.
```
string
```
quantity
The new quantity for the line item.
```
number
```
sellingPlanId
The identifier of the selling plan that the merchandise is being purchased with or `null` to remove the the product from the selling plan.
```
SellingPlan['id'] | null
```
type
An identifier for changes that update line items.
```
'updateCartLine'
```

CartLineChangeResult

CartLineChangeResultSuccess | CartLineChangeResultError

CartLineChangeResultSuccess

type
Indicates that the line item was changed successfully.
```
'success'
```

CartLineChangeResultError

message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```
type
Indicates that the line item was not changed successfully. Refer to the `message` property for details about the error.
```
'error'
```

Anchor to useApplyCartLinesChange
useApplyCartLinesChange()

Returns a function to mutate the lines property of checkout.

Anchor to useApplyCartLinesChange-returnsReturns

(change: ) => Promise<>

Anchor to CartLineItemApiCartLineItemApi

The API object provided to cart-line-item extension targets.

Anchor to target target StatefulRemoteSubscribable<> required: The cart line the extension is attached to. Until version 2023-04, this property was a StatefulRemoteSubscribable<PresentmentCartLine>.

Anchor to useTarget
useTarget()

Returns the cart line the extension is attached to. This hook can only be used by extensions in the purchase.cart-line-item.line-components.render, purchase.checkout.cart-line-item.render-after, and purchase.thank-you.cart-line-item.render-after extension targets. Until version 2023-04, this hook returned a PresentmentCartLine object.

Caution

Deprecated as of version 2023-10, use useCartLineTarget() instead.

Anchor to useTarget-returnsReturns

Anchor to useCartLineTarget
useCartLineTarget()

Returns the cart line the extension is attached to. This hook can only be used by extensions in the following extension targets:

purchase.cart-line-item.line-components.render
purchase.checkout.cart-line-item.render-after
purchase.thank-you.cart-line-item.render-after

Anchor to useCartLineTarget-returnsReturns

Examples

import {

reactExtension,

Text,

useCartLineTarget,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.cart-line-item.render-after',

() => <Extension />,

);

function Extension() {

const {

merchandise: {title},

} = useCartLineTarget();

return <Text>Line item title: {title}</Text>;

}