# Cart API 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. ## CartApi ### CartApiContent ### subscribable Provides a subscription to POS cart changes. Provides an initial value and a callback to subscribe to value changes. Currently supports only one subscription. You can utilize `makeStatefulSubscribable` on a `RemoteSubscribable` to implement multiple subscriptions. Using `makeStatefulSubscribable` or the corresponding hooks counts as a subscription. ### applyCartDiscount Apply a cart level discount ### addCartCodeDiscount Add a code discount to the cart ### removeCartDiscount Remove the cart discount ### removeAllDiscounts Remove all cart and line item discounts ### clearCart Clear the cart ### setCustomer Set the customer in the cart ### removeCustomer Remove the current customer from the cart ### addCustomSale Add a custom sale to the cart ### addLineItem Add a line item by variant ID to the cart ### removeLineItem Remove the line item at this uuid from the cart ### addCartProperties Adds custom properties to the cart ### removeCartProperties Removes the specified cart properties ### addLineItemProperties Adds custom properties to the specified line item ### bulkAddLineItemProperties Adds custom properties to multiple line items at the same time. ### removeLineItemProperties Removes the specified line item properties ### setLineItemDiscount Add a discount on a line item to the cart ### bulkSetLineItemDiscounts Set line item discounts to multiple line items at the same time. ### setAttributedStaff Sets an attributed staff to all line items in the cart. ### setAttributedStaffToLineItem Sets an attributed staff to a specific line items in the cart. ### removeLineItemDiscount Remove all discounts from a line item ### addAddress Add an address to the customer (Customer must be present) ### deleteAddress Delete an address from the customer (Customer must be present) ### updateDefaultAddress Update the default address for the customer (Customer must be present) ### Cart ### subtotal ### taxTotal ### grandTotal ### note ### cartDiscount ### cartDiscounts ### customer ### lineItems ### properties ### Discount ### amount ### discountDescription ### type ### Customer ### id ### email ### firstName ### lastName ### note ### LineItem ### uuid ### price ### quantity ### title ### variantId ### productId ### discounts ### taxable ### sku ### vendor ### properties ### isGiftCard ### CartDiscountType 'Percentage' | 'FixedAmount' | 'Code' ### CustomSale ### quantity ### title ### price ### taxable ### SetLineItemPropertiesInput Parameters for adding custom properties to a line item. ### lineItemUuid The uuid belonging to the line item which should receive the custom properties. ### properties The custom properties to apply to the line item. ### LineItemDiscountType 'Percentage' | 'FixedAmount' ### SetLineItemDiscountInput Parameters for adding a line item discount. ### lineItemUuid The uuid belonging to the line item which should receive the discount. ### lineItemDiscount The discount to be applied to the line item. ### LineItemDiscount ### title The title of the line item discount. ### type The discount type. ### amount The percentage or fixed amount for the discount. ### Address ### address1 ### address2 ### city ### company ### firstName ### lastName ### phone ### province ### country ### zip ### name ### provinceCode ### countryCode ## Examples 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. ### ### Subscribe to cart changes. ```tsx import React from 'react'; import { reactExtension, useApi, Tile, useCartSubscription } from '@shopify/ui-extensions-react/point-of-sale'; const SmartGridTile = () => { const cart = useCartSubscription(); return ( <Tile title='My App' subtitle={`${cart.lineItems.length} line items in cart`} enabled /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Cart, Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: `${api.cart.subscribable.initial.lineItems.length} line items in cart`, enabled: true, }); api.cart.subscribable.subscribe((newCart: Cart) => { tile.updateProps({ subtitle: `${newCart.lineItems.length > 0} line items in cart`, }); }); root.append(tile); }); ``` ### ### Apply a cart level discount ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.applyCartDiscount('Percentage', 'Summer discount', '10')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.applyCartDiscount('Percentage', 'Summer discount', '10'); }, }); root.append(tile); }); ``` ### ### Apply a cart level discount code ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.addCartCodeDiscount('SUMMER_2024')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.addCartCodeDiscount('SUMMER_2024'); }, }); root.append(tile); }); ``` ### ### Remove all the discounts on the cart and line items ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.removeAllDiscounts(true)} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.removeAllDiscounts(true); }, }); root.append(tile); }); ``` ### ### Set a custom discount on a line item ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.setLineItemDiscount('aa-1234567', 'Percentage', 'Summer discount', '10')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.setLineItemDiscount( 'aa-1234567', 'Percentage', 'Summer discount', '10', ); }, }); root.append(tile); }); ``` ### ### Set a custom discount on multiple line items ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.bulkSetLineItemDiscounts([ { lineItemUuid: 'aa-1234567', lineItemDiscount: { title: 'Summer 2024', amount: '10', type: 'Percentage', }, }, { lineItemUuid: 'bb-1234567', lineItemDiscount: { title: 'Shorts sale', amount: '15', type: 'FixedAmount', }, }, ])} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.bulkSetLineItemDiscounts([ { lineItemUuid: 'aa-1234567', lineItemDiscount: { title: 'Summer 2024', amount: '10', type: 'Percentage', }, }, { lineItemUuid: 'bb-1234567', lineItemDiscount: { title: 'Shorts sale', amount: '15', type: 'FixedAmount', }, }, ]); }, }); root.append(tile); }); ``` ### ### Remove a discount on a line item ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.removeLineItemDiscount('aa-1234567')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.removeLineItemDiscount('aa-1234567'); }, }); root.append(tile); }); ``` ### ### Clear the entire cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.clearCart()} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.clearCart(); }, }); root.append(tile); }); ``` ### ### Set the customer in the cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.setCustomer({ id: 1, })} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.setCustomer({ id: 1, }); }, }); root.append(tile); }); ``` ### ### Remove the customer in the cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.removeCustomer()} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.removeCustomer(); }, }); root.append(tile); }); ``` ### ### Add a custom sale to the cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.addCustomSale({ title: 'New product', quantity: 1, price: '10.00', taxable: true, })} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.addCustomSale({ title: 'New product', quantity: 1, price: '10.00', taxable: true, }); }, }); root.append(tile); }); ``` ### ### Add a line item to the cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.addLineItem(12345678, 1)} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.addLineItem(12345678, 1); }, }); root.append(tile); }); ``` ### ### Remove a line item from the cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.removeLineItem('aa-1234567')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.removeLineItem('aa-1234567'); }, }); root.append(tile); }); ``` ### ### Add custom properties to the cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.addCartProperties({Engraving: 'John Doe'})} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart action', enabled: true, onPress: () => { api.cart.addCartProperties({Engraving: 'John Doe'}); }, }); root.append(tile); }); ``` ### ### Remove custom properties from the cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.removeCartProperties(['Engraving'])} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.removeCartProperties(['Engraving']); }, }); root.append(tile); }); ``` ### ### Add custom properties to a line item ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.addLineItemProperties('aa-1234567', {Engraving: 'John Doe'})} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.addLineItemProperties('aa-1234567', {Engraving: 'John Doe'}); }, }); root.append(tile); }); ``` ### ### Add custom properties to multiple line items ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.bulkAddLineItemProperties([ {lineItemUuid: 'aa-1234567', properties: {Engraving: 'John Doe'}}, {lineItemUuid: 'bb-001234567', properties: {Engraving: 'Jane Doe'}} ])} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.bulkAddLineItemProperties([ {lineItemUuid: 'aa-1234567', properties: {Engraving: 'John Doe'}}, {lineItemUuid: 'bb-001234567', properties: {Engraving: 'Jane Doe'}}, ]); }, }); root.append(tile); }); ``` ### ### Remove custom properties from a line item ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.removeLineItemProperties('aa-1234567', ['Engraving'])} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.removeLineItemProperties('aa-1234567', ['Engraving']); }, }); root.append(tile); }); ``` ### ### Set an attributed staff member on the cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.setAttributedStaff(123456)} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.setAttributedStaff(123456); }, }); root.append(tile); }); ``` ### ### Set an attributed staff member on a line item ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.setAttributedStaffToLineItem(123456, 'aa-1234567')} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.setAttributedStaffToLineItem(123456, 'aa-1234567'); }, }); root.append(tile); }); ``` ### ### Add an address to the customer in the cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.addAddress({ address1: '123456 Main Street', city: 'Ottawa', province: 'Ontario', firstName: 'John', lastName: 'Doe', country: 'Canada' })} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.addAddress({ address1: '123456 Main Street', city: 'Ottawa', province: 'Ontario', firstName: 'John', lastName: 'Doe', country: 'Canada', }); }, }); root.append(tile); }); ``` ### ### Delete an address corresponding to an ID ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.deleteAddress(123456)} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.deleteAddress(123456); }, }); root.append(tile); }); ``` ### ### Set the default address of the customer in the cart ```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 ( <Tile title='My App' subtitle='Call cart function' enabled onPress={() => api.cart.updateDefaultAddress(123456)} /> ); }; export default reactExtension( 'pos.home.tile.render', () => <SmartGridTile /> ); ``` ```ts import {Tile, extension} from '@shopify/ui-extensions/point-of-sale'; export default extension('pos.home.tile.render', (root, api) => { const tile = root.createComponent(Tile, { title: 'My App', subtitle: 'Call cart function', enabled: true, onPress: () => { api.cart.updateDefaultAddress(123456); }, }); root.append(tile); }); ```