--- title: Cart API description: >- 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. The API supports both individual and bulk operations for efficient cart manipulation, with [selling plan functionality](/docs/apps/build/purchase-options/subscriptions/selling-plans) and error handling. api_version: 2025-10 api_name: pos-ui-extensions source_url: html: >- https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/contextual-apis/cart-api md: >- https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/contextual-apis/cart-api.md --- # 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. The API supports both individual and bulk operations for efficient cart manipulation, with [selling plan functionality](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/selling-plans) and error handling. ## CartApi The `CartApi` object provides access to cart management functionality and real-time cart state monitoring. Access these properties through `shopify.cart` to interact with the current POS cart. * addAddress (address: Address) => Promise\ 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. * addCartCodeDiscount (code: string) => Promise\ 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. * addCartProperties (properties: Record\) => Promise\ 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. * addCustomSale (customSale: CustomSale) => Promise\ 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. * addLineItem (variantId: number, quantity: number) => Promise\ 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. * addLineItemProperties (uuid: string, properties: Record\) => Promise\ 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. * addLineItemSellingPlan (input: SetLineItemSellingPlanInput) => Promise\ required Add a selling plan to a line item in the cart using the line item `UUID`, selling plan `ID`, and selling plan name. Optionally provide delivery interval and interval count for improved performance, otherwise POS will fetch them after syncing the cart. * applyCartDiscount (type: CartDiscountType, title: string, amount?: string) => Promise\ 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. * bulkAddLineItemProperties (lineItemProperties: SetLineItemPropertiesInput\[]) => Promise\ 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. * bulkCartUpdate (cartState: CartUpdateInput) => 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. * bulkSetLineItemDiscounts (lineItemDiscounts: SetLineItemDiscountInput\[]) => Promise\ 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. * clearCart () => Promise\ 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. * current ReadonlySignalLike\ required Provides read-only access to the current cart state and allows subscribing to cart changes. The `value` property provides the current cart state, and `subscribe` allows listening to changes with improved performance and memory management. * deleteAddress (addressId: number) => Promise\ 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`. * removeAllDiscounts (disableAutomaticDiscounts: boolean) => Promise\ 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. * removeCartDiscount () => Promise\ required Remove the current cart-level discount. This only affects cart-level discounts and does not impact line item discounts or automatic discount eligibility. * removeCartProperties (keys: string\[]) => Promise\ 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. * removeCustomer () => Promise\ 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. * removeLineItem (uuid: string) => Promise\ 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. * removeLineItemDiscount (uuid: string) => Promise\ 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. * removeLineItemProperties (uuid: string, keys: string\[]) => Promise\ 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. * removeLineItemSellingPlan (uuid: string) => Promise\ required Remove the selling plan from a line item in the cart using the line item `UUID`. This will clear any subscription or recurring purchase configuration from the line item. * setAttributedStaff (staffId: number) => Promise\ 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. * setAttributedStaffToLineItem (staffId: number, lineItemUuid: string) => Promise\ 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. * setCustomer (customer: Customer) => Promise\ 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. * setLineItemDiscount (uuid: string, type: LineItemDiscountType, title: string, amount: string) => Promise\ 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. * updateDefaultAddress (addressId: number) => Promise\ 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. ```ts string ``` * address2 The secondary address line for apartment, suite, or unit information. Optional field for additional address details. ```ts string ``` * city The city name for the address. Required for shipping calculations and location-based services. ```ts string ``` * company The company name associated with the address. Optional field for business customers and B2B transactions. ```ts string ``` * country The country name for the address. Required for international shipping, tax calculations, and compliance. ```ts string ``` * countryCode The standardized country code (ISO format). Use for precise country identification and international shipping operations. ```ts CountryCode ``` * firstName The first name for the address contact. Used for personalized shipping labels and customer communication. ```ts string ``` * lastName The last name for the address contact. Required for complete customer identification and shipping labels. ```ts string ``` * name The full name for the address contact. Use when first and last names are combined or unavailable as separate fields. ```ts string ``` * phone The phone number for the address contact. Used for delivery notifications, shipping updates, and customer communication. ```ts string ``` * province The province or state name for the address. Required for regional shipping rates and tax calculations. ```ts string ``` * provinceCode The standardized province or state code. Use for precise regional identification and automated shipping calculations. ```ts string ``` * zip The postal or ZIP code for the address. Required for accurate shipping rates and location-based services. ```ts string ``` ```ts export interface Address { /** * The primary street address line. Required for most shipping and billing operations. Should contain street number and name. */ address1?: string; /** * The secondary address line for apartment, suite, or unit information. Optional field for additional address details. */ address2?: string; /** * The city name for the address. Required for shipping calculations and location-based services. */ city?: string; /** * The company name associated with the address. Optional field for business customers and B2B transactions. */ company?: string; /** * The first name for the address contact. Used for personalized shipping labels and customer communication. */ firstName?: string; /** * The last name for the address contact. Required for complete customer identification and shipping labels. */ lastName?: string; /** * The phone number for the address contact. Used for delivery notifications, shipping updates, and customer communication. */ phone?: string; /** * The province or state name for the address. Required for regional shipping rates and tax calculations. */ province?: string; /** * The country name for the address. Required for international shipping, tax calculations, and compliance. */ country?: string; /** * The postal or ZIP code for the address. Required for accurate shipping rates and location-based services. */ zip?: string; /** * The full name for the address contact. Use when first and last names are combined or unavailable as separate fields. */ name?: string; /** * The standardized province or state code. Use for precise regional identification and automated shipping calculations. */ provinceCode?: string; /** * The standardized country code (ISO format). Use for precise country identification and international shipping operations. */ countryCode?: CountryCode; } ``` ### CountryCode * AF ```ts AF ``` * AX ```ts AX ``` * AL ```ts AL ``` * DZ ```ts DZ ``` * AD ```ts AD ``` * AO ```ts AO ``` * AI ```ts AI ``` * AG ```ts AG ``` * AR ```ts AR ``` * AM ```ts AM ``` * AW ```ts AW ``` * AC ```ts AC ``` * AU ```ts AU ``` * AT ```ts AT ``` * AZ ```ts AZ ``` * BS ```ts BS ``` * BH ```ts BH ``` * BD ```ts BD ``` * BB ```ts BB ``` * BY ```ts BY ``` * BE ```ts BE ``` * BZ ```ts BZ ``` * BJ ```ts BJ ``` * BM ```ts BM ``` * BT ```ts BT ``` * BO ```ts BO ``` * BA ```ts BA ``` * BW ```ts BW ``` * BV ```ts BV ``` * BR ```ts BR ``` * IO ```ts IO ``` * BN ```ts BN ``` * BG ```ts BG ``` * BF ```ts BF ``` * BI ```ts BI ``` * KH ```ts KH ``` * CA ```ts CA ``` * CV ```ts CV ``` * BQ ```ts BQ ``` * KY ```ts KY ``` * CF ```ts CF ``` * TD ```ts TD ``` * CL ```ts CL ``` * CN ```ts CN ``` * CX ```ts CX ``` * CC ```ts CC ``` * CO ```ts CO ``` * KM ```ts KM ``` * CG ```ts CG ``` * CD ```ts CD ``` * CK ```ts CK ``` * CR ```ts CR ``` * HR ```ts HR ``` * CU ```ts CU ``` * CW ```ts CW ``` * CY ```ts CY ``` * CZ ```ts CZ ``` * CI ```ts CI ``` * DK ```ts DK ``` * DJ ```ts DJ ``` * DM ```ts DM ``` * DO ```ts DO ``` * EC ```ts EC ``` * EG ```ts EG ``` * SV ```ts SV ``` * GQ ```ts GQ ``` * ER ```ts ER ``` * EE ```ts EE ``` * SZ ```ts SZ ``` * ET ```ts ET ``` * FK ```ts FK ``` * FO ```ts FO ``` * FJ ```ts FJ ``` * FI ```ts FI ``` * FR ```ts FR ``` * GF ```ts GF ``` * PF ```ts PF ``` * TF ```ts TF ``` * GA ```ts GA ``` * GM ```ts GM ``` * GE ```ts GE ``` * DE ```ts DE ``` * GH ```ts GH ``` * GI ```ts GI ``` * GR ```ts GR ``` * GL ```ts GL ``` * GD ```ts GD ``` * GP ```ts GP ``` * GT ```ts GT ``` * GG ```ts GG ``` * GN ```ts GN ``` * GW ```ts GW ``` * GY ```ts GY ``` * HT ```ts HT ``` * HM ```ts HM ``` * VA ```ts VA ``` * HN ```ts HN ``` * HK ```ts HK ``` * HU ```ts HU ``` * IS ```ts IS ``` * IN ```ts IN ``` * ID ```ts ID ``` * IR ```ts IR ``` * IQ ```ts IQ ``` * IE ```ts IE ``` * IM ```ts IM ``` * IL ```ts IL ``` * IT ```ts IT ``` * JM ```ts JM ``` * JP ```ts JP ``` * JE ```ts JE ``` * JO ```ts JO ``` * KZ ```ts KZ ``` * KE ```ts KE ``` * KI ```ts KI ``` * KP ```ts KP ``` * XK ```ts XK ``` * KW ```ts KW ``` * KG ```ts KG ``` * LA ```ts LA ``` * LV ```ts LV ``` * LB ```ts LB ``` * LS ```ts LS ``` * LR ```ts LR ``` * LY ```ts LY ``` * LI ```ts LI ``` * LT ```ts LT ``` * LU ```ts LU ``` * MO ```ts MO ``` * MG ```ts MG ``` * MW ```ts MW ``` * MY ```ts MY ``` * MV ```ts MV ``` * ML ```ts ML ``` * MT ```ts MT ``` * MQ ```ts MQ ``` * MR ```ts MR ``` * MU ```ts MU ``` * YT ```ts YT ``` * MX ```ts MX ``` * MD ```ts MD ``` * MC ```ts MC ``` * MN ```ts MN ``` * ME ```ts ME ``` * MS ```ts MS ``` * MA ```ts MA ``` * MZ ```ts MZ ``` * MM ```ts MM ``` * NA ```ts NA ``` * NR ```ts NR ``` * NP ```ts NP ``` * NL ```ts NL ``` * AN ```ts AN ``` * NC ```ts NC ``` * NZ ```ts NZ ``` * NI ```ts NI ``` * NE ```ts NE ``` * NG ```ts NG ``` * NU ```ts NU ``` * NF ```ts NF ``` * MK ```ts MK ``` * NO ```ts NO ``` * OM ```ts OM ``` * PK ```ts PK ``` * PS ```ts PS ``` * PA ```ts PA ``` * PG ```ts PG ``` * PY ```ts PY ``` * PE ```ts PE ``` * PH ```ts PH ``` * PN ```ts PN ``` * PL ```ts PL ``` * PT ```ts PT ``` * QA ```ts QA ``` * CM ```ts CM ``` * RE ```ts RE ``` * RO ```ts RO ``` * RU ```ts RU ``` * RW ```ts RW ``` * BL ```ts BL ``` * SH ```ts SH ``` * KN ```ts KN ``` * LC ```ts LC ``` * MF ```ts MF ``` * PM ```ts PM ``` * WS ```ts WS ``` * SM ```ts SM ``` * ST ```ts ST ``` * SA ```ts SA ``` * SN ```ts SN ``` * RS ```ts RS ``` * SC ```ts SC ``` * SL ```ts SL ``` * SG ```ts SG ``` * SX ```ts SX ``` * SK ```ts SK ``` * SI ```ts SI ``` * SB ```ts SB ``` * SO ```ts SO ``` * ZA ```ts ZA ``` * GS ```ts GS ``` * KR ```ts KR ``` * SS ```ts SS ``` * ES ```ts ES ``` * LK ```ts LK ``` * VC ```ts VC ``` * SD ```ts SD ``` * SR ```ts SR ``` * SJ ```ts SJ ``` * SE ```ts SE ``` * CH ```ts CH ``` * SY ```ts SY ``` * TW ```ts TW ``` * TJ ```ts TJ ``` * TZ ```ts TZ ``` * TH ```ts TH ``` * TL ```ts TL ``` * TG ```ts TG ``` * TK ```ts TK ``` * TO ```ts TO ``` * TT ```ts TT ``` * TA ```ts TA ``` * TN ```ts TN ``` * TR ```ts TR ``` * TM ```ts TM ``` * TC ```ts TC ``` * TV ```ts TV ``` * UG ```ts UG ``` * UA ```ts UA ``` * AE ```ts AE ``` * GB ```ts GB ``` * US ```ts US ``` * UM ```ts UM ``` * UY ```ts UY ``` * UZ ```ts UZ ``` * VU ```ts VU ``` * VE ```ts VE ``` * VN ```ts VN ``` * VG ```ts VG ``` * WF ```ts WF ``` * EH ```ts EH ``` * YE ```ts YE ``` * ZM ```ts ZM ``` * ZW ```ts ZW ``` * ZZ ```ts ZZ ``` ```ts export enum CountryCode { 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. ```ts string ``` * quantity The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management. ```ts number ``` * taxable Determines whether the custom sale item is taxable. Set to \`true\` to apply tax calculations, \`false\` to exempt from taxes. ```ts boolean ``` * title The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. ```ts string ``` ```ts export interface CustomSale { /** * The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management. */ quantity: number; /** * The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. */ title: string; /** * The price for the custom sale item as currency string. Must be a valid positive amount. Use for non-catalog items and custom pricing. */ price: string; /** * Determines whether the custom sale item is taxable. Set to `true` to apply tax calculations, `false` to exempt from taxes. */ taxable: boolean; } ``` ### SetLineItemSellingPlanInput Specifies the parameters for assigning selling plans to line items. Used to add subscription or purchase option configurations to products. * lineItemUuid The target line item \`UUID\` for selling plan assignment. Must match an existing line item in the cart. ```ts string ``` * sellingPlanId The selling plan \`ID\` to apply to the line item. Must be a valid selling plan available for the product. ```ts number ``` * sellingPlanName The selling plan name for display purposes. Required for proper selling plan display in the cart. ```ts string ``` ```ts export interface SetLineItemSellingPlanInput { /** * The target line item `UUID` for selling plan assignment. Must match an existing line item in the cart. */ lineItemUuid: string; /** * The selling plan `ID` to apply to the line item. Must be a valid selling plan available for the product. */ sellingPlanId: number; /** * The selling plan name for display purposes. Required for proper selling plan display in the cart. */ sellingPlanName?: 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. ```ts '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. ```ts string ``` * properties The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. ```ts Record ``` ```ts export interface SetLineItemPropertiesInput { /** * The target line item `UUID` for selling plan assignment. Must match an existing line item in the cart. */ lineItemUuid: string; /** * The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. */ properties: Record; } ``` ### 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. ```ts Discount ``` * cartDiscounts An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array. ```ts Discount[] ``` * customer The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart. ```ts 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. ```ts 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. ```ts string ``` * properties The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. ```ts Record ``` ```ts export interface CartUpdateInput { /** * 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. */ note?: string; /** * The cart-level discount to apply during bulk update. Replaces existing cart discount. Set to `undefined` to remove current discount. */ cartDiscount?: Discount; /** * An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array. */ cartDiscounts: Discount[]; /** * The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart. */ customer?: Customer; /** * An array of line items to set during bulk update. Completely replaces existing cart contents—removes all current items and adds the provided ones. */ lineItems: LineItem[]; /** * The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. */ properties: Record; } ``` ### 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. ```ts number ``` * currency The \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) currency code associated with the location currently active on POS. ```ts 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. ```ts 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. ```ts string ``` ```ts export interface Discount { /** * 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. */ amount: number; /** * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS. */ currency?: string; /** * 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. */ discountDescription?: string; /** * 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. */ type?: 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. ```ts number ``` ```ts export interface Customer { /** * 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. */ id: 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. ```ts 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. ```ts 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. ```ts 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. ```ts 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. ```ts 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. ```ts boolean ``` * price The unit price of the line item. Returns 'undefined' for custom sales without set prices. Use for pricing calculations and displays. ```ts 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. ```ts 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. ```ts { [key: string]: string; } ``` * quantity The quantity of this item in the cart. Always a positive integer. Use for quantity displays, calculations, and inventory management. ```ts 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. ```ts 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. ```ts 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. ```ts string ``` * taxable Determines whether this line item is subject to tax calculations. Use for tax computation, compliance, and pricing displays. ```ts boolean ``` * taxLines An array of tax lines applied to this line item, containing tax amounts and rates. Use for detailed tax reporting and compliance. ```ts TaxLine[] ``` * title The display title of the line item. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification. ```ts string ``` * uuid The unique identifier for this line item within the cart. Use for line item-specific operations like updates, removals, or property modifications. ```ts 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. ```ts 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. ```ts string ``` ```ts export interface LineItem { /** * The unique identifier for this line item within the cart. Use for line item-specific operations like updates, removals, or property modifications. */ uuid: string; /** * The unit price of the line item. Returns 'undefined' for custom sales without set prices. Use for pricing calculations and displays. */ price?: number; /** * The quantity of this item in the cart. Always a positive integer. Use for quantity displays, calculations, and inventory management. */ quantity: number; /** * The display title of the line item. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification. */ title?: string; /** * 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. */ variantId?: number; /** * 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. */ productId?: number; /** * 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. */ discounts: Discount[]; /** * 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. */ discountAllocations?: DiscountAllocation[]; /** * Determines whether this line item is subject to tax calculations. Use for tax computation, compliance, and pricing displays. */ taxable: boolean; /** * An array of tax lines applied to this line item, containing tax amounts and rates. Use for detailed tax reporting and compliance. */ taxLines: TaxLine[]; /** * The Stock Keeping Unit (SKU) identifier for this line item. Returns 'undefined' if no SKU is configured. Use for inventory tracking and product identification. */ sku?: string; /** * The vendor or brand name for this line item. Returns 'undefined' if no vendor is set. Use for vendor-specific displays and organization. */ vendor?: string; /** * 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. */ properties: {[key: string]: string}; /** * 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. */ isGiftCard: boolean; /** * The staff member 'ID' attributed to this line item. Returns 'undefined' if no staff attribution is set. Use for commission tracking and performance analytics. */ attributedUserId?: number; /** * 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. */ requiresSellingPlan?: boolean; /** * 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. */ hasSellingPlanGroups?: boolean; /** * 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?: SellingPlan; /** * 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. */ components?: LineItemComponent[]; } ``` ### 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. ```ts number ``` * productId The unique numeric identifier for the product this component represents, if applicable. ```ts number ``` * quantity The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management. ```ts number ``` * taxable Determines whether the custom sale item is taxable. Set to \`true\` to apply tax calculations, \`false\` to exempt from taxes. ```ts boolean ``` * taxLines An array of tax lines applied to this component. ```ts TaxLine[] ``` * title The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. ```ts string ``` * variantId The unique numeric identifier for the product variant this component represents, if applicable. ```ts number ``` ```ts export interface LineItemComponent { /** * The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. */ title?: string; /** * The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management. */ quantity: number; /** * The price for the custom sale item as currency string. Must be a valid positive amount. Use for non-catalog items and custom pricing. */ price?: number; /** * Determines whether the custom sale item is taxable. Set to `true` to apply tax calculations, `false` to exempt from taxes. */ taxable: boolean; /** * An array of tax lines applied to this component. */ taxLines: TaxLine[]; /** * The unique numeric identifier for the product variant this component represents, if applicable. */ variantId?: number; /** * The unique numeric identifier for the product this component represents, if applicable. */ productId?: number; } ``` ### TaxLine Represents a tax line applied to an item or transaction. * enabled Whether this tax is currently enabled. ```ts boolean ``` * price The tax amount as a Money object. ```ts Money ``` * rate The tax rate as a decimal number. ```ts number ``` * rateRange The range of tax rates if applicable. ```ts { min: number; max: number; } ``` * title The title or name of the tax. ```ts string ``` * uuid The unique identifier for this tax line. ```ts string ``` ```ts export interface TaxLine { /** * The title or name of the tax. */ title: string; /** * The tax amount as a Money object. */ price: Money; /** * The tax rate as a decimal number. */ rate: number; /** * The unique identifier for this tax line. */ uuid?: string; /** * The range of tax rates if applicable. */ rateRange?: {min: number; max: number}; /** * Whether this tax is currently enabled. */ enabled?: boolean; } ``` ### Money Represents a monetary amount with currency information. * amount The monetary amount as a number. ```ts number ``` * currency The \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) currency code associated with the location currently active on POS. ```ts string ``` ```ts export interface Money { /** * The monetary amount as a number. */ amount: number; /** * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS. */ currency: string; } ``` ### DiscountAllocation Represents the allocation of a discount to a specific line item. * allocatedAmount The amount of discount allocated. ```ts MoneyV2 ``` ```ts export interface DiscountAllocation { /** * The amount of discount allocated. */ allocatedAmount: MoneyV2; } ``` ### MoneyV2 Represents a monetary amount as a string with explicit currency code. * amount The monetary amount as a string. ```ts string ``` * currencyCode The ISO currency code (for example, USD, CAD). ```ts string ``` ```ts export interface MoneyV2 { /** * The monetary amount as a string. */ amount: string; /** * The ISO currency code (for example, USD, CAD). */ currencyCode: 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). ```ts string ``` * deliveryIntervalCount The number of intervals between deliveries. ```ts number ``` * digest The fingerprint of the applied selling plan within this cart session. Provided by POS. Not available during refund / exchanges. ```ts string ``` * id The unique identifier of the selling plan. ```ts number ``` * name The name of the POS device. ```ts string ``` ```ts export interface SellingPlan { /** * The unique identifier of the selling plan. */ id: number; /** * The name of the POS device. */ name: string; /** * The fingerprint of the applied selling plan within this cart session. Provided by POS. Not available during refund / exchanges. */ digest?: string; /** * The interval of the selling plan. (DAY, WEEK, MONTH, YEAR). */ deliveryInterval?: string; /** * The number of intervals between deliveries. */ deliveryIntervalCount?: number; } ``` ### 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. ```ts Discount ``` * cartDiscounts An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array. ```ts Discount[] ``` * customer The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart. ```ts 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. ```ts boolean ``` * grandTotal The final total amount including all items, taxes, and discounts, formatted as a currency string. ```ts 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. ```ts 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. ```ts string ``` * properties The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. ```ts Record ``` * subtotal The subtotal amount of the cart before taxes and discounts, formatted as a currency string. ```ts string ``` * taxTotal The total tax amount for the cart, formatted as a currency string. ```ts string ``` ```ts export interface Cart { /** * 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. */ editable?: boolean; /** * The subtotal amount of the cart before taxes and discounts, formatted as a currency string. */ subtotal: string; /** * The total tax amount for the cart, formatted as a currency string. */ taxTotal: string; /** * The final total amount including all items, taxes, and discounts, formatted as a currency string. */ grandTotal: string; /** * 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. */ note?: string; /** * The cart-level discount to apply during bulk update. Replaces existing cart discount. Set to `undefined` to remove current discount. */ cartDiscount?: Discount; /** * An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array. */ cartDiscounts: Discount[]; /** * The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart. */ customer?: Customer; /** * An array of line items to set during bulk update. Completely replaces existing cart contents—removes all current items and adds the provided ones. */ lineItems: LineItem[]; /** * The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values. */ properties: Record; } ``` ### 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. ```ts LineItemDiscount ``` * lineItemUuid The target line item \`UUID\` for selling plan assignment. Must match an existing line item in the cart. ```ts string ``` ```ts export interface SetLineItemDiscountInput { /** * The target line item `UUID` for selling plan assignment. Must match an existing line item in the cart. */ lineItemUuid: string; /** * The discount details to apply to the line item. Contains title, type (`'Percentage'` or `'FixedAmount'`), and amount value. */ lineItemDiscount: LineItemDiscount; } ``` ### LineItemDiscount Represents a discount applied to an individual line item in the cart. * amount The percentage or fixed amount for the discount. ```ts string ``` * title The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. ```ts string ``` * type The discount type. ```ts 'Percentage' | 'FixedAmount' ``` ```ts export interface LineItemDiscount { /** * The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly. */ title: string; /** * The discount type. */ type: 'Percentage' | 'FixedAmount'; /** * The percentage or fixed amount for the discount. */ amount: string; } ``` ### ReadonlySignalLike Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. * subscribe Subscribes to locale changes and calls the provided function whenever the locale updates. Returns an unsubscribe function to clean up the subscription. Use to automatically update your extension content when merchants change their language settings during POS sessions. ```ts (fn: (value: T) => void) => () => void ``` * value The current value of the locale string in IETF format. For example, \`"en-US"\`, \`"fr-CA"\`, or \`"de-DE"\`. This property provides immediate access to the current locale without requiring subscription setup. Use for one-time locale checks or initial internationalization setup. ```ts T ``` ```ts export interface ReadonlySignalLike { /** * The current value of the locale string in IETF format. For example, `"en-US"`, `"fr-CA"`, or `"de-DE"`. This property provides immediate access to the current locale without requiring subscription setup. Use for one-time locale checks or initial internationalization setup. */ readonly value: T; /** * Subscribes to locale changes and calls the provided function whenever the locale updates. Returns an unsubscribe function to clean up the subscription. Use to automatically update your extension content when merchants change their language settings during POS sessions. */ subscribe(fn: (value: T) => void): () => void; } ``` ### LineItemDiscountType Defines the type of discount applied to individual line items. Specifies whether the discount is percentage-based or a fixed amount reduction. ```ts 'Percentage' | 'FixedAmount' ``` ## Best practices * **Handle cart state reactively:** Use the signal-based interface to automatically update your extension UI when cart changes occur. * **Validate operations before execution:** Check cart editability and validate input data before performing cart operations to prevent errors. * **Use bulk operations for efficiency:** When performing multiple related operations, use bulk methods like `bulkCartUpdate`, `bulkSetLineItemDiscounts`, and `bulkAddLineItemProperties` for better performance and reduced API calls. * **Handle errors gracefully:** Implement proper error handling for all cart operations, as they may fail due to inventory constraints, validation errors, oversell protection, or business rule violations. * **Manage selling plans appropriately:** When working with subscription products, validate selling plan compatibility and handle selling plan requirements. ## Limitations Cart operations may fail due to business rules, inventory constraints, oversell protection, or validation errors—always implement appropriate error handling. ## Examples Learn how to manage cart contents, apply discounts, handle customer information, and track cart changes in real time. ### Examples * #### Add a custom sale item to the cart ##### Description Add a custom item to the cart with manual pricing and details. This example demonstrates using \`shopify.cart.addCustomSale()\` to create custom line items for services, fees, or items not in the product catalog. This provides flexibility for unique sales scenarios. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.addCustomSale({ taxable: true, quantity: 1, title: 'T-shirt', price: '10.00', }); }} /> ); }; ``` * #### Add a new address to the customer ##### Description Create a new address for the customer associated with the cart. This example demonstrates using \`shopify.cart.addAddress()\` to add shipping or billing addresses to customer profiles. This simplifies future purchases and enables multiple delivery locations. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.addAddress({ address1: '123 Main St', city: 'Ottawa', province: 'Ontario', zip: 'K1S 5B6', firstName: 'John', lastName: 'Doe', country: 'Canada', phone: '555-1234', }); }} /> ); }; ``` * #### Add a product to the cart ##### Description Add a product variant to the cart with specified quantity and optional properties. This example shows how to use \`shopify.cart.addLineItem()\` to add catalog items to the cart with custom attributes. This enables standard product sales with additional customization. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.addLineItem(12345678, 1); }} /> ); }; ``` * #### Add a subscription selling plan to a line item ##### Description Associate a subscription or selling plan with a line item for recurring purchases. This example shows how to use \`shopify.cart.addLineItemSellingPlan()\` to add selling plans to items. This enables subscription-based sales and recurring revenue models. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.addLineItemSellingPlan({ lineItemUuid: 'aa-1234567', sellingPlanId: 123, sellingPlanName: 'My Exclusive Subscription', }); }} /> ); }; ``` * #### Add custom properties to a line item ##### Description Attach custom metadata to a specific line item for additional product information. This example shows how to use \`shopify.cart.addLineItemProperties()\` to add key-value properties to individual items. This enables customization like engraving text, gift messages, or special instructions. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.addLineItemProperties('aa-1234567', { note: 'Handle with care', request: 'Gift wrap', }); }} /> ); }; ``` * #### Add custom properties to the cart ##### Description Attach custom metadata to the cart for additional order information. This example shows how to use \`shopify.cart.addCartProperties()\` to add key-value properties that persist through checkout. This is useful for tracking order sources, preferences, or workflow data. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.addCartProperties({ note: 'Handle with care', request: 'Gift wrap', }); }} /> ); }; ``` * #### Add properties to multiple line items at once ##### Description Attach custom metadata to multiple line items efficiently in a single operation. This example demonstrates using \`shopify.cart.bulkAddLineItemProperties()\` to add properties to several items simultaneously. This improves performance for batch customization operations. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.bulkAddLineItemProperties([ { lineItemUuid: 'aa-1234567', properties: { note: 'Handle with care', request: 'Gift wrap', }, }, { lineItemUuid: 'bb-7654321', properties: { color: 'Blue', size: 'Medium', }, }, ]); }} /> ); }; ``` * #### Apply a cart-level discount ##### Description Apply a custom discount to the entire cart using a fixed amount or percentage. This example shows how to use \`shopify.cart.applyCartDiscount()\` to add order-level discounts with custom reasons. This is useful for promotions, loyalty rewards, or staff discounts. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.applyCartDiscount('Percentage', 'Summer discount', '10'); }} /> ); }; ``` * #### Apply a discount code to the cart ##### Description Apply a discount code to the cart for automatic discount validation and application. This example demonstrates using \`shopify.cart.applyCodeDiscount()\` to add discount codes that are validated against Shopify discount rules. This enables promotional code redemption with automatic validation. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.addCartCodeDiscount('SUMMER10'); }} /> ); }; ``` * #### Apply a discount to a line item ##### Description Apply a custom discount to a specific line item in the cart. This example demonstrates using \`shopify.cart.setLineItemDiscount()\` to add item-level discounts with custom reasons. This is useful for selective price adjustments or item-specific promotions. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.setLineItemDiscount( 'aa-1234567', 'Percentage', 'Summer discount', '10', ); }} /> ); }; ``` * #### 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. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.applyCartDiscount('Percentage', 'Summer discount', '10'); }} /> ); }; ``` * #### Apply different discounts to multiple line items ##### Description Apply discounts to multiple line items efficiently in a single operation. This example shows how to use \`shopify.cart.bulkSetLineItemDiscounts()\` to add discounts to several items simultaneously. This improves performance for bulk pricing adjustments or category-wide promotions. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.bulkSetLineItemDiscounts([ { lineItemUuid: 'aa-1234567', lineItemDiscount: { type: 'Percentage', title: 'Summer discount', amount: '10', }, }, { lineItemUuid: 'bb-7654321', lineItemDiscount: { type: 'FixedAmount', title: 'Loyalty discount', amount: '5', }, }, ]); }} /> ); }; ``` * #### Associate a customer with the cart ##### Description Assign a customer to the current cart for personalized pricing and order history. This example demonstrates using \`shopify.cart.setCustomer()\` to link a customer by ID. This enables customer-specific discounts, loyalty programs, and order tracking. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.setCustomer({ id: 1, }); }} /> ); }; ``` * #### Attribute a staff member to a line item ##### Description Associate a specific line item with a staff member for item-level commission tracking. This example shows how to use \`shopify.cart.setAttributedStaffToLineItem()\` to assign staff members to individual items. This enables granular sales attribution and performance analysis. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.setAttributedStaffToLineItem(123456, 'aa-1234567'); }} /> ); }; ``` * #### Attribute a staff member to the cart ##### Description Attribute the cart to a staff member for commission tracking and sales attribution. This example demonstrates using \`shopify.cart.setAttributedStaff()\` to assign staff members to sales. This enables performance tracking and commission calculations. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.setAttributedStaff(123456); }} /> ); }; ``` * #### Check if the cart is editable ##### Description Verify whether the cart is in an editable state before attempting modifications. This example demonstrates using \`shopify.cart.editable\` to check if the cart can accept changes. By disabling actions when the cart is locked or in an immutable state, you can prevent errors and improve the user experience. ##### jsx ```jsx import {render} from 'preact'; import {useState, useEffect} from 'preact/hooks'; export default async () => { render(, document.body); }; const Extension = () => { const [isEditable, setIsEditable] = useState( shopify.cart.current.value.editable ?? true ); useEffect(() => { const unsubscribe = shopify.cart.current.subscribe((newCart) => { setIsEditable(newCart.editable ?? true); }); return unsubscribe; }, []); return ( ); }; ``` * #### Clear all items from the cart ##### Description Remove all line items and reset the cart to an empty state. This example shows how to use \`shopify.cart.clear()\` to completely clear the cart. This is useful for starting fresh transactions or implementing cart reset functionality. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.clearCart(); }} /> ); }; ``` * #### Delete a customer address ##### Description Remove a specific address from the customer profile using its unique identifier. This example shows how to use \`shopify.cart.deleteAddress()\` to delete outdated or incorrect addresses. This helps maintain clean customer records. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.deleteAddress(123456); }} /> ); }; ``` * #### Remove a discount from a line item ##### Description Remove a previously applied discount from a specific line item. This example demonstrates using \`shopify.cart.removeLineItemDiscount()\` to clear item-level discounts. This is useful for discount corrections or when promotional conditions are no longer met. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeLineItemDiscount('aa-1234567'); }} /> ); }; ``` * #### 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 shows how to use \`shopify.cart.removeAllDiscounts()\` to reset pricing to base values. This is useful for recalculating totals or canceling promotional offers. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeAllDiscounts(true); }} /> ); }; ``` * #### Remove an item from the cart ##### Description Remove a specific line item from the cart using its unique identifier. This example demonstrates using \`shopify.cart.removeLineItem()\` to delete items. This is useful for implementing remove buttons, cart cleanup, or conditional item removal logic. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeLineItem('aa-1234567'); }} /> ); }; ``` * #### Remove custom properties from a line item ##### Description Delete specific custom properties from a line item by their keys. This example shows how to use \`shopify.cart.removeLineItemProperties()\` to clear item metadata. This is useful for removing temporary customization data or outdated property values. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeLineItemProperties('aa-1234567', ['note']); }} /> ); }; ``` * #### Remove custom properties from the cart ##### Description Delete specific custom properties from the cart by their keys. This example demonstrates using \`shopify.cart.removeCartProperties()\` to clear metadata. This is useful for cleaning up temporary data or removing properties that are no longer needed. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeCartProperties(['note']); }} /> ); }; ``` * #### Remove a subscription plan from a line item ##### Description Remove the selling plan from a line item to convert it back to a one-time purchase. This example demonstrates using \`shopify.cart.removeLineItemSellingPlan()\` to clear subscription plans. This is useful when customers change their mind about recurring orders. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeLineItemSellingPlan('aa-1234567'); }} /> ); }; ``` * #### Remove the customer from the cart ##### Description Disassociate the customer from the current cart for anonymous transactions. This example shows how to use \`shopify.cart.removeCustomer()\` to clear customer information. This reverts to guest checkout pricing and removes customer-specific data from the cart. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeCustomer(); }} /> ); }; ``` * #### Subscribe to real-time cart changes ##### Description Monitor cart state changes in real time using the subscribe method. This example shows how to use \`shopify.cart.subscribe()\` to receive updates whenever the cart changes. This enables reactive UI updates, validation logic, or analytics tracking based on cart modifications. ##### jsx ```jsx import {render} from 'preact'; import {useState, useEffect} from 'preact/hooks'; export default async () => { render(, document.body); }; const Extension = () => { const [lineItemCount, setLineItemCount] = useState( shopify.cart.current.value.lineItems.length ); useEffect(() => { const unsubscribe = shopify.cart.current.subscribe((newCart) => { setLineItemCount(newCart.lineItems.length); }); return unsubscribe; }, []); return ( ); }; ``` * #### Update the default address for the customer ##### Description Designate a specific address as the default for the customer. This example demonstrates using \`shopify.cart.updateDefaultAddress()\` to set the primary shipping or billing address. This simplifies the checkout process for future transactions. ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.updateDefaultAddress(123456); }} /> ); }; ```