--- 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 api_name: app-home source_url: html: >- https://shopify.dev/docs/api/app-home/apis/device-and-platform-integration/pos-api md: >- https://shopify.dev/docs/api/app-home/apis/device-and-platform-integration/pos-api.md --- # POS API 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(); ``` ***