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 Line Item API

The Cart Line Item API provides read-only access to a specific line item in the cart. Use this API to get line item details like product information, pricing, discounts, and custom properties. This allows you to build features that respond to the specific item a customer is viewing or interacting with.

Anchor to Use casesUse cases

Line item details: Display detailed information about the current line item including product details and pricing.
Item-specific actions: Implement actions and workflows based on product type or custom properties.
Contextual UI: Create interfaces that adapt based on line item characteristics.
Discount management: Access line item discounts to create specialized discount display interfaces.

Support

Targets (2)

Supported targets

Anchor to PropertiesProperties

The Cart Line Item API object provides read-only access to a specific line item in the cart. Access the following properties on the API object to get line item details like product information, pricing, discounts, and custom properties.

Anchor to cartLineItem cartLineItem required: The selected line item in the merchant's current cart. Provides complete line item data including product information, pricing, discounts, properties, and metadata. Use for displaying item details and implementing item-specific functionality.

LineItem

Represents an individual item in the shopping cart. Contains product information, pricing, quantity, discounts, and customization details for a single cart entry.

attributedUserId
The staff member 'ID' attributed to this line item. Returns 'undefined' if no staff attribution is set. Use for commission tracking and performance analytics.
```
number
```
components
Bundle components for this line item. Only present for [product bundles](/docs/apps/build/product-merchandising/bundles). Each component represents an individual item within the bundle with its own tax information.
```
LineItemComponent[]
```
discountAllocations
An array of discount allocations applied to this line item, providing detailed breakdown of how discounts are distributed. Returns 'undefined' if no allocations exist. Use for enhanced discount tracking and reporting.
```
DiscountAllocation[]
```
discounts
An array of discounts applied to this line item. Empty array if no discounts are active. Use for displaying line item savings and discount details.
```
Discount[]
```
hasSellingPlanGroups
Determines whether this line item has selling plan groups (subscription options) available. Returns 'undefined' if selling plan information is unavailable. Use for displaying subscription options.
```
boolean
```
isGiftCard
Determines whether this line item is a gift card. Gift cards have special handling requirements and business logic. Use for implementing gift card-specific workflows.
```
boolean
```
price
The unit price of the line item. Returns 'undefined' for custom sales without set prices. Use for pricing calculations and displays.
```
number
```
productId
The product 'ID' this line item represents. Returns 'undefined' for custom sales or non-product items. Use for product-specific operations and linking to product details.
```
number
```
properties
The custom key-value properties attached to this line item. Empty object if no properties are set. Use for metadata, customization options, or integration data.
```
{ [key: string]: string; }
```
quantity
The quantity of this item in the cart. Always a positive integer. Use for quantity displays, calculations, and inventory management.
```
number
```
requiresSellingPlan
Determines whether this line item requires a selling plan (subscription) to be purchased. Returns 'undefined' if selling plan information is unavailable. Use for implementing subscription-based product handling.
```
boolean
```
sellingPlan
The currently selected selling plan for this line item. Returns 'undefined' if no selling plan is applied. Contains selling plan details including 'ID', name, and delivery intervals. Use for subscription management and recurring purchase functionality.
```
SellingPlan
```
sku
The Stock Keeping Unit (SKU) identifier for this line item. Returns 'undefined' if no SKU is configured. Use for inventory tracking and product identification.
```
string
```
taxable
Determines whether this line item is subject to tax calculations. Use for tax computation, compliance, and pricing displays.
```
boolean
```
taxLines
An array of tax lines applied to this line item, containing tax amounts and rates. Use for detailed tax reporting and compliance.
```
TaxLine[]
```
title
The display title of the line item. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification.
```
string
```
uuid
The unique identifier for this line item within the cart. Use for line item-specific operations like updates, removals, or property modifications.
```
string
```
variantId
The product variant 'ID' this line item represents. Returns 'undefined' for custom sales or non-variant items. Use for variant-specific operations and product details.
```
number
```
vendor
The vendor or brand name for this line item. Returns 'undefined' if no vendor is set. Use for vendor-specific displays and organization.
```
string
```

LineItemComponent

Represents a component of a [product bundle](/docs/apps/build/product-merchandising/bundles) line item. Bundle components contain the individual items that make up a bundle, each with their own pricing and tax information.

price
The price for the custom sale item as currency string. Must be a valid positive amount. Use for non-catalog items and custom pricing.
```
number
```
productId
The unique numeric identifier for the product this component represents, if applicable.
```
number
```
quantity
The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management.
```
number
```
taxable
Determines whether the custom sale item is taxable. Set to `true` to apply tax calculations, `false` to exempt from taxes.
```
boolean
```
taxLines
An array of tax lines applied to this component.
```
TaxLine[]
```
title
The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly.
```
string
```
variantId
The unique numeric identifier for the product variant this component represents, if applicable.
```
number
```

TaxLine

Represents a tax line applied to an item or transaction.

