--- title: POS API description: >- The POS API provides comprehensive access to Point of Sale data and cart operations, enabling apps to retrieve device and location information, manage the cart during a sale, apply discounts, and handle customer data. This API supports individual and bulk cart operations for efficient transaction management. api_version: v1.0 source_url: html: >- https://shopify.dev/docs/api/app-home/latest/apis/device-and-platform-integration/pos-api md: >- https://shopify.dev/docs/api/app-home/latest/apis/device-and-platform-integration/pos-api.md api_name: app-home --- # POS API **Info:** App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version. The POS API provides comprehensive access to Point of Sale data and cart operations, enabling apps to retrieve device and location information, manage the cart during a sale, apply discounts, and handle customer data. This API supports individual and bulk cart operations for efficient transaction management. **Tip:** We recommend using [POS UI extensions](https://shopify.dev/docs/api/pos-ui-extensions/) for your development needs as they provide a faster, more robust, and easier to use solution for merchants using apps on POS. ### Use cases * **Cart management:** Add products, apply discounts, and manage the POS cart during a sale. * **Device information:** Access POS device and location data for context-aware operations. * **Customer management:** Associate customers with the current cart or look up customer information. * **Bulk operations:** Perform multiple cart operations efficiently using batch APIs. ### Methods Retrieve cart data and perform actions. * **cart** **PosCart** **required** Provides methods to read and modify the current POS cart, including line items, discounts, customers, and properties. * **close** **PosClose** **required** Closes the app and returns to the POS screen. * **device** **PosDevice** **required** Returns information about the POS device, including its name and serial number. * **location** **PosLocation** **required** Returns information about the current POS location, including its ID, name, address, and status. ### PosCart * addAddress Add a new address to a customer. ```ts (address: Address) => Promise ``` * addCartProperties Add properties for the cart. ```ts (properties: Record) => Promise ``` * addCustomSale Add custom sale for the cart. ```ts (customSale: CustomSale) => Promise ``` * addLineItem Add a product to the cart. ```ts (variantId: number, quantity: number) => Promise ``` * addLineItemProperties Add properties to a line item. ```ts (uuid: string, properties: Record) => Promise ``` * applyCartCodeDiscount Apply a code discount to the whole cart. ```ts (code: string) => Promise ``` * applyCartDiscount Apply a percentage or fixed amount discount to the whole cart. ```ts (type: DiscountType, discountDescription: string, amount: string) => Promise ``` * clear Clear all contents from the cart. ```ts () => Promise ``` * fetch Fetch the current cart. ```ts () => Promise ``` * removeAllDiscounts Clears all applied discounts from the cart and optionally disables automatic discounts. ```ts (disableAutomaticDiscounts: boolean) => Promise ``` * removeCartDiscount Remove the discount applied to the whole cart. ```ts () => Promise ``` * removeCartProperties Remove properties from the cart. ```ts (keys: string[]) => Promise ``` * removeCustomer Remove the current customer from the cart. ```ts () => Promise ``` * removeLineItem Remove a line item in the cart. ```ts (uuid: string) => Promise ``` * removeLineItemDiscount Remove a discount from a line item. ```ts (uuid: string) => Promise ``` * removeLineItemProperties Remove properties from a line item. ```ts (uuid: string, properties: string[]) => Promise ``` * setCustomer Add a new or existing customer to the cart. ```ts (customer: Customer) => Promise ``` * setLineItemDiscount Apply a discount to a line item. ```ts (uuid: string, type: DiscountType, discountDescription: string, amount: string) => Promise ``` * subscribe Subscribe the cart changes. ```ts (onSubscribe: CartSubscriber) => Unsubscribe ``` * updateAddress Update an address for a customer. ```ts (index: number, address: Address) => Promise ``` * updateLineItem Make changes to a line item in the cart. ```ts (uuid: string, quantity: number) => Promise ``` ### Address * address1 The customer's primary address. ```ts string ``` * address2 Any extra information associated with the address (Apartment #, Suite #, Unit #, etc.). ```ts string ``` * city The name of the customer's city. ```ts string ``` * company The company name associated with address. ```ts string ``` * country The country of the address. ```ts string ``` * countryCode The Country Code in ISO 3166-1 (alpha-2) format. ```ts string ``` * firstName The first name of the customer. ```ts string ``` * lastName The last name of the customer. ```ts string ``` * name The name of the address. ```ts string ``` * phone The phone number of the customer. ```ts string ``` * province The province or state of the address. ```ts string ``` * provinceCode The acronym of the province or state. ```ts string ``` * zip The ZIP or postal code of the address. ```ts string ``` ### CustomSale * price Price of line item ```ts number ``` * quantity Quantity of line item. ```ts number ``` * taxable If line item charges tax. ```ts boolean ``` * title Title of line item. ```ts string ``` ### DiscountType ```ts 'Percentage' | 'FixedAmount' ``` ### Cart * cartDiscount The current discount applied to the entire cart. ```ts Discount ``` * cartDiscounts All current discounts applied to the entire cart and line items. ```ts Discount[] ``` * customer The customer associated to the current cart. ```ts Customer ``` * grandTotal The total cost of the current cart, after taxes and discounts have been applied. Value is based on the shop's existing currency settings. ```ts string ``` * lineItems A list of lineItem objects. ```ts LineItem[] ``` * properties A list of objects containing cart properties. ```ts Record ``` * subTotal The total cost of the current cart including discounts, but before taxes and shipping. Value is based on the shop's existing currency settings. ```ts string ``` * taxTotal The sum of taxes for the current cart. Value is based on the shop's existing currency settings. ```ts string ``` ### Discount * amount Amount of discount. Only for fixed or percentage discounts. ```ts number ``` * discountDescription Description of discount. ```ts string ``` * type Type of discount. ```ts DiscountType ``` ### Customer * email The email for a new customer. ```ts string ``` * firstName The first name for new customer. ```ts string ``` * id The ID of existing customer. ```ts number ``` * lastName The last name for new customer. ```ts string ``` * note The note for new customer. ```ts string ``` ### LineItem * discounts Discount applied to line item. ```ts Discount[] ``` * isGiftCard If the line item is a gift card. ```ts boolean ``` * price Price of line item ```ts number ``` * productId Product identifier for line item. ```ts number ``` * properties Properties of the line item. ```ts { [key: string]: string; } ``` * quantity Quantity of line item. ```ts number ``` * sku Stock keeping unit of the line item. ```ts string ``` * taxable If line item charges tax. ```ts boolean ``` * title Title of line item. ```ts string ``` * uuid Unique id of line item ```ts string ``` * variantId Variant identifier for line item. ```ts number ``` * vendor Vendor of line item. ```ts string ``` ### CartSubscriber Callback to execute when cart updates. * cart ```ts Cart ``` returns ```ts void ``` ### Unsubscribe Callback to unsubscribe returns ```ts void ``` ### PosClose Close the app. returns ```ts Promise ``` ### PosDevice Retrieve device data. returns ```ts Promise ``` ### Device * name The name of the device. ```ts string ``` * serialNumber The unique ID associated device ID and app ID.. ```ts string ``` ### PosLocation Retrieve location data. returns ```ts Promise ``` ### Location * active The status of current location. ```ts boolean ``` * address1 The primary address of current location. ```ts string ``` * address2 Any extra information associated with the address (Apartment #, Suite #, Unit #, etc.). ```ts string ``` * city The name of the city. ```ts string ``` * countryCode The Country Code in ISO 3166-1 (alpha-2) format. ```ts string ``` * countryName The country of the address. ```ts string ``` * id The ID of current location. ```ts number ``` * locationType The type of current location. ```ts string ``` * name The name of current location. ```ts string ``` * phone The phone number of the location. ```ts string ``` * province TThe province or state of the address. ```ts string ``` * zip The ZIP or postal code of the address. ```ts string ``` Examples ### Examples * #### ##### Description Retrieve current cart data. This example fetches the cart object containing line items, customer, and totals. ##### js ```js await shopify.pos.cart.fetch(); ``` * #### ##### Description Listen for cart changes. This example subscribes to a callback that fires whenever the cart is updated. ##### js ```js await shopify.pos.cart.subscribe((cart) => { console.log(cart); }); ``` * #### ##### Description Reset the cart to an empty state. This example clears all items, customer, and discounts from the cart. ##### js ```js await shopify.pos.cart.clear(); ``` * #### ##### Description Manage products in the cart. This example adds a variant by ID, updates quantity using the line item UUID, and removes items. ##### Add line item ```js await shopify.pos.cart.addLineItem(40202439393345, 10); ``` ##### Update line item ```js const cart = await shopify.pos.cart.fetch(); const lineItemUuid = cart.lineItems[0].uuid; await shopify.pos.cart.updateLineItem(lineItemUuid, 4); ``` ##### Remove line item ```js const cart = await shopify.pos.cart.fetch(); const lineItemUuid = cart.lineItems[0].uuid; await shopify.pos.cart.removeLineItem(lineItemUuid); ``` * #### ##### Description Add items without a product variant. This example creates a custom sale with a price, quantity, title, and tax setting. ##### Add custom sale ```js await shopify.pos.cart.addCustomSale({ price: 10, quantity: 1, title: 'Custom sale', taxable: true, }); ``` * #### ##### Description Apply discounts to specific items. This example sets a percentage or fixed discount on a line item using its UUID. ##### Add line item discount ```js const cart = await shopify.pos.cart.fetch(); const lineItemUuid = cart.lineItems[0].uuid; await shopify.pos.cart.setLineItemDiscount( lineItemUuid, 'Percentage', 'Holiday sale', '0.5', ); ``` ##### Remove line item discount ```js const cart = await shopify.pos.cart.fetch(); const lineItemUuid = cart.lineItems[0].uuid; await shopify.pos.cart.removeLineItemDiscount(lineItemUuid); ``` * #### ##### Description Attach custom metadata to items. This example adds and removes key-value properties on a line item. ##### Add line item properties ```js const cart = await shopify.pos.cart.fetch(); const lineItemUuid = cart.lineItems[0].uuid; await shopify.pos.cart.addLineItemProperties(lineItemUuid, { referral: 'Shopify', employee: '472', }); ``` ##### Remove line item properties ```js const cart = await shopify.pos.cart.fetch(); const lineItemUuid = cart.lineItems[0].uuid; await shopify.pos.cart.removeLineItemProperties(lineItemUuid, [ 'referral', 'employee', ]); ``` * #### ##### Description Associate a customer with the cart. This example sets a customer by email or ID, or removes an existing customer. ##### Add a customer by email ```js await shopify.pos.cart.setCustomer({ email: 'foo@shopify.com', firstName: 'Jane', lastName: 'Doe', note: 'Customer note', }); ``` ##### Add a customer by ID ```js await shopify.pos.cart.setCustomer({ id: 5945486803009, note: 'Customer note', }); ``` ##### Remove customer ```js await shopify.pos.cart.removeCustomer(); ``` * #### ##### Description Manage customer addresses. This example adds a new address and updates an existing address by index. ##### Add a customer address ```js await shopify.pos.cart.addAddress({ address1: '123 Cherry St.', address2: 'Apt. 5', city: 'Toronto', company: 'Shopify', firstName: 'Foo', lastName: 'Bar', phone: '(613) 555-5555', province: 'Ontario', country: 'Canada', zip: 'M5V0G4', name: 'Shopify', provinceCode: 'M5V0G4', countryCode: '1', }); ``` ##### Update customer address ```js await shopify.pos.cart.updateAddress(0, { address1: '555 Apple St.', address2: 'Unit. 10', city: 'Vancouver', company: 'Shopify', firstName: 'Jane', lastName: 'Doe', phone: '(403) 555-5555', province: 'British Columbia', country: 'Canada', zip: 'M5V0G4', name: 'Shopify', provinceCode: 'M5V0G4', countryCode: '2', }); ``` * #### ##### Description Apply discounts to the entire cart. This example adds fixed or percentage discounts, applies discount codes, and removes discounts. ##### Add cart discount ```js await shopify.pos.cart.applyCartDiscount('FixedAmount', 'Holiday sale', '10'); ``` ##### Add discount code ```js await shopify.pos.cart.applyCartCodeDiscount('HOLIDAY SALE'); ``` ##### Remove cart discount ```js await shopify.pos.cart.removeCartDiscount(); ``` ##### Remove all discounts ```js await shopify.pos.cart.removeAllDiscounts(true); ``` * #### ##### Description Attach custom metadata to the cart. This example adds and removes key-value properties on the cart object. ##### Add cart properties ```js await shopify.pos.cart.addCartProperties({ referral: 'Shopify', employee: '472', }); ``` ##### Remove cart properties ```js await shopify.pos.cart.removeCartProperties(['referral', 'employee']); ``` * #### ##### Description Retrieve POS device information. This example gets the device name and serial number. ##### js ```js await shopify.pos.device(); ``` * #### ##### Description Retrieve POS location information. This example gets the location ID, name, and status. ##### js ```js await shopify.pos.location(); ``` * #### ##### Description Dismiss the app screen. This example programmatically closes the app and returns to POS. ##### js ```js await shopify.pos.close(); ``` ***