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.
We recommend using 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.
We recommend using 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.
Anchor to Use casesUse 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.
Anchor to MethodsMethods
Retrieve cart data and perform actions.
- Anchor to cartcartcartPosCartPosCartrequiredrequired
Provides methods to read and modify the current POS cart, including line items, discounts, customers, and properties.
- Anchor to closecloseclosePosClosePosCloserequiredrequired
Closes the app and returns to the POS screen.
- Anchor to devicedevicedevicePosDevicePosDevicerequiredrequired
Returns information about the POS device, including its name and serial number.
- Anchor to locationlocationlocationPosLocationPosLocationrequiredrequired
Returns information about the current POS location, including its ID, name, address, and status.
PosCart
- addAddress
Add a new address to a customer.
(address: Address) => Promise<void> - addCartProperties
Add properties for the cart.
(properties: Record<string, string>) => Promise<void> - addCustomSale
Add custom sale for the cart.
(customSale: CustomSale) => Promise<void> - addLineItem
Add a product to the cart.
(variantId: number, quantity: number) => Promise<void> - addLineItemProperties
Add properties to a line item.
(uuid: string, properties: Record<string, string>) => Promise<void> - applyCartCodeDiscount
Apply a code discount to the whole cart.
(code: string) => Promise<void> - applyCartDiscount
Apply a percentage or fixed amount discount to the whole cart.
(type: DiscountType, discountDescription: string, amount: string) => Promise<void> - clear
Clear all contents from the cart.
() => Promise<void> - fetch
Fetch the current cart.
() => Promise<Cart> - removeAllDiscounts
Clears all applied discounts from the cart and optionally disables automatic discounts.
(disableAutomaticDiscounts: boolean) => Promise<void> - removeCartDiscount
Remove the discount applied to the whole cart.
() => Promise<void> - removeCartProperties
Remove properties from the cart.
(keys: string[]) => Promise<void> - removeCustomer
Remove the current customer from the cart.
() => Promise<void> - removeLineItem
Remove a line item in the cart.
(uuid: string) => Promise<void> - removeLineItemDiscount
Remove a discount from a line item.
(uuid: string) => Promise<void> - removeLineItemProperties
Remove properties from a line item.
(uuid: string, properties: string[]) => Promise<void> - setCustomer
Add a new or existing customer to the cart.
(customer: Customer) => Promise<void> - setLineItemDiscount
Apply a discount to a line item.
(uuid: string, type: DiscountType, discountDescription: string, amount: string) => Promise<void> - subscribe
Subscribe the cart changes.
(onSubscribe: CartSubscriber) => Unsubscribe - updateAddress
Update an address for a customer.
(index: number, address: Address) => Promise<void> - updateLineItem
Make changes to a line item in the cart.
(uuid: string, quantity: number) => Promise<void>
Address
- address1
The customer's primary address.
string - address2
Any extra information associated with the address (Apartment #, Suite #, Unit #, etc.).
string - city
The name of the customer's city.
string - company
The company name associated with address.
string - country
The country of the address.
string - countryCode
The Country Code in ISO 3166-1 (alpha-2) format.
string - firstName
The first name of the customer.
string - lastName
The last name of the customer.
string - name
The name of the address.
string - phone
The phone number of the customer.
string - province
The province or state of the address.
string - provinceCode
The acronym of the province or state.
string - zip
The ZIP or postal code of the address.
string
CustomSale
- price
Price of line item
number - quantity
Quantity of line item.
number - taxable
If line item charges tax.
boolean - title
Title of line item.
string
DiscountType
'Percentage' | 'FixedAmount'Cart
- cartDiscount
The current discount applied to the entire cart.
Discount - cartDiscounts
All current discounts applied to the entire cart and line items.
Discount[] - customer
The customer associated to the current cart.
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.
string - lineItems
A list of lineItem objects.
LineItem[] - properties
A list of objects containing cart properties.
Record<string, string> - 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.
string - taxTotal
The sum of taxes for the current cart. Value is based on the shop's existing currency settings.
string
Discount
- amount
Amount of discount. Only for fixed or percentage discounts.
number - discountDescription
Description of discount.
string - type
Type of discount.
DiscountType
Customer
- email
The email for a new customer.
string - firstName
The first name for new customer.
string - id
The ID of existing customer.
number - lastName
The last name for new customer.
string - note
The note for new customer.
string
LineItem
- discounts
Discount applied to line item.
Discount[] - isGiftCard
If the line item is a gift card.
boolean - price
Price of line item
number - productId
Product identifier for line item.
number - properties
Properties of the line item.
{ [key: string]: string; } - quantity
Quantity of line item.
number - sku
Stock keeping unit of the line item.
string - taxable
If line item charges tax.
boolean - title
Title of line item.
string - uuid
Unique id of line item
string - variantId
Variant identifier for line item.
number - vendor
Vendor of line item.
string
CartSubscriber
Callback to execute when cart updates.
- cart
Cart
voidUnsubscribe
Callback to unsubscribe
voidPosClose
Close the app.
Promise<void>PosDevice
Retrieve device data.
Promise<Device>Device
- name
The name of the device.
string - serialNumber
The unique ID associated device ID and app ID..
string
PosLocation
Retrieve location data.
Promise<Location>Location
- active
The status of current location.
boolean - address1
The primary address of current location.
string - address2
Any extra information associated with the address (Apartment #, Suite #, Unit #, etc.).
string - city
The name of the city.
string - countryCode
The Country Code in ISO 3166-1 (alpha-2) format.
string - countryName
The country of the address.
string - id
The ID of current location.
number - locationType
The type of current location.
string - name
The name of current location.
string - phone
The phone number of the location.
string - province
TThe province or state of the address.
string - zip
The ZIP or postal code of the address.
string
js
Examples
Description
Retrieve current cart data. This example fetches the cart object containing line items, customer, and totals.
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
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
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
await shopify.pos.cart.addLineItem(40202439393345, 10);Update line item
const cart = await shopify.pos.cart.fetch(); const lineItemUuid = cart.lineItems[0].uuid; await shopify.pos.cart.updateLineItem(lineItemUuid, 4);Remove line item
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
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
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
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
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
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
await shopify.pos.cart.setCustomer({ email: 'foo@shopify.com', firstName: 'Jane', lastName: 'Doe', note: 'Customer note', });Add a customer by ID
await shopify.pos.cart.setCustomer({ id: 5945486803009, note: 'Customer note', });Remove customer
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
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
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
await shopify.pos.cart.applyCartDiscount('FixedAmount', 'Holiday sale', '10');Add discount code
await shopify.pos.cart.applyCartCodeDiscount('HOLIDAY SALE');Remove cart discount
await shopify.pos.cart.removeCartDiscount();Remove all discounts
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
await shopify.pos.cart.addCartProperties({ referral: 'Shopify', employee: '472', });Remove cart properties
await shopify.pos.cart.removeCartProperties(['referral', 'employee']);Description
Retrieve POS device information. This example gets the device name and serial number.
js
await shopify.pos.device();Description
Retrieve POS location information. This example gets the location ID, name, and status.
js
await shopify.pos.location();Description
Dismiss the app screen. This example programmatically closes the app and returns to POS.
js
await shopify.pos.close();