enabled
Whether this tax is currently enabled.
```
boolean
```
price
The tax amount as a Money object.
```
Money
```
rate
The tax rate as a decimal number.
```
number
```
rateRange
The range of tax rates if applicable.
```
{ min: number; max: number; }
```
title
The title or name of the tax.
```
string
```
uuid
The unique identifier for this tax line.
```
string
```

Money

Represents a monetary amount with currency information.

amount
The monetary amount as a number.
```
number
```
currency
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
```
string
```

DiscountAllocation

Represents the allocation of a discount to a specific line item.

allocatedAmount
The amount of discount allocated.
```
MoneyV2
```

MoneyV2

Represents a monetary amount as a string with explicit currency code.

amount
The monetary amount as a string.
```
string
```
currencyCode
The ISO currency code (for example, USD, CAD).
```
string
```

Discount

Represents a discount applied to a cart or transaction, including amount and description.

amount
The discount value to apply. For `'Percentage'` type, this represents the percentage value (For example, "10" for 10% off). For `'FixedAmount'` type, this represents the fixed monetary amount to deduct from the line item price. Commonly used for discount calculations and displaying the discount value to merchants.
```
number
```
currency
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
```
string
```
discountDescription
A human-readable description of the discount shown to merchants and customers. This typically includes the discount name, promotion details, or discount code (for example, "SUMMER2024", "10% off entire order", "Buy 2 Get 1 Free"). Returns `undefined` when no description is provided.
```
string
```
type
The [discount type](https://help.shopify.com/en/manual/discounts/discount-types) applied to this line item. Can be either `'Percentage'` for percentage-based discounts or `'FixedAmount'` for fixed monetary amount discounts. This determines how the discount amount is calculated and displayed.
```
string
```

SellingPlan

Represents a selling plan (subscription) associated with a line item, containing delivery schedule and plan identification details.

deliveryInterval
The interval of the selling plan. (DAY, WEEK, MONTH, YEAR).
```
string
```
deliveryIntervalCount
The number of intervals between deliveries.
```
number
```
digest
The fingerprint of the applied selling plan within this cart session. Provided by POS. Not available during refund / exchanges.
```
string
```
id
The unique identifier of the selling plan.
```
number
```
name
The name of the POS device.
```
string
```

Examples

import React from 'react';

import {

Text,

Screen,

ScrollView,

Navigator,

reactExtension,

useApi,

} from '@shopify/ui-extensions-react/point-of-sale';

const Modal = () => {

const api = useApi<'pos.cart.line-item-details.action.render'>();

return (

<Text>{`Cart Line Item ID: ${api.cartLineItem.id}`}</Text>

</ScrollView>

</Screen>

</Navigator>

);

};

export default reactExtension(

'pos.cart.line-item-details.action.render',

() => <Modal />,

);

Examples

Get the current line item ID

Description

Retrieve the unique identifier of the cart line item currently associated with the extension's context. This example shows how to access the line item ID from line item detail screens, enabling you to fetch additional item data, implement custom actions, or track item-specific operations.

React

import React from 'react';

import {
  Text,
  Screen,
  ScrollView,
  Navigator,
  reactExtension,
  useApi,
} from '@shopify/ui-extensions-react/point-of-sale';

const Modal = () => {
  const api = useApi<'pos.cart.line-item-details.action.render'>();
  return (
    <Navigator>
      <Screen name="CartLineItemApi" title="Cart Line Item Api">
        <ScrollView>
          <Text>{`Cart Line Item ID: ${api.cartLineItem.id}`}</Text>
        </ScrollView>
      </Screen>
    </Navigator>
  );
};

export default reactExtension(
  'pos.cart.line-item-details.action.render',
  () => <Modal />,
);

TS

import {
  Navigator,
  Screen,
  ScrollView,
  Text,
  extension,
} from '@shopify/ui-extensions/point-of-sale';

export default extension(
  'pos.cart.line-item-details.action.render',
  (root, api) => {
    const navigator = root.createComponent(Navigator);
    const screen = root.createComponent(Screen, {
      name: 'CartLineItemApi',
      title: 'Cart Line Item Api',
    });
    const scrollView = root.createComponent(ScrollView);
    const text = root.createComponent(Text);

    text.append(`Cart Line Item ID: ${api.cartLineItem.id}`);
    scrollView.append(text);
    screen.append(scrollView);
    navigator.append(screen);
    root.append(navigator);
  },
);

Anchor to Best practicesBest practices

Use line item context effectively: Use the line item data to create contextual experiences—for example, showing different interfaces for gift cards versus regular products, or displaying vendor-specific information.
Implement item-specific validation: Use line item properties like taxable and isGiftCard to implement appropriate validation and business logic for different item types.
Access related data efficiently: Use productId and variantId to fetch additional product information when needed, but avoid unnecessary API calls by using the data already available in the line item.

Anchor to LimitationsLimitations

The API provides read-only access to line item data—use the Cart API for modifying line item properties, discounts, or other attributes.
Line item data reflects the current state and may not include real-time inventory or pricing updates until the cart is refreshed.

Was this page helpful?