---
title: CartLineItemApi
description: >

  This API object is provided to extensions registered for the
  `purchase.cart-line-item.line-components.render`,
  `purchase.checkout.cart-line-item.render-after`,
  `purchase.thank-you.cart-line-item.render-after`, and
  `customer-account.order-status.cart-line-item.render-after` extension targets.


  It extends the
  [StandardApi](/docs/api/checkout-ui-extensions/apis/standardapi) and provides
  the [target](#properties-propertydetail-target) cart line item associated with
  the extension.
api_version: 2023-07
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/apis/cartlineitemapi
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2023-07/apis/cartlineitemapi.md
---

# Cart​Line​Item​Api

Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) for some properties.

This API object is provided to extensions registered for the `purchase.cart-line-item.line-components.render`, `purchase.checkout.cart-line-item.render-after`, `purchase.thank-you.cart-line-item.render-after`, and `customer-account.order-status.cart-line-item.render-after` extension targets.

It extends the [StandardApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi) and provides the [target](#properties-propertydetail-target) cart line item associated with the extension.

## Properties

See the [StandardApi examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#examples) for more information on how to use the API.

* target

  StatefulRemoteSubscribable\<CartLine>

  required

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

### CartLine

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

  ```ts
  string
  ```

* merchandise

  The merchandise being purchased.

  ```ts
  Merchandise
  ```

* quantity

  The quantity of the merchandise being purchased.

  ```ts
  number
  ```

* cost

  The details about the cost components attributed to the cart line.

  ```ts
  CartLineCost
  ```

* attributes

  The line item additional custom attributes.

  ```ts
  Attribute[]
  ```

* discountAllocations

  Discounts applied to the cart line.

  ```ts
  CartDiscountAllocation[]
  ```

* lineComponents

  Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.

  ```ts
  CartBundleLineComponent[]
  ```

```ts
export interface CartLine {
  /**
   * 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.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The merchandise being purchased.
   */
  merchandise: Merchandise;

  /**
   * The quantity of the merchandise being purchased.
   */
  quantity: number;

  /**
   * The details about the cost components attributed to the cart line.
   */
  cost: CartLineCost;

  /**
   * The line item additional custom attributes.
   */
  attributes: Attribute[];

  /**
   * Discounts applied to the cart line.
   */
  discountAllocations: CartDiscountAllocation[];

  /**
   * Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
   */
  lineComponents: CartLineComponentType[];
}
```

### Merchandise

* type

  ```ts
  "variant"
  ```

* id

  A globally-unique identifier.

  ```ts
  string
  ```

* title

  The product variant’s title.

  ```ts
  string
  ```

* subtitle

  The product variant's subtitle.

  ```ts
  string
  ```

* image

  Image associated with the product variant. This field falls back to the product image if no image is available.

  ```ts
  ImageDetails
  ```

* selectedOptions

  List of product options applied to the variant.

  ```ts
  SelectedOption[]
  ```

* product

  The product object that the product variant belongs to.

  ```ts
  Product
  ```

* requiresShipping

  Whether or not the product requires shipping.

  ```ts
  boolean
  ```

* sellingPlan

  The selling plan associated with the merchandise.

  ```ts
  SellingPlan
  ```

```ts
ProductVariant
```

### ImageDetails

* url

  The image URL.

  ```ts
  string
  ```

* altText

  The alternative text for the image.

  ```ts
  string
  ```

```ts
export interface ImageDetails {
  /**
   * The image URL.
   */
  url: string;

  /**
   * The alternative text for the image.
   */
  altText?: string;
}
```

### SelectedOption

* name

  The name of the merchandise option.

  ```ts
  string
  ```

* value

  The value of the merchandise option.

  ```ts
  string
  ```

```ts
export interface SelectedOption {
  /**
   * The name of the merchandise option.
   */
  name: string;

  /**
   * The value of the merchandise option.
   */
  value: string;
}
```

### Product

* id

  A globally-unique identifier.

  ```ts
  string
  ```

* vendor

  The product’s vendor name.

  ```ts
  string
  ```

* productType

  A categorization that a product can be tagged with, commonly used for filtering and searching.

  ```ts
  string
  ```

```ts
export interface Product {
  /**
   * A globally-unique identifier.
   */
  id: string;

  /**
   * The product’s vendor name.
   */
  vendor: string;

  /**
   * A categorization that a product can be tagged with, commonly used for filtering and searching.
   */
  productType: string;
}
```

### SellingPlan

* id

  A globally-unique identifier.

  ```ts
  string
  ```

```ts
export interface SellingPlan {
  /**
   * A globally-unique identifier.
   * @example 'gid://shopify/SellingPlan/1'
   */
  id: string;
}
```

### CartLineCost

* totalAmount

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

  ```ts
  Money
  ```

```ts
export interface CartLineCost {
  /**
   * The total amount after reductions the buyer can expect to pay that is directly attributable to a single
   * cart line.
   */
  totalAmount: Money;
}
```

### Money

* amount

  The price amount.

  ```ts
  number
  ```

* currencyCode

  The ISO 4217 format for the currency.

  ```ts
  CurrencyCode
  ```

```ts
export interface Money {
  /**
   * The price amount.
   */
  amount: number;
  /**
   * The ISO 4217 format for the currency.
   * @example 'CAD' for Canadian dollar
   */
  currencyCode: 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'
```

### Attribute

* key

  The key for the attribute.

  ```ts
  string
  ```

* value

  The value for the attribute.

  ```ts
  string
  ```

```ts
export interface Attribute {
  /**
   * The key for the attribute.
   */
  key: string;

  /**
   * The value for the attribute.
   */
  value: string;
}
```

### CartDiscountAllocation

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

### CartCodeDiscountAllocation

* code

  The code for the discount

  ```ts
  string
  ```

* type

  The type of the code discount

  ```ts
  "code"
  ```

* discountedAmount

  The money amount that has been discounted from the order

  ```ts
  Money
  ```

```ts
export interface CartCodeDiscountAllocation extends CartDiscountAllocationBase {
  /**
   * The code for the discount
   */
  code: string;

  /**
   * The type of the code discount
   */
  type: 'code';
}
```

### CartAutomaticDiscountAllocation

* title

  The title of the automatic discount

  ```ts
  string
  ```

* type

  The type of the automatic discount

  ```ts
  "automatic"
  ```

* discountedAmount

  The money amount that has been discounted from the order

  ```ts
  Money
  ```

```ts
export interface CartAutomaticDiscountAllocation
  extends CartDiscountAllocationBase {
  /**
   * The title of the automatic discount
   */
  title: string;

  /**
   * The type of the automatic discount
   */
  type: 'automatic';
}
```

### CartCustomDiscountAllocation

* title

  The title of the custom discount

  ```ts
  string
  ```

* type

  The type of the custom discount

  ```ts
  "custom"
  ```

* discountedAmount

  The money amount that has been discounted from the order

  ```ts
  Money
  ```

```ts
export interface CartCustomDiscountAllocation
  extends CartDiscountAllocationBase {
  /**
   * The title of the custom discount
   */
  title: string;

  /**
   * The type of the custom discount
   */
  type: 'custom';
}
```

### CartBundleLineComponent

* type

  ```ts
  "bundle"
  ```

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

  ```ts
  string
  ```

* merchandise

  The merchandise of this bundle line component.

  ```ts
  Merchandise
  ```

* quantity

  The quantity of merchandise being purchased.

  ```ts
  number
  ```

* cost

  The cost attributed to this bundle line component.

  ```ts
  CartLineCost
  ```

* attributes

  Additional custom attributes for the bundle line component.

  ```ts
  Attribute[]
  ```

```ts
export interface CartBundleLineComponent {
  type: 'bundle';

  /**
   * 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.
   *
   * @example 'gid://shopify/CartLineComponent/123'
   */
  id: string;

  /**
   * The merchandise of this bundle line component.
   */
  merchandise: Merchandise;

  /**
   * The quantity of merchandise being purchased.
   */
  quantity: number;

  /**
   * The cost attributed to this bundle line component.
   */
  cost: CartLineCost;

  /**
   * Additional custom attributes for the bundle line component.
   *
   * @example [{key: 'engraving', value: 'hello world'}]
   */
  attributes: Attribute[];
}
```

### Examples

* ####

  ##### React

  ```jsx
  import {
    reactExtension,
    Text,
    useTarget,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.cart-line-item.render-after',
    () => <Extension />,
  );

  function Extension() {
    const {
      merchandise: {title},
    } = useTarget();
    return <Text>Line item title: {title}</Text>;
  }
  ```

  ##### JavaScript

  ```js
  import {extension} from '@shopify/ui-extensions/checkout';

  export default extension(
    'purchase.checkout.cart-line-item.render-after',
    (root, {target}) => {
      const text = root.createText(
        `Line item title: ${target.current.title}`,
      );
      root.appendChild(text);

      target.subscribe((updatedTarget) => {
        text.updateText(
          `Line item title: ${updatedTarget.title}`,
        );
      });
    },
  );
  ```

## Related

[APIs - StandardApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi)

[APIs - CheckoutApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/checkoutapi)

[APIs - OrderStatusApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/orderstatusapi)

[APIs - PickupPointListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuppointlistapi)

[APIs - PickupLocationListApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/pickuplocationlistapi)

[APIs - ShippingOptionItemApi](https://shopify.dev/docs/api/checkout-ui-extensions/apis/shippingoptionitemapi)

[APIs - ExtensionTargets](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensiontargets)