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 upgrade guide to upgrade your extension.

Choose a version:

Cart API

The Cart API provides comprehensive access to POS cart management functionality, enabling extensions to read cart state, modify line items, apply discounts, manage customer information, and handle cart properties through a subscribable interface that delivers real-time updates. The API supports both individual and bulk operations for efficient cart manipulation.

Anchor to Use casesUse cases

Real-time monitoring: Monitor cart changes to update extension UI in real-time.
Custom discounts: Apply discounts at cart and line item levels with percentage or fixed amounts.
Product management: Add products programmatically with oversell protection.
Staff attribution: Implement staff attribution to track which team members are responsible for sales.

Support

Targets (16)

Supported targets

Anchor to PropertiesProperties

The Cart API object provides access to cart management functionality and real-time cart state monitoring. Access the following properties on the API object to read cart state, modify line items, apply discounts, manage customer information, and handle cart properties.

Anchor to addAddress addAddress (address: ) => Promise<void> required: Add a new address to the customer associated with the cart. The customer must be present in the cart before adding addresses with enhanced address validation and formatting.
Anchor to addCartCodeDiscount addCartCodeDiscount (code: string) => Promise<void> required: Apply a discount code to the cart. The system will validate the code and apply the appropriate discount if the code is valid and applicable to the current cart contents with improved error messaging.
Anchor to addCartProperties addCartProperties (properties: Record<string, string>) => Promise<void> required: Add custom key-value properties to the cart for storing metadata, tracking information, or integration data. Properties are merged with existing cart properties with enhanced validation and conflict resolution.
Anchor to addCustomSale addCustomSale (customSale: ) => Promise<string> required: Add a custom sale item to the cart with specified quantity, title, price, and taxable status. Returns the UUID of the created line item for future operations and property management.
Anchor to addLineItem addLineItem (variantId: number, quantity: number) => Promise<string> required: Add a product variant to the cart by its numeric ID with the specified quantity. Returns the UUID of the newly added line item, or an empty string if the user dismissed an oversell guard modal. Throws an error if POS fails to add the line item due to validation or system errors.
Anchor to addLineItemProperties addLineItemProperties (uuid: string, properties: Record<string, string>) => Promise<void> required: Add custom properties to a specific line item using its UUID. Properties are merged with existing line item properties for metadata storage and tracking with enhanced validation.
Anchor to applyCartDiscount applyCartDiscount (type: , title: string, amount?: string) => Promise<void> required: Apply a cart-level discount with the specified type ('Percentage', 'FixedAmount', or 'Code'), title, and optional amount. For discount codes, omit the amount parameter. Enhanced validation ensures proper discount application.
Anchor to bulkAddLineItemProperties bulkAddLineItemProperties (lineItemProperties: []) => Promise<void> required: Add properties to multiple line items simultaneously using an array of inputs containing line item UUIDs and their respective properties for efficient bulk operations with enhanced validation and error reporting.
Anchor to bulkCartUpdate bulkCartUpdate (cartState: ) => Promise<> required: Perform a bulk update of the entire cart state including note, discounts, customer, line items, and properties. Returns the updated cart object after the operation completes with enhanced validation and error handling.
Anchor to bulkSetLineItemDiscounts bulkSetLineItemDiscounts (lineItemDiscounts: []) => Promise<void> required: Apply discounts to multiple line items simultaneously. Each input specifies the line item UUID and discount details for efficient bulk discount operations with enhanced validation and allocation tracking.
Anchor to clearCart clearCart () => Promise<void> required: Remove all line items and reset the cart to an empty state. This action can't be undone and will clear all cart contents including line items, discounts, properties, and selling plans.
Anchor to deleteAddress deleteAddress (addressId: number) => Promise<void> required: Delete an existing address from the customer using the address ID. The customer must be present in the cart to perform this operation with improved error handling for invalid address IDs.
Anchor to removeAllDiscounts removeAllDiscounts (disableAutomaticDiscounts: boolean) => Promise<void> required: Remove all discounts from both the cart and individual line items. Set disableAutomaticDiscounts to true to prevent automatic discounts from being reapplied after removal with enhanced discount allocation handling.
Anchor to removeCartDiscount removeCartDiscount () => Promise<void> required: Remove the current cart-level discount. This only affects cart-level discounts and does not impact line item discounts or automatic discount eligibility.
Anchor to removeCartProperties removeCartProperties (keys: string[]) => Promise<void> required: Remove specific cart properties by their keys. Only the specified property keys will be removed while other properties remain intact with improved error handling for non-existent keys.
Anchor to removeCustomer removeCustomer () => Promise<void> required: Remove the currently associated customer from the cart, converting it back to a guest cart without customer-specific benefits or information while preserving cart contents.
Anchor to removeLineItem removeLineItem (uuid: string) => Promise<void> required: Remove a specific line item from the cart using its UUID. The line item will be completely removed from the cart along with any associated discounts, properties, or selling plans.
Anchor to removeLineItemDiscount removeLineItemDiscount (uuid: string) => Promise<void> required: Remove all discounts from a specific line item identified by its UUID. This will clear any custom discounts applied to the line item while preserving discount allocation history.
Anchor to removeLineItemProperties removeLineItemProperties (uuid: string, keys: string[]) => Promise<void> required: Remove specific properties from a line item by UUID and property keys. Only the specified keys will be removed while other properties remain intact with improved error handling.
Anchor to setAttributedStaff setAttributedStaff (staffId: number) => Promise<void> required: Set the attributed staff member for all line items in the cart using the staff ID. Pass undefined to clear staff attribution from all line items with enhanced staff validation and tracking.
Anchor to setAttributedStaffToLineItem setAttributedStaffToLineItem (staffId: number, lineItemUuid: string) => Promise<void> required: Set the attributed staff member for a specific line item using the staff ID and line item UUID. Pass undefined as staffId to clear attribution from the line item with improved validation and error handling.
Anchor to setCustomer setCustomer (customer: ) => Promise<void> required: Associate a customer with the current cart using the customer object containing the customer ID. This enables customer-specific pricing, discounts, and checkout features with enhanced customer data validation.
Anchor to setLineItemDiscount setLineItemDiscount (uuid: string, type: , title: string, amount: string) => Promise<void> required: Apply a discount to a specific line item using its UUID. Specify the discount type ('Percentage' or 'FixedAmount'), title, and amount value with improved discount allocation tracking.
Anchor to subscribable subscribable RemoteSubscribable<> required: Subscribes to real-time cart state changes. Provides initial cart value and triggers callbacks on updates. Supports only one active subscription—use makeStatefulSubscribable for multiple subscribers.
Anchor to updateDefaultAddress updateDefaultAddress (addressId: number) => Promise<void> required: Set a specific address as the default address for the customer using the address ID. The customer must be present in the cart to update the default address with enhanced validation.

Address

Represents physical address information for customer shipping and billing. Contains standard address fields including street, city, region, postal code, and country data.

address1
The primary street address line. Required for most shipping and billing operations. Should contain street number and name.
```
string
```
address2
The secondary address line for apartment, suite, or unit information. Optional field for additional address details.
```
string
```
city
The city name for the address. Required for shipping calculations and location-based services.
```
string
```
company
The company name associated with the address. Optional field for business customers and B2B transactions.
```
string
```
country
The country name for the address. Required for international shipping, tax calculations, and compliance.
```
string
```
countryCode
The standardized country code (ISO format). Use for precise country identification and international shipping operations.
```
CountryCode
```
firstName
The first name for the address contact. Used for personalized shipping labels and customer communication.
```
string
```
lastName
The last name for the address contact. Required for complete customer identification and shipping labels.
```
string
```
name
The full name for the address contact. Use when first and last names are combined or unavailable as separate fields.
```
string
```
phone
The phone number for the address contact. Used for delivery notifications, shipping updates, and customer communication.
```
string
```
province
The province or state name for the address. Required for regional shipping rates and tax calculations.
```
string
```
provinceCode
The standardized province or state code. Use for precise regional identification and automated shipping calculations.
```
string
```
zip
The postal or ZIP code for the address. Required for accurate shipping rates and location-based services.
```
string
```

CountryCode

The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes representing all countries and territories. These standard codes are used for addresses, shipping destinations, tax jurisdictions, and regional settings.

AF
```
AF
```
AX
```
AX
```
AL
```
AL
```
DZ
```
DZ
```
AD
```
AD
```
AO
```
AO
```
AI
```
AI
```
AG
```
AG
```
AR
```
AR
```
AM
```
AM
```
AW
```
AW
```
AC
```
AC
```
AU
```
AU
```
AT
```
AT
```
AZ
```
AZ
```
BS
```
BS
```
BH
```
BH
```
BD
```
BD
```
BB
```
BB
```
BY
```
BY
```
BE
```
BE
```
BZ
```
BZ
```
BJ
```
BJ
```
BM
```
BM
```
BT
```
BT
```
BO
```
BO
```
BA
```
BA
```
BW
```
BW
```
BV
```
BV
```
BR
```
BR
```
IO
```
IO
```
BN
```
BN
```
BG
```
BG
```
BF
```
BF
```
BI
```
BI
```
KH
```
KH
```
CA
```
CA
```
CV
```
CV
```
BQ
```
BQ
```
KY
```
KY
```
CF
```
CF
```
TD
```
TD
```
CL
```
CL
```
CN
```
CN
```
CX
```
CX
```
CC
```
CC
```
CO
```
CO
```
KM
```
KM
```
CG
```
CG
```
CD
```
CD
```
CK
```
CK
```
CR
```
CR
```
HR
```
HR
```
CU
```
CU
```
CW
```
CW
```
CY
```
CY
```
CZ
```
CZ
```
CI
```
CI
```
DK
```
DK
```
DJ
```
DJ
```
DM
```
DM
```
DO
```
DO
```
EC
```
EC
```
EG
```
EG
```
SV
```
SV
```
GQ
```
GQ
```
ER
```
ER
```
EE
```
EE
```
SZ
```
SZ
```
ET
```
ET
```
FK
```
FK
```
FO
```
FO
```
FJ
```
FJ
```
FI
```
FI
```
FR
```
FR
```
GF
```
GF
```
PF
```
PF
```
TF
```
TF
```
GA
```
GA
```
GM
```
GM
```
GE
```
GE
```
DE
```
DE
```
GH
```
GH
```
GI
```
GI
```
GR
```
GR
```
GL
```
GL
```
GD
```
GD
```
GP
```
GP
```
GT
```
GT
```
GG
```
GG
```
GN
```
GN
```
GW
```
GW
```
GY
```
GY
```
HT
```
HT
```
HM
```
HM
```
VA
```
VA
```
HN
```
HN
```
HK
```
HK
```
HU
```
HU
```
IS
```
IS
```
IN
```
IN
```
ID
```
ID
```
IR
```
IR
```
IQ
```
IQ
```
IE
```
IE
```
IM
```
IM
```
IL
```
IL
```
IT
```
IT
```
JM
```
JM
```
JP
```
JP
```
JE
```
JE
```
JO
```
JO
```
KZ
```
KZ
```
KE
```
KE
```
KI
```
KI
```
KP
```
KP
```
XK
```
XK
```
KW
```
KW
```
KG
```
KG
```
LA
```
LA
```
LV
```
LV
```
LB
```
LB
```
LS
```
LS
```
LR
```
LR
```
LY
```
LY
```
LI
```
LI
```
LT
```
LT
```
LU
```
LU
```
MO
```
MO
```
MG
```
MG
```
MW
```
MW
```
MY
```
MY
```
MV
```
MV
```
ML
```
ML
```
MT
```
MT
```
MQ
```
MQ
```
MR
```
MR
```
MU
```
MU
```
YT
```
YT
```
MX
```
MX
```
MD
```
MD
```
MC
```
MC
```
MN
```
MN
```
ME
```
ME
```
MS
```
MS
```
MA
```
MA
```
MZ
```
MZ
```
MM
```
MM
```
NA
```
NA
```
NR
```
NR
```
NP
```
NP
```
NL
```
NL
```
AN
```
AN
```
NC
```
NC
```
NZ
```
NZ
```
NI
```
NI
```
NE
```
NE
```
NG
```
NG
```
NU
```
NU
```
NF
```
NF
```
MK
```
MK
```
NO
```
NO
```
OM
```
OM
```
PK
```
PK
```
PS
```
PS
```
PA
```
PA
```
PG
```
PG
```
PY
```
PY
```
PE
```
PE
```
PH
```
PH
```
PN
```
PN
```
PL
```
PL
```
PT
```
PT
```
QA
```
QA
```
CM
```
CM
```
RE
```
RE
```
RO
```
RO
```
RU
```
RU
```
RW
```
RW
```
BL
```
BL
```
SH
```
SH
```
KN
```
KN
```
LC
```
LC
```
MF
```
MF
```
PM
```
PM
```
WS
```
WS
```
SM
```
SM
```
ST
```
ST
```
SA
```
SA
```
SN
```
SN
```
RS
```
RS
```
SC
```
SC
```
SL
```
SL
```
SG
```
SG
```
SX
```
SX
```
SK
```
SK
```
SI
```
SI
```
SB
```
SB
```
SO
```
SO
```
ZA
```
ZA
```
GS
```
GS
```
KR
```
KR
```
SS
```
SS
```
ES
```
ES
```
LK
```
LK
```
VC
```
VC
```
SD
```
SD
```
SR
```
SR
```
SJ
```
SJ
```
SE
```
SE
```
CH
```
CH
```
SY
```
SY
```
TW
```
TW
```
TJ
```
TJ
```
TZ
```
TZ
```
TH
```
TH
```
TL
```
TL
```
TG
```
TG
```
TK
```
TK
```
TO
```
TO
```
TT
```
TT
```
TA
```
TA
```
TN
```
TN
```
TR
```
TR
```
TM
```
TM
```
TC
```
TC
```
TV
```
TV
```
UG
```
UG
```
UA
```
UA
```
AE
```
AE
```
GB
```
GB
```
US
```
US
```
UM
```
UM
```
UY
```
UY
```
UZ
```
UZ
```
VU
```
VU
```
VE
```
VE
```
VN
```
VN
```
VG
```
VG
```
WF
```
WF
```
EH
```
EH
```
YE
```
YE
```
ZM
```
ZM
```
ZW
```
ZW
```
ZZ
```
ZZ
```

CustomSale

Represents a custom sale item that is not associated with a product in the catalog. Includes pricing, taxation, and descriptive information for manually created line items.

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.
```
string
```
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
```
title
The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly.
```
string
```

CartDiscountType

Defines the type of discount applied at the cart level. Specifies whether the discount is percentage-based, fixed amount, or discount code redemption.

'Percentage' | 'FixedAmount' | 'Code'

SetLineItemPropertiesInput

Specifies the parameters for adding custom properties to line items. Properties are key-value pairs used for storing metadata, tracking information, or integration data.

lineItemUuid
The target line item `UUID` for selling plan assignment. Must match an existing line item in the cart.
```
string
```
properties
The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values.
```
Record<string, string>
```

CartUpdateInput

Specifies the parameters for updating cart information. Includes options for modifying customer data, notes, references, and other cart-level metadata.

cartDiscount
The cart-level discount to apply during bulk update. Replaces existing cart discount. Set to `undefined` to remove current discount.
```
Discount
```
cartDiscounts
An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array.
```
Discount[]
```
customer
The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart.
```
Customer
```
lineItems
An array of line items to set during bulk update. Completely replaces existing cart contents—removes all current items and adds the provided ones.
```
LineItem[]
```
note
The cart note to set during bulk update. Replaces existing note or sets new note if none exists. Set to `undefined` to remove current note.
```
string
```
properties
The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values.
```
Record<string, 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
```

Customer

Represents basic customer identification information. Contains the customer ID for linking to detailed customer data and enabling customer-specific features.

id
The unique numeric identifier for the customer in Shopify's system. This ID is consistent across all Shopify systems and APIs. Used to link this customer reference to the full customer record with complete profile information. Commonly used for customer lookups, applying customer-specific pricing or discounts, linking orders to customer accounts, or integrating with customer management systems.
```
number
```

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

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

Cart

Represents the shopping cart state, including line items, pricing, customer information, and applied discounts. Provides comprehensive access to all cart data and operations.

cartDiscount
The cart-level discount to apply during bulk update. Replaces existing cart discount. Set to `undefined` to remove current discount.
```
Discount
```
cartDiscounts
An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array.
```
Discount[]
```
customer
The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart.
```
Customer
```
editable
Indicates whether the cart is currently editable. An `undefined` value should be treated as `true` for backward compatibility. Use this to determine if cart modification operations are allowed.
```
boolean
```
grandTotal
The final total amount including all items, taxes, and discounts, formatted as a currency string.
```
string
```
lineItems
An array of line items to set during bulk update. Completely replaces existing cart contents—removes all current items and adds the provided ones.
```
LineItem[]
```
note
The cart note to set during bulk update. Replaces existing note or sets new note if none exists. Set to `undefined` to remove current note.
```
string
```
properties
The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values.
```
Record<string, string>
```
subtotal
The subtotal amount of the cart before taxes and discounts, formatted as a currency string.
```
string
```
taxTotal
The total tax amount for the cart, formatted as a currency string.
```
string
```

SetLineItemDiscountInput

Specifies the parameters for applying discounts to individual line items. Includes the discount type, value, and reason for audit and reporting purposes.

lineItemDiscount
The discount details to apply to the line item. Contains title, type (`'Percentage'` or `'FixedAmount'`), and amount value.
```
LineItemDiscount
```
lineItemUuid
The target line item `UUID` for selling plan assignment. Must match an existing line item in the cart.
```
string
```

LineItemDiscount

Represents a discount applied to an individual line item in the cart.

amount
The percentage or fixed amount for the discount.
```
string
```
title
The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly.
```
string
```
type
The discount type.
```
'Percentage' | 'FixedAmount'
```

LineItemDiscountType

Defines the type of discount applied to individual line items. Specifies whether the discount is percentage-based or a fixed amount reduction.

'Percentage' | 'FixedAmount'

Examples

import React from 'react';

import {

reactExtension,

useApi,

Tile

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

const SmartGridTile = () => {

const api = useApi<'pos.home.tile.render'>();

return (

<Tile

title='My App'

subtitle='Call cart function'

enabled

onPress={() => api.cart.addCustomSale({

title: 'New product',

quantity: 1,

price: '10.00',

taxable: true,

})}

);

};

export default reactExtension(

'pos.home.tile.render',

() => <SmartGridTile />

);

Examples

Add a custom sale item to the cart

Description

Create and add a custom sale item that isn't tied to an existing product in your catalog. This example demonstrates using `addCustomSale()` to add a line item with a custom title, quantity, price, and tax settings—useful for services, custom orders, or special charges.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.addCustomSale({
        title: 'New product',
        quantity: 1,
        price: '10.00',
        taxable: true,
      })}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.addCustomSale({
        title: 'New product',
        quantity: 1,
        price: '10.00',
        taxable: true,
      });
    },
  });

  root.append(tile);
});

Add a new address to the customer

Description

Create and add a new address to the customer associated with the cart. This example shows how to use `addAddress()` to add a complete address with street, city, province, name, and country information to the customer's profile for shipping or billing purposes.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.addAddress({
        address1: '123456 Main Street', 
        city: 'Ottawa', 
        province: 'Ontario',
        firstName: 'John',
        lastName: 'Doe',
        country: 'Canada'
      })}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.addAddress({
        address1: '123456 Main Street',
        city: 'Ottawa',
        province: 'Ontario',
        firstName: 'John',
        lastName: 'Doe',
        country: 'Canada',
      });
    },
  });

  root.append(tile);
});

Add a product to the cart

Description

Add a product to the cart by specifying its variant ID and quantity. This example uses `addLineItem()` to add a product variant with the specified quantity, returning the new line item's UUID for future reference or manipulation.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.addLineItem(12345678, 1)}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.addLineItem(12345678, 1);
    },
  });

  root.append(tile);
});

Add custom properties to a line item

Description

Attach custom key-value metadata to a specific line item using its UUID. This example uses `addLineItemProperties()` to add an `'Engraving'` property to a particular line item, useful for storing item-specific customizations, notes, or tracking data.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.addLineItemProperties('aa-1234567', {Engraving: 'John Doe', _internalRef: 'req_1042'})}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.addLineItemProperties('aa-1234567', {Engraving: 'John Doe', _internalRef: 'req_1042'});
    },
  });

  root.append(tile);
});

Add custom properties to multiple line items

Description

Attach different custom properties to multiple line items simultaneously in a single operation. This example shows how to use `bulkAddLineItemProperties()` to efficiently add unique engraving text to multiple items at once, reducing API calls and improving performance.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.bulkAddLineItemProperties([
        {lineItemUuid: 'aa-1234567', properties: {Engraving: 'John Doe'}},
        {lineItemUuid: 'bb-001234567', properties: {Engraving: 'Jane Doe'}}
      ])}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.bulkAddLineItemProperties([
        {lineItemUuid: 'aa-1234567', properties: {Engraving: 'John Doe'}},
        {lineItemUuid: 'bb-001234567', properties: {Engraving: 'Jane Doe'}},
      ]);
    },
  });

  root.append(tile);
});

Add custom properties to the cart

Description

Attach custom key-value metadata to the cart for tracking, integrations, or additional context. This example uses `addCartProperties()` to add an `'Engraving'` property to the cart, which merges with existing properties and overwrites duplicate keys.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.addCartProperties({Engraving: 'John Doe', _internalRef: 'req_1042'})}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart action',
    enabled: true,
    onPress: () => {
      api.cart.addCartProperties({Engraving: 'John Doe', _internalRef: 'req_1042'});
    },
  });

  root.append(tile);
});

Apply a discount code to the cart

Description

Add a discount to the cart using a discount code. This example shows how to apply the discount code `'SUMMER_2024'` using the `addCartCodeDiscount()` method, which validates and applies the code server-side if it's valid and applicable to the current cart.

React

import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.addCartCodeDiscount('SUMMER_2024')} 
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.addCartCodeDiscount('SUMMER_2024');
    },
  });

  root.append(tile);
});

Apply a discount to a line item

Description

Add a discount to an individual line item in the cart using its UUID. This example applies a 10% discount titled `'Summer discount'` to a specific line item using the `setLineItemDiscount()` method, allowing you to target discounts at particular products.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.setLineItemDiscount('aa-1234567', 'Percentage', 'Summer discount', '10')}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.setLineItemDiscount(
        'aa-1234567',
        'Percentage',
        'Summer discount',
        '10',
      );
    },
  });

  root.append(tile);
});

Apply a percentage discount to the cart

Description

Add a cart-level discount that applies to the total cart value. This example demonstrates applying a 10% discount titled `'Summer discount'` to the cart using the `applyCartDiscount()` method with the `Percentage` discount type.

React

import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.applyCartDiscount('Percentage', 'Summer discount', '10')}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.applyCartDiscount('Percentage', 'Summer discount', '10');
    },
  });

  root.append(tile);
});

Apply different discounts to multiple line items

Description

Add discounts to multiple line items simultaneously using a single operation. This example shows how to use `bulkSetLineItemDiscounts()` to apply different discount types and amounts to multiple items efficiently—one gets a 10% percentage discount while another receives a $15 fixed amount discount.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.bulkSetLineItemDiscounts([
        {
          lineItemUuid: 'aa-1234567',
          lineItemDiscount: {
            title: 'Summer 2024',
            amount: '10',
            type: 'Percentage',
          },
        },
        {
          lineItemUuid: 'bb-1234567',
          lineItemDiscount: {
            title: 'Shorts sale',
            amount: '15',
            type: 'FixedAmount',
          },
        },
      ])}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.bulkSetLineItemDiscounts([
        {
          lineItemUuid: 'aa-1234567',
          lineItemDiscount: {
            title: 'Summer 2024',
            amount: '10',
            type: 'Percentage',
          },
        },
        {
          lineItemUuid: 'bb-1234567',
          lineItemDiscount: {
            title: 'Shorts sale',
            amount: '15',
            type: 'FixedAmount',
          },
        },
      ]);
    },
  });

  root.append(tile);
});

Associate a customer with the cart

Description

Associate a customer with the cart using their ID to enable customer-specific features. This example shows how to use `setCustomer()` to associate a customer, which enables personalized pricing, applicable discounts, loyalty benefits, and streamlines the checkout process.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.setCustomer({
        id: 1,
      })}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.setCustomer({
        id: 1,
      });
    },
  });

  root.append(tile);
});

Attribute a staff member to a line item

Description

Assign a staff member to an individual line item for detailed sales tracking. This example demonstrates using `setAttributedStaffToLineItem()` to track which staff member was responsible for selling a specific item, enabling item-level commission tracking and performance analysis.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.setAttributedStaffToLineItem(123456, 'aa-1234567')}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.setAttributedStaffToLineItem(123456, 'aa-1234567');
    },
  });

  root.append(tile);
});

Attribute a staff member to the cart

Description

Assign a staff member to the cart for sales tracking and commission purposes. This example uses `setAttributedStaff()` with a staff member ID to track who facilitated or managed the sale, useful for performance metrics and incentive calculations.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.setAttributedStaff(123456)}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.setAttributedStaff(123456);
    },
  });

  root.append(tile);
});

Check if the cart is editable

Description

Check whether the cart can be modified before attempting cart operations. This example demonstrates using `cart.editable` to verify editability, preventing errors from operations attempted on locked or finalized carts during payment processing or order completion.

React

import React from 'react';
import {
  reactExtension,
  Tile,
  useApi,
  useCartEditable,
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const editable = useCartEditable();

  return <Tile title="My App" enabled={editable} />;
};

export default reactExtension('pos.home.tile.render', () => <SmartGridTile />);

TS

import {Cart, Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    enabled: api.cart.subscribable.initial.editable ?? true,
  });

  api.cart.subscribable.subscribe((newCart: Cart) => {
    tile.updateProps({
      enabled: newCart.editable ?? true
    });
  });

  root.append(tile);
});

Clear all items from the cart

Description

Empty the cart completely, removing all line items, discounts, and properties. This example uses `clearCart()` to reset the cart to its initial empty state while preserving the customer association if present, useful for starting a new transaction or canceling a sale.

React

import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.clearCart()}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.clearCart();
    },
  });

  root.append(tile);
});

Delete a customer address

Description

Remove a specific address from the customer's profile using its ID. This example demonstrates using `deleteAddress()` to permanently delete an address from the customer associated with the cart, useful for cleaning up outdated or incorrect addresses.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.deleteAddress(123456)}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.deleteAddress(123456);
    },
  });

  root.append(tile);
});

Monitor cart updates in real time

Description

Subscribe to cart state changes to display dynamic information based on cart contents. This example shows how to react to cart updates and display the current number of line items in the cart, automatically updating the tile subtitle whenever the cart changes.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile,
  useCartSubscription
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const cart = useCartSubscription();

  return (
    <Tile 
      title='My App' 
      subtitle={`${cart.lineItems.length} line items in cart`} 
      enabled
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Cart, Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: `${api.cart.subscribable.initial.lineItems.length} line items in cart`,
    enabled: true,
  });

  api.cart.subscribable.subscribe((newCart: Cart) => {
    tile.updateProps({
      subtitle: `${newCart.lineItems.length > 0} line items in cart`,
    });
  });

  root.append(tile);
});

Remove a discount from a line item

Description

Clear the discount from an individual line item while leaving other cart discounts intact. This example uses `removeLineItemDiscount()` with the line item's UUID to remove only that item's discount without affecting cart-level or other line item discounts.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.removeLineItemDiscount('aa-1234567')}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.removeLineItemDiscount('aa-1234567');
    },
  });

  root.append(tile);
});

Remove a line item from the cart

Description

Delete a line item from the cart using its UUID. This example demonstrates using `removeLineItem()` to completely remove a specific item along with any associated discounts or properties, without affecting other cart contents.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.removeLineItem('aa-1234567')}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.removeLineItem('aa-1234567');
    },
  });

  root.append(tile);
});

Remove all discounts from cart and line items

Description

Clear all discounts applied to both the cart and individual line items in a single operation. This example uses `removeAllDiscounts(true)` to remove all discounts and disable automatic discounts from being reapplied, giving you full control over the cart's discount state.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.removeAllDiscounts(true)}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.removeAllDiscounts(true);
    },
  });

  root.append(tile);
});

Remove custom properties from a line item

Description

Delete specific properties from a line item by its UUID and property keys. This example demonstrates using `removeLineItemProperties()` to remove the `'Engraving'` property from a specific line item while preserving other line item properties and data.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.removeLineItemProperties('aa-1234567', ['Engraving'])}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.removeLineItemProperties('aa-1234567', ['Engraving']);
    },
  });

  root.append(tile);
});

Remove custom properties from the cart

Description

Delete specific cart properties by their keys while leaving other properties intact. This example demonstrates using `removeCartProperties()` to remove the `'Engraving'` property from the cart without affecting other custom properties or cart data.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.removeCartProperties(['Engraving'])}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.removeCartProperties(['Engraving']);
    },
  });

  root.append(tile);
});

Remove the customer from the cart

Description

Disassociate the customer from the cart and convert it to a guest cart. This example uses `removeCustomer()` to remove customer-specific pricing, discounts, and personalization while preserving all cart contents and line items.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.removeCustomer()}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.removeCustomer();
    },
  });

  root.append(tile);
});

Set a customer's default address

Description

Update which address is marked as the default for the customer in the cart. This example uses `updateDefaultAddress()` with an address ID to set the customer's primary address, which will be automatically selected for future transactions.

React


import React from 'react';
import {
  reactExtension,
  useApi,
  Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
  const api = useApi<'pos.home.tile.render'>();

  return (
    <Tile 
      title='My App' 
      subtitle='Call cart function' 
      enabled 
      onPress={() => api.cart.updateDefaultAddress(123456)}
    />
  );
};

export default reactExtension(
  'pos.home.tile.render',
  () => <SmartGridTile />
);

TS

import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';

export default extension('pos.home.tile.render', (root, api) => {
  const tile = root.createComponent(Tile, {
    title: 'My App',
    subtitle: 'Call cart function',
    enabled: true,
    onPress: () => {
      api.cart.updateDefaultAddress(123456);
    },
  });

  root.append(tile);
});

Anchor to Private propertiesPrivate properties

Prefix a property key with an underscore to hide it from POS. Any key starting with _, whether it's set with addLineItemProperties, bulkAddLineItemProperties, or addCartProperties, is hidden from every POS surface: the cart and checkout screens, the customer view that the buyer sees, printed and emailed receipts, and order and draft order details.

The underscore convention comes from the Ajax API. However, in POS, a __ prefix carries no extra meaning, so a key named __bookingId is hidden exactly as _bookingId is.

The value is still written to the order, and it stays visible in the Shopify admin, the GraphQL Admin API, and order webhooks. In Liquid, a private line item property is readable through line_item.properties, and a private cart property through order.attributes. Your extension also reads it back in full through api.cart.subscribable, and removes it by key with removeLineItemProperties or removeCartProperties.

Caution

Don't put sensitive data in a private property. Use it to keep internal data out of a staff member's and a buyer's way, not to keep that data confidential.

POS writes private properties of its own, so namespace your keys to avoid a collision. Keys beginning with _shopify are reserved, and a key like _myapp_bookingId is safe.

Anchor to Best practicesBest practices

Validate operations before execution: Check cart editability and validate input data before performing cart operations to prevent errors and provide appropriate user feedback.
Use bulk operations for efficiency: When performing multiple related operations, use bulk methods like bulkCartUpdate, bulkSetLineItemDiscounts, and bulkAddLineItemProperties for better performance.
Handle errors gracefully: Implement proper error handling for all cart operations, as they may fail due to inventory constraints, validation errors, or business rule violations.

Anchor to LimitationsLimitations

RemoteSubscribable supports only one subscription at a time. Use makeStatefulSubscribable if you need multiple components to subscribe to cart events simultaneously.
Cart operations may fail due to business rules, inventory constraints, or validation errors—always implement appropriate error handling.
Some operations require specific preconditions. For example, customer must be present for address operations.

Was this page helpful?