--- 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 through a subscribable interface that delivers real-time updates. The API supports both individual and bulk operations for efficient cart manipulation. api_version: 2024-07 api_name: pos-ui-extensions source_url: html: >- https://shopify.dev/docs/api/pos-ui-extensions/2024-07/target-apis/contextual-apis/cart-api md: >- https://shopify.dev/docs/api/pos-ui-extensions/2024-07/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 through a subscribable interface that delivers real-time updates. The API supports both individual and bulk operations for efficient cart manipulation. #### Use 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 (10) ### Supported targets * [pos.​customer-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/customer-details#customer-details-action-menu-item-) * [pos.​customer-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/customer-details#customer-details-action-modal-) * [pos.​draft-order-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/draft-order-details#draft-order-details-action-menu-item-) * [pos.​draft-order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/draft-order-details#draft-order-details-action-modal-) * [pos.​home.​modal.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/home-screen#home-screen-action-modal-) * [pos.​home.​tile.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/home-screen#home-screen-tile-) * [pos.​order-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/order-details#order-details-action-menu-item-) * [pos.​order-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/order-details#order-details-action-modal-) * [pos.​product-details.​action.​menu-item.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/product-details#product-details-action-menu-item-) * [pos.​product-details.​action.​render](https://shopify.dev/docs/api/pos-ui-extensions/2024-07/targets/product-details#product-details-action-modal-) ## CartApi The `CartApi` object provides access to cart management methods and subscribable cart state. Access these methods through `api.cart` to build cart-aware extensions that respond to real-time cart updates. * 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. * 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. * 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. * addCustomSale (customSale: CustomSale) => Promise\ required Add a custom sale item to the cart with specified quantity, title, price, and taxable status. * addLineItem (variantId: number, quantity: number) => Promise\ required Add a product variant to the cart by its numeric `ID` with the specified quantity. * addLineItemProperties (uuid: string, properties: Record\) => Promise\ required Add custom properties to a specific line item using its [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). Properties are merged with existing line item properties for metadata storage and tracking. * 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](https://en.wikipedia.org/wiki/Universally_unique_identifier) and their respective properties for efficient bulk operations. * 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. * 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. * 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. * 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. * removeCartDiscount () => Promise\ required Remove the current cart-level discount. This only affects cart-level discounts and doesn't 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. * 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](https://en.wikipedia.org/wiki/Universally_unique_identifier). 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. * 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. * 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. * 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 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](https://en.wikipedia.org/wiki/Universally_unique_identifier). Specify the discount type (`'Percentage'` or `'FixedAmount'`), title, and amount value. * 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. * 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. ### 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 containing the street number and name (for example, "123 Main Street", "456 Oak Avenue"). This is the first line of the mailing address and is typically required for shipping and billing operations. Returns \`undefined\` when not provided or not applicable. Commonly used for displaying addresses, calculating shipping rates based on location, validating address completeness, or sending to shipping carriers for label generation. ```ts string ``` * address2 The secondary address line for additional location details like apartment number, suite, unit, floor, or building information (for example, "Apt 4B", "Suite 200", "Floor 3"). This field is optional and supplements the primary address line. Returns \`undefined\` when not provided. Commonly used for complete address display, ensuring deliveries reach the correct destination in multi-unit buildings, or providing detailed shipping instructions. ```ts string ``` * city The city or locality name for the address (for example, "New York", "Toronto", "London"). Required for most shipping and billing operations as it's needed for calculating shipping zones, determining tax jurisdictions, and routing deliveries. Returns \`undefined\` when not provided. Commonly used for address display, shipping rate calculations based on destination city, tax determination, or filtering addresses by location. ```ts string ``` * company The company or business name associated with the address (for example, "Acme Corporation", "Smith & Co."). This field is optional and typically used for B2B transactions, business deliveries, or when the shipping/billing address is a commercial location rather than residential. Returns \`undefined\` for individual/residential addresses. Commonly used for business customer identification, commercial shipping labels, B2B order processing, or company-based address organization. ```ts string ``` * country The country name for the address in English (for example, "United States", "Canada", "United Kingdom"). Required for international shipping, determining country-specific tax rules, and customs documentation. The full country name is used rather than an abbreviated code. Returns \`undefined\` when not provided. Commonly used for shipping calculations, tax compliance, customs forms, or country-based address validation. ```ts string ``` * countryCode The standardized \[ISO 3166-1 alpha-2]\(https://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2) country code (for example, \`"US"\` for United States, \`"CA"\` for Canada, \`"GB"\` for United Kingdom). This is a two-letter code that precisely identifies the country in a machine-readable format. Complements the full \`country\` name and is required by many shipping carriers and tax services. Returns \`undefined\` when not provided. Commonly used for precise country identification in shipping operations, international tax calculations, address validation, customs documentation, or carrier API integration. ```ts CountryCode ``` * firstName The first name (given name) of the person associated with this address (for example, "John", "Maria"). Commonly used for personalizing shipping labels, customer communications, and ensuring deliveries reach the correct recipient. Returns \`undefined\` when not provided. Typically combined with \`lastName\` for full name display. ```ts string ``` * lastName The last name (family name/surname) of the person associated with this address (for example, "Smith", "Garcia"). Commonly used for complete customer identification, shipping labels, and formal address displays. Returns \`undefined\` when not provided. Typically combined with \`firstName\` for full name display (for example, "John Smith"). ```ts string ``` * name A customer-defined label or nickname for this address to make it easily identifiable (for example, "Home", "Work", "Main Office", "Warehouse"). This friendly name helps distinguish between multiple saved addresses for the same customer. Returns \`undefined\` when no custom name is assigned. Commonly used for displaying address selection lists ("Ship to: Home"), organizing customer addresses, or showing address nicknames in dropdowns. ```ts string ``` * phone The contact phone number for this address (for example, "+1-555-123-4567", "(555) 123-4567"). Phone numbers enable carriers to contact recipients for delivery coordination, provide delivery notifications using SMS, or reach customers for address clarification. Format varies by region and may include country codes, area codes, and extensions. Returns \`undefined\` when not provided. Commonly used for delivery notifications, customer contact during shipping issues, or SMS updates about order status. ```ts string ``` * province The province, state, or region name for the address (for example, "California", "Ontario", "New South Wales"). Required for calculating regional shipping rates, determining state/provincial taxes, and routing deliveries correctly. The format is the full name rather than abbreviated code. Returns \`undefined\` when not provided or not applicable (some countries don't have province/state divisions). Commonly used for shipping rate calculations, tax jurisdiction determination, or displaying complete addresses. ```ts string ``` * provinceCode The standardized province or state code (for example, "CA" for California, "ON" for Ontario, "NSW" for New South Wales). This is typically a 2-3 character abbreviation that complements the full \`province\` name. Codes follow regional standards and enable programmatic province/state matching. Returns \`undefined\` when not applicable or not provided. Commonly used for precise regional identification in shipping APIs, automated tax calculations, address validation services, or integrating with carriers that require standardized codes. ```ts string ``` * zip The postal code or ZIP code for the address (for example, "90210", "M5V 3A8", "SW1A 1AA"). Format varies by country—US uses 5 or 9-digit ZIP codes, Canada uses alphanumeric postal codes, UK uses alphanumeric postcodes. Required for accurate shipping rate calculations, address verification, and location-based services. Returns \`undefined\` when not provided. Commonly used for shipping rate lookup, address validation, geographic sorting, or carrier integration. ```ts string ``` ```ts export interface Address { /** * The primary street address line containing the street number and name (for example, "123 Main Street", "456 Oak Avenue"). This is the first line of the mailing address and is typically required for shipping and billing operations. Returns `undefined` when not provided or not applicable. Commonly used for displaying addresses, calculating shipping rates based on location, validating address completeness, or sending to shipping carriers for label generation. */ address1?: string; /** * The secondary address line for additional location details like apartment number, suite, unit, floor, or building information (for example, "Apt 4B", "Suite 200", "Floor 3"). This field is optional and supplements the primary address line. Returns `undefined` when not provided. Commonly used for complete address display, ensuring deliveries reach the correct destination in multi-unit buildings, or providing detailed shipping instructions. */ address2?: string; /** * The city or locality name for the address (for example, "New York", "Toronto", "London"). Required for most shipping and billing operations as it's needed for calculating shipping zones, determining tax jurisdictions, and routing deliveries. Returns `undefined` when not provided. Commonly used for address display, shipping rate calculations based on destination city, tax determination, or filtering addresses by location. */ city?: string; /** * The company or business name associated with the address (for example, "Acme Corporation", "Smith & Co."). This field is optional and typically used for B2B transactions, business deliveries, or when the shipping/billing address is a commercial location rather than residential. Returns `undefined` for individual/residential addresses. Commonly used for business customer identification, commercial shipping labels, B2B order processing, or company-based address organization. */ company?: string; /** * The first name (given name) of the person associated with this address (for example, "John", "Maria"). Commonly used for personalizing shipping labels, customer communications, and ensuring deliveries reach the correct recipient. Returns `undefined` when not provided. Typically combined with `lastName` for full name display. */ firstName?: string; /** * The last name (family name/surname) of the person associated with this address (for example, "Smith", "Garcia"). Commonly used for complete customer identification, shipping labels, and formal address displays. Returns `undefined` when not provided. Typically combined with `firstName` for full name display (for example, "John Smith"). */ lastName?: string; /** * The contact phone number for this address (for example, "+1-555-123-4567", "(555) 123-4567"). Phone numbers enable carriers to contact recipients for delivery coordination, provide delivery notifications using SMS, or reach customers for address clarification. Format varies by region and may include country codes, area codes, and extensions. Returns `undefined` when not provided. Commonly used for delivery notifications, customer contact during shipping issues, or SMS updates about order status. */ phone?: string; /** * The province, state, or region name for the address (for example, "California", "Ontario", "New South Wales"). Required for calculating regional shipping rates, determining state/provincial taxes, and routing deliveries correctly. The format is the full name rather than abbreviated code. Returns `undefined` when not provided or not applicable (some countries don't have province/state divisions). Commonly used for shipping rate calculations, tax jurisdiction determination, or displaying complete addresses. */ province?: string; /** * The country name for the address in English (for example, "United States", "Canada", "United Kingdom"). Required for international shipping, determining country-specific tax rules, and customs documentation. The full country name is used rather than an abbreviated code. Returns `undefined` when not provided. Commonly used for shipping calculations, tax compliance, customs forms, or country-based address validation. */ country?: string; /** * The postal code or ZIP code for the address (for example, "90210", "M5V 3A8", "SW1A 1AA"). Format varies by country—US uses 5 or 9-digit ZIP codes, Canada uses alphanumeric postal codes, UK uses alphanumeric postcodes. Required for accurate shipping rate calculations, address verification, and location-based services. Returns `undefined` when not provided. Commonly used for shipping rate lookup, address validation, geographic sorting, or carrier integration. */ zip?: string; /** * A customer-defined label or nickname for this address to make it easily identifiable (for example, "Home", "Work", "Main Office", "Warehouse"). This friendly name helps distinguish between multiple saved addresses for the same customer. Returns `undefined` when no custom name is assigned. Commonly used for displaying address selection lists ("Ship to: Home"), organizing customer addresses, or showing address nicknames in dropdowns. */ name?: string; /** * The standardized province or state code (for example, "CA" for California, "ON" for Ontario, "NSW" for New South Wales). This is typically a 2-3 character abbreviation that complements the full `province` name. Codes follow regional standards and enable programmatic province/state matching. Returns `undefined` when not applicable or not provided. Commonly used for precise regional identification in shipping APIs, automated tax calculations, address validation services, or integrating with carriers that require standardized codes. */ provinceCode?: string; /** * The standardized [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (for example, `"US"` for United States, `"CA"` for Canada, `"GB"` for United Kingdom). This is a two-letter code that precisely identifies the country in a machine-readable format. Complements the full `country` name and is required by many shipping carriers and tax services. Returns `undefined` when not provided. Commonly used for precise country identification in shipping operations, international tax calculations, address validation, customs documentation, or carrier API integration. */ 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 isn't linked to a product in the merchant's catalog. Custom sales allow merchants to add arbitrary items to the cart with manually entered details—useful for services, custom orders, one-off items, or products not in the catalog. * price The unit price for a single unit of this custom sale item as a string value. This represents the price per item in the store's currency (for example, \`"25.00"\` for $25.00, \`"99.99"\` for $99.99). String format ensures precision for financial calculations. The total line item cost is calculated as this price multiplied by the quantity. Commonly used for pricing the custom sale, calculating line totals, displaying the charge to customers, or generating receipts with itemized pricing. ```ts string ``` * quantity The number of units of this custom sale item to add to the cart. Must be a positive integer (minimum 1) representing how many of this custom item the customer is purchasing. Since custom sales don't have inventory tracking, any quantity can be entered without stock validation. Commonly used for specifying how many of the custom item to charge for, calculating line totals (price × quantity), or displaying quantity on receipts and invoices. ```ts number ``` * taxable Whether this custom sale item is subject to tax calculations. When \`true\`, taxes are calculated and applied to this item based on location tax rules and settings. When \`false\`, this item is tax-exempt and no tax is charged. Tax exemption might apply for services, specific product categories, or non-taxable items depending on jurisdiction. Commonly used for determining whether to calculate taxes on this custom sale, compliance with tax regulations, displaying tax-inclusive vs tax-exclusive pricing, or generating accurate tax reports. ```ts boolean ``` * title The customer-facing display name for this custom sale item. This is the text that will appear on receipts, in the cart, and on order confirmations to describe what was sold. Should be descriptive and clear (for example, "Repair Service", "Custom Engraving", "Consultation Fee", "Special Order Item"). This is required to create a custom sale. Commonly used for cart and receipt displays, order identification, or describing the custom item in customer communications. ```ts string ``` ```ts export interface CustomSale { /** * The number of units of this custom sale item to add to the cart. Must be a positive integer (minimum 1) representing how many of this custom item the customer is purchasing. Since custom sales don't have inventory tracking, any quantity can be entered without stock validation. Commonly used for specifying how many of the custom item to charge for, calculating line totals (price × quantity), or displaying quantity on receipts and invoices. */ quantity: number; /** * The customer-facing display name for this custom sale item. This is the text that will appear on receipts, in the cart, and on order confirmations to describe what was sold. Should be descriptive and clear (for example, "Repair Service", "Custom Engraving", "Consultation Fee", "Special Order Item"). This is required to create a custom sale. Commonly used for cart and receipt displays, order identification, or describing the custom item in customer communications. */ title: string; /** * The unit price for a single unit of this custom sale item as a string value. This represents the price per item in the store's currency (for example, `"25.00"` for $25.00, `"99.99"` for $99.99). String format ensures precision for financial calculations. The total line item cost is calculated as this price multiplied by the quantity. Commonly used for pricing the custom sale, calculating line totals, displaying the charge to customers, or generating receipts with itemized pricing. */ price: string; /** * Whether this custom sale item is subject to tax calculations. When `true`, taxes are calculated and applied to this item based on location tax rules and settings. When `false`, this item is tax-exempt and no tax is charged. Tax exemption might apply for services, specific product categories, or non-taxable items depending on jurisdiction. Commonly used for determining whether to calculate taxes on this custom sale, compliance with tax regulations, displaying tax-inclusive vs tax-exclusive pricing, or generating accurate tax reports. */ taxable: boolean; } ``` ### 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 \[UUID]\(https://en.wikipedia.org/wiki/Universally\_unique\_identifier) of the target line item to which the selling plan should be applied. This must match the \`uuid\` of an existing line item in the current cart. If the UUID doesn't exist in the cart, the operation will fail. The line item's product must support selling plans—attempting to add a selling plan to a line item whose product doesn't have selling plan groups will result in an error. Commonly used to identify which cart item is being configured with a subscription plan. ```ts string ``` * properties The custom key-value properties attached to this line item. Empty object if no properties are set. Commonly used for metadata, customization options, or integration data. ```ts Record ``` ```ts export interface SetLineItemPropertiesInput { /** * The [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) of the target line item to which the selling plan should be applied. This must match the `uuid` of an existing line item in the current cart. If the UUID doesn't exist in the cart, the operation will fail. The line item's product must support selling plans—attempting to add a selling plan to a line item whose product doesn't have selling plan groups will result in an error. Commonly used to identify which cart item is being configured with a subscription plan. */ lineItemUuid: string; /** * The custom key-value properties attached to this line item. Empty object if no properties are set. Commonly used for metadata, customization options, or integration data. */ 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 \[UUID]\(https://en.wikipedia.org/wiki/Universally\_unique\_identifier) of the target line item to which the selling plan should be applied. This must match the \`uuid\` of an existing line item in the current cart. If the UUID doesn't exist in the cart, the operation will fail. The line item's product must support selling plans—attempting to add a selling plan to a line item whose product doesn't have selling plan groups will result in an error. Commonly used to identify which cart item is being configured with a subscription plan. ```ts string ``` ```ts export interface SetLineItemDiscountInput { /** * The [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) of the target line item to which the selling plan should be applied. This must match the `uuid` of an existing line item in the current cart. If the UUID doesn't exist in the cart, the operation will fail. The line item's product must support selling plans—attempting to add a selling plan to a line item whose product doesn't have selling plan groups will result in an error. Commonly used to identify which cart item is being configured with a subscription plan. */ 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 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 string ``` * title The customer-facing display name for this custom sale item. This is the text that will appear on receipts, in the cart, and on order confirmations to describe what was sold. Should be descriptive and clear (for example, "Repair Service", "Custom Engraving", "Consultation Fee", "Special Order Item"). This is required to create a custom sale. Commonly used for cart and receipt displays, order identification, or describing the custom item in customer communications. ```ts string ``` * type The \[discount type]\(https://help.api.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 'Percentage' | 'FixedAmount' ``` ```ts export interface LineItemDiscount { /** * The customer-facing display name for this custom sale item. This is the text that will appear on receipts, in the cart, and on order confirmations to describe what was sold. Should be descriptive and clear (for example, "Repair Service", "Custom Engraving", "Consultation Fee", "Special Order Item"). This is required to create a custom sale. Commonly used for cart and receipt displays, order identification, or describing the custom item in customer communications. */ title: string; /** * The [discount type](https://help.api.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: 'Percentage' | 'FixedAmount'; /** * 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: string; } ``` ### Customer Represents basic customer identification information. Contains the customer ID for linking to detailed customer data and enabling customer-specific features. * email The customer's email address for communication and account identification. Used for sending order confirmations, receipts, marketing communications, and account recovery. Returns \`undefined\` when no email is associated with the customer account. ```ts string ``` * firstName The customer's first name (given name) as stored in their Shopify account. Used for personalizing communications and displaying customer information on receipts and orders. Returns \`undefined\` when first name isn't provided. ```ts string ``` * 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 ``` * lastName The customer's last name (family name/surname) as stored in their Shopify account. Used for personalizing communications and displaying customer information on receipts and orders. Returns \`undefined\` when last name isn't provided. ```ts string ``` * note Internal notes about this customer for merchant reference only. This field is not visible to the customer and can contain information like preferences, special instructions, or account history. Returns \`undefined\` when no notes have been added. Commonly used for tracking customer preferences, recording important account details, or communicating information between staff members. ```ts string ``` ```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; /** * The customer's email address for communication and account identification. Used for sending order confirmations, receipts, marketing communications, and account recovery. Returns `undefined` when no email is associated with the customer account. */ email?: string; /** * The customer's first name (given name) as stored in their Shopify account. Used for personalizing communications and displaying customer information on receipts and orders. Returns `undefined` when first name isn't provided. */ firstName?: string; /** * The customer's last name (family name/surname) as stored in their Shopify account. Used for personalizing communications and displaying customer information on receipts and orders. Returns `undefined` when last name isn't provided. */ lastName?: string; /** * Internal notes about this customer for merchant reference only. This field is not visible to the customer and can contain information like preferences, special instructions, or account history. Returns `undefined` when no notes have been added. Commonly used for tracking customer preferences, recording important account details, or communicating information between staff members. */ note?: string; } ``` ### 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' ``` ### 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 ``` * 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 attached to this line item. Empty object if no properties are set. Commonly used for metadata, customization options, or integration data. ```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 { /** * 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 attached to this line item. Empty object if no properties are set. Commonly used for metadata, customization options, or integration data. */ 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 ``` * 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.api.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; /** * 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.api.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; } ``` ### LineItem Represents an individual item in the shopping cart. Contains product information, pricing, quantity, discounts, and customization details for a single cart entry. * discounts An array of all discounts applied specifically to this line item (not cart-level discounts). Each discount object contains the amount, type, and description. The array is empty when no line item-specific discounts are applied. Multiple discounts can apply to a single line item when discount stacking is enabled. The sum of discount amounts reduces the line item's contribution to the cart total. Commonly used for displaying line item savings ("You save $5.00"), showing discount breakdowns in itemized views, calculating effective prices after discounts, or implementing discount-aware business logic. ```ts Discount[] ``` * isGiftCard Whether this line item is a gift card product. When \`true\`, indicates this is a Shopify gift card (digital or physical) which has special handling—gift cards don't affect inventory, have different tax treatment in some jurisdictions, and generate gift card codes upon purchase. When \`false\`, this is a regular product, custom sale, or other non-gift-card item. Gift card line items may have restrictions on discounts or combinations with other line items. Commonly used for implementing gift card-specific UI, applying gift card business rules, excluding gift cards from certain promotions, or separating gift card sales in reporting. ```ts boolean ``` * price The unit price for a single unit of this custom sale item as a string value. This represents the price per item in the store's currency (for example, \`"25.00"\` for $25.00, \`"99.99"\` for $99.99). String format ensures precision for financial calculations. The total line item cost is calculated as this price multiplied by the quantity. Commonly used for pricing the custom sale, calculating line totals, displaying the charge to customers, or generating receipts with itemized pricing. ```ts number ``` * productId The unique numeric identifier for the product this bundle component represents. Links to the parent product in the Shopify catalog. Returns \`undefined\` for custom components or non-catalog items within the bundle. When present, this ID can be used to fetch full product information about the component. Commonly used for component product lookups, grouping bundle components, or linking to product records. ```ts number ``` * properties The custom key-value properties attached to this line item. Empty object if no properties are set. Commonly used for metadata, customization options, or integration data. ```ts { [key: string]: string; } ``` * quantity The number of units of this custom sale item to add to the cart. Must be a positive integer (minimum 1) representing how many of this custom item the customer is purchasing. Since custom sales don't have inventory tracking, any quantity can be entered without stock validation. Commonly used for specifying how many of the custom item to charge for, calculating line totals (price × quantity), or displaying quantity on receipts and invoices. ```ts number ``` * sku The Stock Keeping Unit (SKU) identifier for this line item as configured in the product catalog. SKUs are merchant-defined alphanumeric codes used for inventory tracking, fulfillment, and product identification (for example, "TSHIRT-BLU-LG", "12345-A"). Returns \`undefined\` when no SKU is configured for the product variant, which is common for products without inventory tracking or custom sales. The SKU is unique within the merchant's catalog and is often used with barcode scanners or inventory management systems. Commonly used for inventory tracking, displaying product codes on receipts, integrating with warehouse management systems, or matching products with external SKU-based systems. ```ts string ``` * taxable Whether this custom sale item is subject to tax calculations. When \`true\`, taxes are calculated and applied to this item based on location tax rules and settings. When \`false\`, this item is tax-exempt and no tax is charged. Tax exemption might apply for services, specific product categories, or non-taxable items depending on jurisdiction. Commonly used for determining whether to calculate taxes on this custom sale, compliance with tax regulations, displaying tax-inclusive vs tax-exclusive pricing, or generating accurate tax reports. ```ts boolean ``` * title The customer-facing display name for this custom sale item. This is the text that will appear on receipts, in the cart, and on order confirmations to describe what was sold. Should be descriptive and clear (for example, "Repair Service", "Custom Engraving", "Consultation Fee", "Special Order Item"). This is required to create a custom sale. Commonly used for cart and receipt displays, order identification, or describing the custom item in customer communications. ```ts string ``` * uuid The unique \[UUID]\(https://en.wikipedia.org/wiki/Universally\_unique\_identifier) string identifier for this specific line item within the cart. This identifier is generated when the line item is added to the cart and remains constant for that line item throughout its lifecycle. The UUID distinguishes this line item from other line items in the cart, even if they represent the same product or variant. This is the primary key for line item operations—all Cart API methods that target specific line items require this UUID. Commonly used for updating line item properties, applying line item discounts, removing items from cart, setting selling plans, or tracking individual line items through the checkout process. ```ts string ``` * variantId The unique numeric identifier for the product variant this bundle component represents. Links to a specific variant in the Shopify catalog. Returns \`undefined\` for custom components or non-catalog items within the bundle. When present, this ID can be used to fetch full variant details or verify component inventory. Commonly used for component inventory management, linking bundle components to catalog records, or loading component variant details. ```ts number ``` * vendor The vendor or brand name for this line item as configured in the product catalog (for example, "Nike", "Acme Corp", "House Brand"). This indicates who manufactures or supplies the product. Returns \`undefined\` when no vendor is set for the product, which is common for products where vendor tracking isn't used. Vendors are merchant-defined and not standardized. Commonly used for vendor-specific displays in cart or receipts, filtering or grouping products by vendor, implementing vendor-based business logic (special handling for certain suppliers), or reporting sales by vendor. ```ts string ``` ```ts export interface LineItem { /** * The unique [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) string identifier for this specific line item within the cart. This identifier is generated when the line item is added to the cart and remains constant for that line item throughout its lifecycle. The UUID distinguishes this line item from other line items in the cart, even if they represent the same product or variant. This is the primary key for line item operations—all Cart API methods that target specific line items require this UUID. Commonly used for updating line item properties, applying line item discounts, removing items from cart, setting selling plans, or tracking individual line items through the checkout process. */ uuid: string; /** * The unit price for a single unit of this custom sale item as a string value. This represents the price per item in the store's currency (for example, `"25.00"` for $25.00, `"99.99"` for $99.99). String format ensures precision for financial calculations. The total line item cost is calculated as this price multiplied by the quantity. Commonly used for pricing the custom sale, calculating line totals, displaying the charge to customers, or generating receipts with itemized pricing. */ price?: number; /** * The number of units of this custom sale item to add to the cart. Must be a positive integer (minimum 1) representing how many of this custom item the customer is purchasing. Since custom sales don't have inventory tracking, any quantity can be entered without stock validation. Commonly used for specifying how many of the custom item to charge for, calculating line totals (price × quantity), or displaying quantity on receipts and invoices. */ quantity: number; /** * The customer-facing display name for this custom sale item. This is the text that will appear on receipts, in the cart, and on order confirmations to describe what was sold. Should be descriptive and clear (for example, "Repair Service", "Custom Engraving", "Consultation Fee", "Special Order Item"). This is required to create a custom sale. Commonly used for cart and receipt displays, order identification, or describing the custom item in customer communications. */ title?: string; /** * The unique numeric identifier for the product variant this bundle component represents. Links to a specific variant in the Shopify catalog. Returns `undefined` for custom components or non-catalog items within the bundle. When present, this ID can be used to fetch full variant details or verify component inventory. Commonly used for component inventory management, linking bundle components to catalog records, or loading component variant details. */ variantId?: number; /** * The unique numeric identifier for the product this bundle component represents. Links to the parent product in the Shopify catalog. Returns `undefined` for custom components or non-catalog items within the bundle. When present, this ID can be used to fetch full product information about the component. Commonly used for component product lookups, grouping bundle components, or linking to product records. */ productId?: number; /** * An array of all discounts applied specifically to this line item (not cart-level discounts). Each discount object contains the amount, type, and description. The array is empty when no line item-specific discounts are applied. Multiple discounts can apply to a single line item when discount stacking is enabled. The sum of discount amounts reduces the line item's contribution to the cart total. Commonly used for displaying line item savings ("You save $5.00"), showing discount breakdowns in itemized views, calculating effective prices after discounts, or implementing discount-aware business logic. */ discounts: Discount[]; /** * Whether this custom sale item is subject to tax calculations. When `true`, taxes are calculated and applied to this item based on location tax rules and settings. When `false`, this item is tax-exempt and no tax is charged. Tax exemption might apply for services, specific product categories, or non-taxable items depending on jurisdiction. Commonly used for determining whether to calculate taxes on this custom sale, compliance with tax regulations, displaying tax-inclusive vs tax-exclusive pricing, or generating accurate tax reports. */ taxable: boolean; /** * The Stock Keeping Unit (SKU) identifier for this line item as configured in the product catalog. SKUs are merchant-defined alphanumeric codes used for inventory tracking, fulfillment, and product identification (for example, "TSHIRT-BLU-LG", "12345-A"). Returns `undefined` when no SKU is configured for the product variant, which is common for products without inventory tracking or custom sales. The SKU is unique within the merchant's catalog and is often used with barcode scanners or inventory management systems. Commonly used for inventory tracking, displaying product codes on receipts, integrating with warehouse management systems, or matching products with external SKU-based systems. */ sku?: string; /** * The vendor or brand name for this line item as configured in the product catalog (for example, "Nike", "Acme Corp", "House Brand"). This indicates who manufactures or supplies the product. Returns `undefined` when no vendor is set for the product, which is common for products where vendor tracking isn't used. Vendors are merchant-defined and not standardized. Commonly used for vendor-specific displays in cart or receipts, filtering or grouping products by vendor, implementing vendor-based business logic (special handling for certain suppliers), or reporting sales by vendor. */ vendor?: string; /** * The custom key-value properties attached to this line item. Empty object if no properties are set. Commonly used for metadata, customization options, or integration data. */ properties: {[key: string]: string}; /** * Whether this line item is a gift card product. When `true`, indicates this is a Shopify gift card (digital or physical) which has special handling—gift cards don't affect inventory, have different tax treatment in some jurisdictions, and generate gift card codes upon purchase. When `false`, this is a regular product, custom sale, or other non-gift-card item. Gift card line items may have restrictions on discounts or combinations with other line items. Commonly used for implementing gift card-specific UI, applying gift card business rules, excluding gift cards from certain promotions, or separating gift card sales in reporting. */ isGiftCard: boolean; } ``` Examples ### 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 ```tsx 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 ( api.cart.addCustomSale({ title: 'New product', quantity: 1, price: '10.00', taxable: true, })} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.addAddress({ address1: '123456 Main Street', city: 'Ottawa', province: 'Ontario', firstName: 'John', lastName: 'Doe', country: 'Canada' })} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.addLineItem(12345678, 1)} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.addLineItemProperties('aa-1234567', {Engraving: 'John Doe'})} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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'}); }, }); 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 ```tsx 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 ( api.cart.bulkAddLineItemProperties([ {lineItemUuid: 'aa-1234567', properties: {Engraving: 'John Doe'}}, {lineItemUuid: 'bb-001234567', properties: {Engraving: 'Jane Doe'}} ])} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.addCartProperties({Engraving: 'John Doe'})} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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'}); }, }); 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 ```tsx 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 ( api.cart.addCartCodeDiscount('SUMMER_2024')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.setLineItemDiscount('aa-1234567', 'Percentage', 'Summer discount', '10')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.applyCartDiscount('Percentage', 'Summer discount', '10')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( 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', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.setCustomer({ id: 1, })} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.setAttributedStaffToLineItem(123456, 'aa-1234567')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.setAttributedStaff(123456)} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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); }); ``` * #### 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 ```tsx 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 ( api.cart.clearCart()} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.deleteAddress(123456)} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx import React from 'react'; import { reactExtension, useApi, Tile, useCartSubscription } from '@shopify/ui-extensions-react/point-of-sale'; const SmartGridTile = () => { const cart = useCartSubscription(); return ( ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.removeLineItemDiscount('aa-1234567')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.removeLineItem('aa-1234567')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.removeAllDiscounts(true)} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.removeLineItemProperties('aa-1234567', ['Engraving'])} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.removeCartProperties(['Engraving'])} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.removeCustomer()} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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 ```tsx 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 ( api.cart.updateDefaultAddress(123456)} /> ); }; export default reactExtension( 'pos.home.tile.render', () => ); ``` ##### TS ```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); }); ``` ## Best practices * **Manage subscriptions properly:** Remember that `RemoteSubscribable` supports only one subscription at a time. Use `makeStatefulSubscribable` if you need multiple components to subscribe to cart changes simultaneously. * **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 `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. ## Limitations * `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.