POS
The POS API provides the ability to retrieve POS user, device, and location data, while also interacting with the cart and closing the app.
It is recommended to use 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. To learn more about the benefits and implementation details, refer to POS UI Extensions.
It is recommended to use 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. To learn more about the benefits and implementation details, refer to POS UI Extensions.
Tip: It is recommended to use 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. To learn more about the benefits and implementation details, refer to <a href="/docs/apps/pos/ui-extensions">POS UI Extensions</a>.
Anchor to cartCart
Retrieve cart data and perform actions.
- Anchor to addAddressaddAddressaddAddress(address: Address) => Promise<void>(address: Address) => Promise<void>
Add a new address to a customer.
- Anchor to addCartPropertiesaddCartPropertiesaddCartProperties(properties: Record<string, string>) => Promise<void>(properties: Record<string, string>) => Promise<void>
Add properties for the cart.
- Anchor to addCustomSaleaddCustomSaleaddCustomSale(customSale: CustomSale) => Promise<void>(customSale: CustomSale) => Promise<void>
Add custom sale for the cart.
- Anchor to addLineItemaddLineItemaddLineItem(variantId: number, quantity: number) => Promise<void>(variantId: number, quantity: number) => Promise<void>
Add a product to the cart.
- Anchor to addLineItemPropertiesaddLineItemPropertiesaddLineItemProperties(uuid: string, properties: Record<string, string>) => Promise<void>(uuid: string, properties: Record<string, string>) => Promise<void>
Add properties to a line item.
- Anchor to applyCartCodeDiscountapplyCartCodeDiscountapplyCartCodeDiscount(code: string) => Promise<void>(code: string) => Promise<void>
Apply a code discount to the whole cart.
- Anchor to applyCartDiscountapplyCartDiscountapplyCartDiscount(type: DiscountType, discountDescription: string, amount: string) => Promise<void>(type: DiscountType, discountDescription: string, amount: string) => Promise<void>
Apply a percentage or fixed amount discount to the whole cart.
- Anchor to clearclearclear() => Promise<void>() => Promise<void>
Clear all contents from the cart.
- Anchor to fetchfetchfetch() => Promise<Cart>() => Promise<Cart>
Fetch the current cart.
- Anchor to removeAllDiscountsremoveAllDiscountsremoveAllDiscounts(disableAutomaticDiscounts: boolean) => Promise<void>(disableAutomaticDiscounts: boolean) => Promise<void>
Clears all applied discounts from the cart and optionally disables automatic discounts.
- Anchor to removeCartDiscountremoveCartDiscountremoveCartDiscount() => Promise<void>() => Promise<void>
Remove the discount applied to the whole cart.
- Anchor to removeCartPropertiesremoveCartPropertiesremoveCartProperties(keys: string[]) => Promise<void>(keys: string[]) => Promise<void>
Remove properties from the cart.
- Anchor to removeCustomerremoveCustomerremoveCustomer() => Promise<void>() => Promise<void>
Remove the current customer from the cart.
- Anchor to removeLineItemremoveLineItemremoveLineItem(uuid: string) => Promise<void>(uuid: string) => Promise<void>
Remove a line item in the cart.
- Anchor to removeLineItemDiscountremoveLineItemDiscountremoveLineItemDiscount(uuid: string) => Promise<void>(uuid: string) => Promise<void>
Remove a discount from a line item.
- Anchor to removeLineItemPropertiesremoveLineItemPropertiesremoveLineItemProperties(uuid: string, properties: string[]) => Promise<void>(uuid: string, properties: string[]) => Promise<void>
Remove properties from a line item.
- Anchor to setCustomersetCustomersetCustomer(customer: Customer) => Promise<void>(customer: Customer) => Promise<void>
Add a new or existing customer to the cart.
- Anchor to setLineItemDiscountsetLineItemDiscountsetLineItemDiscount(uuid: string, type: DiscountType, discountDescription: string, amount: string) => Promise<void>(uuid: string, type: DiscountType, discountDescription: string, amount: string) => Promise<void>
Apply a discount to a line item.
- Anchor to subscribesubscribesubscribe(onSubscribe: CartSubscriber) => Unsubscribe(onSubscribe: CartSubscriber) => Unsubscribe
Subscribe the cart changes.
- Anchor to updateAddressupdateAddressupdateAddress(index: number, address: Address) => Promise<void>(index: number, address: Address) => Promise<void>
Update an address for a customer.
- Anchor to updateLineItemupdateLineItemupdateLineItem(uuid: string, quantity: number) => Promise<void>(uuid: string, quantity: number) => Promise<void>
Make changes to a line item in the cart.
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
interface Address {
/**
* The customer's primary address.
*/
address1?: string;
/**
* Any extra information associated with the address (Apartment #, Suite #, Unit #, etc.).
*/
address2?: string;
/**
* The name of the customer's city.
*/
city?: string;
/**
* The company name associated with address.
*/
company?: string;
/**
* The first name of the customer.
*/
firstName?: string;
/**
* The last name of the customer.
*/
lastName?: string;
/**
* The phone number of the customer.
*/
phone?: string;
/**
* The province or state of the address.
*/
province?: string;
/**
* The country of the address.
*/
country?: string;
/**
* The ZIP or postal code of the address.
*/
zip?: string;
/**
* The name of the address.
*/
name?: string;
/**
* The acronym of the province or state.
*/
provinceCode?: string;
/**
* The Country Code in ISO 3166-1 (alpha-2) format.
*/
countryCode?: 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
interface CustomSale {
/**
* Price of line item
*/
price: number;
/**
* Quantity of line item.
*/
quantity: number;
/**
* Title of line item.
*/
title: string;
/**
* If line item charges tax.
*/
taxable: boolean;
}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
interface Cart {
/**
* The total cost of the current cart including discounts, but before taxes and shipping. Value is based on the shop's existing currency settings.
*/
subTotal: string;
/**
* The sum of taxes for the current cart. Value is based on the shop's existing currency settings.
*/
taxTotal: string;
/**
* The total cost of the current cart, after taxes and discounts have been applied. Value is based on the shop's existing currency settings.
*/
grandTotal: string;
/**
* The current discount applied to the entire cart.
*/
cartDiscount?: Discount;
/**
* All current discounts applied to the entire cart and line items.
*/
cartDiscounts?: Discount[];
/**
* The customer associated to the current cart.
*/
customer?: Customer;
/**
* A list of lineItem objects.
*/
lineItems: LineItem[];
/**
* A list of objects containing cart properties.
*/
properties: Record<string, string>;
}Discount
- amount
Amount of discount. Only for fixed or percentage discounts.
number - discountDescription
Description of discount.
string - type
Type of discount.
DiscountType
interface Discount {
/**
* Amount of discount. Only for fixed or percentage discounts.
*/
amount: number;
/**
* Description of discount.
*/
discountDescription?: string;
/**
* Type of discount.
*/
type: 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
interface Customer {
/**
* The ID of existing customer.
*/
id: number;
/**
* The email for a new customer.
*/
email?: string;
/**
* The first name for new customer.
*/
firstName?: string;
/**
* The last name for new customer.
*/
lastName?: string;
/**
* The note for new customer.
*/
note?: 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
interface LineItem {
/**
* Unique id of line item
*/
uuid: string;
/**
* Price of line item
*/
price?: number;
/**
* Quantity of line item.
*/
quantity: number;
/**
* Title of line item.
*/
title?: string;
/**
* Variant identifier for line item.
*/
variantId?: number;
/**
* Product identifier for line item.
*/
productId?: number;
/**
* Discount applied to line item.
*/
discounts: Discount[];
/**
* If line item charges tax.
*/
taxable: boolean;
/**
* Stock keeping unit of the line item.
*/
sku?: string;
/**
* Vendor of line item.
*/
vendor?: string;
/**
* Properties of the line item.
*/
properties: {[key: string]: string};
/**
* If the line item is a gift card.
*/
isGiftCard: boolean;
}CartSubscriber
Callback to execute when cart updates.
- cart
Cart
void(cart: Cart) => voidUnsubscribe
Callback to unsubscribe
void() => voidAnchor to CloseClose()
Close the app
Anchor to Close-returnsReturns
Anchor to DeviceDevice()
Retrieve device data
Anchor to Device-returnsReturns
Device
- name
The name of the device.
string - serialNumber
The unique ID associated device ID and app ID..
string
interface Device {
/**
* The name of the device.
*/
name: string;
/**
* The unique ID associated device ID and app ID..
*/
serialNumber: string;
}Anchor to LocationLocation()
Retrieve location data
Anchor to Location-returnsReturns
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
interface Location {
/**
* The ID of current location.
*/
id: number;
/**
* The status of current location.
*/
active: boolean;
/**
* The name of current location.
*/
name: string;
/**
* The type of current location.
*/
locationType?: string;
/**
* The primary address of current location.
*/
address1?: string;
/**
* Any extra information associated with the address (Apartment #, Suite #, Unit #, etc.).
*/
address2?: string;
/**
* The ZIP or postal code of the address.
*/
zip?: string;
/**
* The name of the city.
*/
city?: string;
/**
* TThe province or state of the address.
*/
province?: string;
/**
* The Country Code in ISO 3166-1 (alpha-2) format.
*/
countryCode?: string;
/**
* The country of the address.
*/
countryName?: string;
/**
* The phone number of the location.
*/
phone?: string;
}Anchor to UserUser()
Refer to the user API to learn more about retrieving POS user data.
Anchor to User-returnsReturns
POSUser
- accountAccess
The account access level of the logged-in user
string - accountType
The user's account type.
string - email
The user's email address.
string - firstName
The user's first name.
string - id
The ID of the user's staff.
number - lastName
The user's last name.
string
export interface POSUser {
/**
* The ID of the user's staff.
*/
id?: number;
/**
* The user's first name.
*/
firstName?: string;
/**
* The user's last name.
*/
lastName?: string;
/**
* The user's email address.
*/
email?: string;
/**
* The account access level of the logged-in user
*/
accountAccess?: string;
/**
* The user's account type.
*/
accountType?: string;
}Preview
Examples
Fetch the POS cart
Default
await shopify.pos.cart.fetch();Fetch the cart
Default
await shopify.pos.cart.fetch();Subscribe to cart updates
Default
await shopify.pos.cart.subscribe((cart) => { console.log(cart); });Clear the cart
Default
await shopify.pos.cart.clear();Line 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);Custom Sale
Add custom sale
await shopify.pos.cart.addCustomSale({ price: 10, quantity: 1, title: 'Custom sale', taxable: true, });Customers
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();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', });Addresses
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', });Cart Discounts
Add cart discount
await shopify.pos.cart.applyCartDiscount('FixedAmount', 'Holiday sale', '10');Add dicount code
await shopify.pos.cart.applyCartCodeDiscount('HOLIDAY SALE');Remove cart discount
await shopify.pos.cart.removeCartDiscount();Remove all discounts with automatic discounts disabled
await shopify.pos.cart.removeAllDiscounts(true);Line Item Discounts
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);Cart Properties
Add cart properties
await shopify.pos.cart.addCartProperties({ referral: 'Shopify', employee: '472', });Remove cart properties
await shopify.pos.cart.removeCartProperties(['referral', 'employee']);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', ]);Line Item Properties
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', ]);Dismiss the screen
Default
await shopify.pos.close();Retrieve POS device data
Default
await shopify.pos.device();Retrieve POS location data
Default
await shopify.pos.location();