--- title: Cart API description: | The Cart API enables UI Extensions to manage and interact with POS cart contents, such as discounts, line items, and customer details. It provides a comprehensive set of functions for adding and removing items, alongside a subscribable object that keeps the UI Extension updated with real-time changes to the cart. #### Supporting targets - [pos.home.tile.render](/docs/api/pos-ui-extensions/targets/smart-grid/pos-home-tile-render) - [pos.home.modal.render](/docs/api/pos-ui-extensions/targets/smart-grid/pos-home-modal-render) - [pos.product-details.action.menu-item.render](/docs/api/pos-ui-extensions/targets/product-details/pos-product-details-action-menu-item-render) - [pos.product-details.action.render](/docs/api/pos-ui-extensions/targets/product-details/pos-product-details-action-render) - [pos.product-details.block.render](/docs/api/pos-ui-extensions/targets/product-details/pos-product-details-block-render) - [pos.customer-details.action.menu-item.render](/docs/api/pos-ui-extensions/targets/customer-details/pos-customer-details-action-menu-item-render) - [pos.customer-details.action.render](/docs/api/pos-ui-extensions/targets/customer-details/pos-customer-details-action-render) - [pos.customer-details.block.render](/docs/api/pos-ui-extensions/targets/customer-details/pos-customer-details-block-render) - [pos.order-details.action.menu-item.render](/docs/api/pos-ui-extensions/targets/order-details/pos-order-details-action-menu-item-render) - [pos.order-details.action.render](/docs/api/pos-ui-extensions/targets/order-details/pos-order-details-action-render) - [pos.order-details.block.render](/docs/api/pos-ui-extensions/targets/order-details/pos-order-details-block-render) - [pos.draft-order-details.action.menu-item.render](/docs/api/pos-ui-extensions/targets/draft-order-details/pos-draft-order-details-action-menu-item-render) - [pos.draft-order-details.action.render](/docs/api/pos-ui-extensions/targets/draft-order-details/pos-draft-order-details-action-render) - [pos.draft-order-details.block.render](/docs/api/pos-ui-extensions/targets/draft-order-details/pos-draft-order-details-block-render) api_version: 2025-10 api_name: pos-ui-extensions source_url: html: https://shopify.dev/docs/api/pos-ui-extensions/latest/apis/cart-api md: https://shopify.dev/docs/api/pos-ui-extensions/latest/apis/cart-api.md --- # Cart APIAPIs The Cart API enables UI Extensions to manage and interact with POS cart contents, such as discounts, line items, and customer details. It provides a comprehensive set of functions for adding and removing items, alongside a subscribable object that keeps the UI Extension updated with real-time changes to the cart. #### Supporting targets * [pos.home.tile.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/smart-grid/pos-home-tile-render) * [pos.home.modal.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/smart-grid/pos-home-modal-render) * [pos.product-details.action.menu-item.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/product-details/pos-product-details-action-menu-item-render) * [pos.product-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/product-details/pos-product-details-action-render) * [pos.product-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/product-details/pos-product-details-block-render) * [pos.customer-details.action.menu-item.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/customer-details/pos-customer-details-action-menu-item-render) * [pos.customer-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/customer-details/pos-customer-details-action-render) * [pos.customer-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/customer-details/pos-customer-details-block-render) * [pos.order-details.action.menu-item.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/order-details/pos-order-details-action-menu-item-render) * [pos.order-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/order-details/pos-order-details-action-render) * [pos.order-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/order-details/pos-order-details-block-render) * [pos.draft-order-details.action.menu-item.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/draft-order-details/pos-draft-order-details-action-menu-item-render) * [pos.draft-order-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/draft-order-details/pos-draft-order-details-action-render) * [pos.draft-order-details.block.render](https://shopify.dev/docs/api/pos-ui-extensions/targets/draft-order-details/pos-draft-order-details-block-render) ## CartApi * addAddress (address: Address) => Promise\ required Add an address to the customer (Customer must be present) * addCartCodeDiscount (code: string) => Promise\ required Add a code discount to the cart * addCartProperties (properties: Record\) => Promise\ required Adds custom properties to the cart * addCustomSale (customSale: CustomSale) => Promise\ required Add a custom sale to the cart * addLineItem (variantId: number, quantity: number) => Promise\ required Add a line item by variant ID to the cart. Returns the uuid of the line item added, or the empty string if the user dismissed an oversell guard modal without adding anything. Throws if POS fails to add the line item. Throws if POS fails to add the line item. * addLineItemProperties (uuid: string, properties: Record\) => Promise\ required Adds custom properties to the specified line item * addLineItemSellingPlan (input: SetLineItemSellingPlanInput) => Promise\ required Add a selling plan to a line item in the cart. * applyCartDiscount (type: CartDiscountType, title: string, amount?: string) => Promise\ required Apply a cart level discount * bulkAddLineItemProperties (lineItemProperties: SetLineItemPropertiesInput\[]) => Promise\ required Adds custom properties to multiple line items at the same time. * bulkCartUpdate (cartState: CartUpdateInput) => Promise\ required Bulk update the cart * bulkSetLineItemDiscounts (lineItemDiscounts: SetLineItemDiscountInput\[]) => Promise\ required Set line item discounts to multiple line items at the same time. * clearCart () => Promise\ required Clear the cart * 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. * deleteAddress (addressId: number) => Promise\ required Delete an address from the customer (Customer must be present) * removeAllDiscounts (disableAutomaticDiscounts: boolean) => Promise\ required Remove all cart and line item discounts * removeCartDiscount () => Promise\ required Remove the cart discount * removeCartProperties (keys: string\[]) => Promise\ required Removes the specified cart properties * removeCustomer () => Promise\ required Remove the current customer from the cart * removeLineItem (uuid: string) => Promise\ required Remove the line item at this uuid from the cart * removeLineItemDiscount (uuid: string) => Promise\ required Remove all discounts from a line item * removeLineItemProperties (uuid: string, keys: string\[]) => Promise\ required Removes the specified line item properties * removeLineItemSellingPlan (uuid: string) => Promise\ required Remove the selling plan from a line item in the cart. * setAttributedStaff (staffId: number) => Promise\ required Sets an attributed staff to all line items in the cart. * setAttributedStaffToLineItem (staffId: number, lineItemUuid: string) => Promise\ required Sets an attributed staff to a specific line items in the cart. * setCustomer (customer: Customer) => Promise\ required Set the customer in the cart * setLineItemDiscount (uuid: string, type: LineItemDiscountType, title: string, amount: string) => Promise\ required Add a discount on a line item to the cart * updateDefaultAddress (addressId: number) => Promise\ required Update the default address for the customer (Customer must be present) ### Address * address1 ```ts string ``` * address2 ```ts string ``` * city ```ts string ``` * company ```ts string ``` * country ```ts string ``` * countryCode ```ts CountryCode ``` * firstName ```ts string ``` * lastName ```ts string ``` * name ```ts string ``` * phone ```ts string ``` * province ```ts string ``` * provinceCode ```ts string ``` * zip ```ts string ``` ```ts export interface Address { address1?: string; address2?: string; city?: string; company?: string; firstName?: string; lastName?: string; phone?: string; province?: string; country?: string; zip?: string; name?: string; provinceCode?: string; 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 * price ```ts string ``` * quantity ```ts number ``` * taxable ```ts boolean ``` * title ```ts string ``` ```ts export interface CustomSale { quantity: number; title: string; price: string; taxable: boolean; } ``` ### SetLineItemSellingPlanInput * lineItemUuid The uuid of the line item to which the selling plan should be applied. ```ts string ``` * sellingPlanId The ID of the selling plan to apply to the line item. ```ts number ``` * sellingPlanName The name of the selling plan to apply to the line item. If not provided, POS will try to fetch it from the server after syncing the cart. ```ts string ``` ```ts export interface SetLineItemSellingPlanInput { /** * The uuid of the line item to which the selling plan should be applied. */ lineItemUuid: string; /** * The ID of the selling plan to apply to the line item. */ sellingPlanId: number; /** * The name of the selling plan to apply to the line item. * If not provided, POS will try to fetch it from the server after syncing the cart. */ sellingPlanName?: string; } ``` ### CartDiscountType ```ts 'Percentage' | 'FixedAmount' | 'Code' ``` ### SetLineItemPropertiesInput Parameters for adding custom properties to a line item. * lineItemUuid The uuid belonging to the line item which should receive the custom properties. ```ts string ``` * properties The custom properties to apply to the line item. ```ts Record ``` ```ts export interface SetLineItemPropertiesInput { /** * The uuid belonging to the line item which should receive the custom properties. */ lineItemUuid: string; /** * The custom properties to apply to the line item. */ properties: Record; } ``` ### CartUpdateInput * cartDiscount ```ts Discount ``` * cartDiscounts ```ts Discount[] ``` * customer ```ts Customer ``` * lineItems ```ts LineItem[] ``` * note ```ts string ``` * properties ```ts Record ``` ```ts export interface CartUpdateInput { note?: string; cartDiscount?: Discount; cartDiscounts: Discount[]; customer?: Customer; lineItems: LineItem[]; properties: Record; } ``` ### Discount * amount ```ts number ``` * currency ```ts string ``` * discountDescription ```ts string ``` * type ```ts string ``` ```ts export interface Discount { amount: number; currency?: string; discountDescription?: string; type?: string; } ``` ### Customer * id ```ts number ``` ```ts export interface Customer { id: number; } ``` ### LineItem * attributedUserId ```ts number ``` * discountAllocations ```ts DiscountAllocation[] ``` * discounts ```ts Discount[] ``` * hasSellingPlanGroups ```ts boolean ``` * isGiftCard ```ts boolean ``` * price ```ts number ``` * productId ```ts number ``` * properties ```ts { [key: string]: string; } ``` * quantity ```ts number ``` * requiresSellingPlan ```ts boolean ``` * sellingPlan The currently selected selling plan for this line item. ```ts SellingPlan ``` * sku ```ts string ``` * taxable ```ts boolean ``` * taxLines ```ts TaxLine[] ``` * title ```ts string ``` * uuid ```ts string ``` * variantId ```ts number ``` * vendor ```ts string ``` ```ts export interface LineItem { uuid: string; price?: number; quantity: number; title?: string; variantId?: number; productId?: number; discounts: Discount[]; discountAllocations?: DiscountAllocation[]; taxable: boolean; taxLines: TaxLine[]; sku?: string; vendor?: string; properties: {[key: string]: string}; isGiftCard: boolean; attributedUserId?: number; requiresSellingPlan?: boolean; hasSellingPlanGroups?: boolean; /** * The currently selected selling plan for this line item. */ sellingPlan?: SellingPlan; } ``` ### DiscountAllocation * allocatedAmount ```ts MoneyV2 ``` ```ts export interface DiscountAllocation { allocatedAmount: MoneyV2; } ``` ### MoneyV2 * amount ```ts string ``` * currencyCode ```ts string ``` ```ts export interface MoneyV2 { amount: string; currencyCode: string; } ``` ### SellingPlan Represents a selling plan associated with a line item. * 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 selling plan. ```ts string ``` ```ts export interface SellingPlan { /** * The unique identifier of the selling plan. */ id: number; /** * The name of the selling plan. */ 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; } ``` ### TaxLine * enabled ```ts boolean ``` * price ```ts Money ``` * rate ```ts number ``` * rateRange ```ts { min: number; max: number; } ``` * title ```ts string ``` * uuid ```ts string ``` ```ts export interface TaxLine { title: string; price: Money; rate: number; uuid?: string; rateRange?: {min: number; max: number}; enabled?: boolean; } ``` ### Money * amount ```ts number ``` * currency ```ts string ``` ```ts export interface Money { amount: number; currency: string; } ``` ### Cart * cartDiscount ```ts Discount ``` * cartDiscounts ```ts Discount[] ``` * customer ```ts Customer ``` * editable Indicates whether the cart is currently editable. An undefined value should be treated as \`true\` for backward compatibility. ```ts boolean ``` * grandTotal ```ts string ``` * lineItems ```ts LineItem[] ``` * note ```ts string ``` * properties ```ts Record ``` * subtotal ```ts string ``` * taxTotal ```ts string ``` ```ts export interface Cart { /** * Indicates whether the cart is currently editable. * * An undefined value should be treated as `true` for backward compatibility. */ editable?: boolean; subtotal: string; taxTotal: string; grandTotal: string; note?: string; cartDiscount?: Discount; cartDiscounts: Discount[]; customer?: Customer; lineItems: LineItem[]; properties: Record; } ``` ### SetLineItemDiscountInput Parameters for adding a line item discount. * lineItemDiscount The discount to be applied to the line item. ```ts LineItemDiscount ``` * lineItemUuid The uuid belonging to the line item which should receive the discount. ```ts string ``` ```ts export interface SetLineItemDiscountInput { /** * The uuid belonging to the line item which should receive the discount. */ lineItemUuid: string; /** * The discount to be applied to the line item. */ lineItemDiscount: LineItemDiscount; } ``` ### LineItemDiscount * amount The percentage or fixed amount for the discount. ```ts string ``` * title The title of the line item discount. ```ts string ``` * type The discount type. ```ts 'Percentage' | 'FixedAmount' ``` ```ts export interface LineItemDiscount { /** * The title of the line item discount. */ title: string; /** * The discount type. */ type: 'Percentage' | 'FixedAmount'; /** * The percentage or fixed amount for the discount. */ amount: string; } ``` ### ReadonlySignalLike Represents a read-only value managed on the main thread that an extension can subscribe to. Example: Checkout uses this to manage the state of an object and communicate state changes to extensions running in a sandboxed web worker. This interface is compatible with \[Preact's ReadonlySignal]\(https\://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709). * subscribe ```ts (fn: (value: T) => void) => () => void ``` * value ```ts T ``` ```ts export interface ReadonlySignalLike { readonly value: T; subscribe(fn: (value: T) => void): () => void; } ``` ### LineItemDiscountType ```ts 'Percentage' | 'FixedAmount' ``` ## Examples Examples of using the Cart API Subscribe to cart changes. Check editable state of the cart Apply a cart level discount Apply a cart level discount code Remove all the discounts on the cart and line items Set a custom discount on a line item Set a custom discount on multiple line items Remove a discount on a line item Clear the entire cart Set the customer in the cart Remove the customer in the cart Add a custom sale to the cart Add a line item to the cart Remove a line item from the cart Add custom properties to the cart Remove custom properties from the cart Add custom properties to a line item Add custom properties to multiple line items Remove custom properties from a line item Set an attributed staff member on the cart Set an attributed staff member on a line item Add an address to the customer in the cart Delete an address corresponding to an ID Set the default address of the customer in the cart Add a selling plan to a line item in the cart Remove a selling plan from a line item in the cart ### Examples * #### Subscribe to cart changes. ##### 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 ( ); }; ``` * #### Check editable state of the cart ##### 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 ( ); }; ``` * #### Apply a cart level discount ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.applyCartDiscount('Percentage', 'Summer discount', '10'); }} /> ); }; ``` * #### Apply a cart level discount code ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.addCartCodeDiscount('SUMMER10'); }} /> ); }; ``` * #### Remove all the discounts on the cart and line items ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeAllDiscounts(true); }} /> ); }; ``` * #### Set a custom discount on a line item ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.setLineItemDiscount( 'aa-1234567', 'Percentage', 'Summer discount', '10', ); }} /> ); }; ``` * #### Set a custom discount on multiple line items ##### 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', }, }, ]); }} /> ); }; ``` * #### Remove a discount on a line item ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeLineItemDiscount('aa-1234567'); }} /> ); }; ``` * #### Clear the entire cart ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.clearCart(); }} /> ); }; ``` * #### Set the customer in the cart ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.setCustomer({ id: 1, }); }} /> ); }; ``` * #### Remove the customer in the cart ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeCustomer(); }} /> ); }; ``` * #### Add a custom sale to the cart ##### 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 line item to the cart ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.addLineItem(12345678, 1); }} /> ); }; ``` * #### Remove a line item from the cart ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeLineItem('aa-1234567'); }} /> ); }; ``` * #### Add custom properties to the cart ##### 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', }); }} /> ); }; ``` * #### Remove custom properties from the cart ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeCartProperties(['note']); }} /> ); }; ``` * #### Add custom properties to a line item ##### 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 multiple line items ##### 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', }, }, ]); }} /> ); }; ``` * #### Remove custom properties from a line item ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeLineItemProperties('aa-1234567', ['note']); }} /> ); }; ``` * #### Set an attributed staff member on the cart ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.setAttributedStaff(123456); }} /> ); }; ``` * #### Set an attributed staff member on a line item ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.setAttributedStaffToLineItem(123456, 'aa-1234567'); }} /> ); }; ``` * #### Add an address to the customer in the cart ##### 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', }); }} /> ); }; ``` * #### Delete an address corresponding to an ID ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.deleteAddress(123456); }} /> ); }; ``` * #### Set the default address of the customer in the cart ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.updateDefaultAddress(123456); }} /> ); }; ``` * #### Add a selling plan to a line item in the cart ##### 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', }); }} /> ); }; ``` * #### Remove a selling plan from a line item in the cart ##### jsx ```jsx import {render} from 'preact'; export default async () => { render(, document.body); }; const Extension = () => { return ( { shopify.cart.removeLineItemSellingPlan('aa-1234567'); }} /> ); }; ```