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.
Anchor to cartCart
Retrieve cart data and perform actions.
- Anchor to addAddressaddAddress(address: ) => Promise<void>
Add a new address to a customer.
- Anchor to addCartPropertiesaddCartProperties(properties: Record<string, string>) => Promise<void>
Add properties for the cart.
- Anchor to addCustomSaleaddCustomSale(customSale: ) => Promise<void>
Add custom sale for the cart.
- Anchor to addLineItemaddLineItem(variantId: number, quantity: number) => Promise<void>
Add a product to the cart.
- Anchor to addLineItemPropertiesaddLineItemProperties(uuid: string, properties: Record<string, string>) => Promise<void>
Add properties to a line item.
- Anchor to applyCartCodeDiscountapplyCartCodeDiscount(code: string) => Promise<void>
Apply a code discount to the whole cart.
- Anchor to applyCartDiscountapplyCartDiscount(type: , discountDescription: string, amount: string) => Promise<void>
Apply a percentage or fixed amount discount to the whole cart.
- Anchor to clearclear() => Promise<void>
Clear all contents from the cart.
- Anchor to fetchfetch() => Promise<>
Fetch the current cart.
- Anchor to removeAllDiscountsremoveAllDiscounts(disableAutomaticDiscounts: boolean) => Promise<void>
Clears all applied discounts from the cart and optionally disables automatic discounts.
- Anchor to removeCartDiscountremoveCartDiscount() => Promise<void>
Remove the discount applied to the whole cart.
- Anchor to removeCartPropertiesremoveCartProperties(keys: string[]) => Promise<void>
Remove properties from the cart.
- Anchor to removeCustomerremoveCustomer() => Promise<void>
Remove the current customer from the cart.
- Anchor to removeLineItemremoveLineItem(uuid: string) => Promise<void>
Remove a line item in the cart.
- Anchor to removeLineItemDiscountremoveLineItemDiscount(uuid: string) => Promise<void>
Remove a discount from a line item.
- Anchor to removeLineItemPropertiesremoveLineItemProperties(uuid: string, properties: string[]) => Promise<void>
Remove properties from a line item.
- Anchor to setCustomersetCustomer(customer: ) => Promise<void>
Add a new or existing customer to the cart.
- Anchor to setLineItemDiscountsetLineItemDiscount(uuid: string, type: , discountDescription: string, amount: string) => Promise<void>
Apply a discount to a line item.
- Anchor to subscribesubscribe(onSubscribe: ) =>
Subscribe the cart changes.
- Anchor to updateAddressupdateAddress(index: number, address: ) => Promise<void>
Update an address for a customer.
- Anchor to updateLineItemupdateLineItem(uuid: string, quantity: number) => Promise<void>
Make changes to a line item in the cart.
_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>
interface _PosCart {
/**
* Fetch the current cart.
*/
fetch?(): Promise<Cart>;
/**
* Subscribe the cart changes.
*/
subscribe?(onSubscribe: CartSubscriber): Unsubscribe;
/**
* Add a new or existing customer to the cart.
*/
setCustomer?(customer: Customer): Promise<void>;
/**
* Remove the current customer from the cart.
*/
removeCustomer?(): Promise<void>;
/**
* Add a new address to a customer.
*/
addAddress?(address: Address): Promise<void>;
/**
* Update an address for a customer.
*/
updateAddress?(index: number, address: Address): Promise<void>;
/**
* Apply a percentage or fixed amount discount to the whole cart.
*/
applyCartDiscount?(
type: DiscountType,
discountDescription: string,
amount: string,
): Promise<void>;
/**
* Apply a code discount to the whole cart.
*/
applyCartCodeDiscount?(code: string): Promise<void>;
/**
* Remove the discount applied to the whole cart.
*/
removeCartDiscount?(): Promise<void>;
/**
* Clears all applied discounts from the cart and optionally disables automatic discounts.
*/
removeAllDiscounts?(disableAutomaticDiscounts: boolean): Promise<void>;
/**
* Add properties for the cart.
*/
addCartProperties?(properties: Record<string, string>): Promise<void>;
/**
* Remove properties from the cart.
*/
removeCartProperties?(keys: string[]): Promise<void>;
/**
* Add custom sale for the cart.
*/
addCustomSale?(customSale: CustomSale): Promise<void>;
/**
* Clear all contents from the cart.
*/
clear?(): Promise<void>;
/**
* Add a product to the cart.
*/
addLineItem?(variantId: number, quantity: number): Promise<void>;
/**
* Make changes to a line item in the cart.
*/
updateLineItem?(uuid: string, quantity: number): Promise<void>;
/**
* Remove a line item in the cart.
*/
removeLineItem?(uuid: string): Promise<void>;
/**
* Apply a discount to a line item.
*/
setLineItemDiscount?(
uuid: string,
type: DiscountType,
discountDescription: string,
amount: string,
): Promise<void>;
/**
* Remove a discount from a line item.
*/
removeLineItemDiscount?(uuid: string): Promise<void>;
/**
* Add properties to a line item.
*/
addLineItemProperties?(
uuid: string,
properties: Record<string, string>,
): Promise<void>;
/**
* Remove properties from a line item.
*/
removeLineItemProperties?(uuid: string, properties: string[]): 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
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) => void
Unsubscribe
Callback to unsubscribe
void
() => void
Anchor to CloseClose()
Close the app
Anchor to Close-returnsReturns
PosClose
Promise<void>
() => Promise<void>
Anchor to DeviceDevice()
Retrieve device data
Anchor to Device-returnsReturns
PosDevice
Promise<Device>
() => Promise<Device>
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
PosLocation
Promise<Location>
() => 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
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
POSUserAPI
Promise<POSUser>
() => Promise<POSUser>
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;
}
Fetch the POS cart
examples
Fetch the POS cart
await shopify.pos.cart.fetch();
Anchor to examplesExamples
Examples for retrieving and interacting with data on the POS
Anchor to example-fetch-the-cartFetch the cart
Anchor to example-subscribe-to-cart-updatesSubscribe to cart updates
Anchor to example-clear-the-cartClear the cart
Anchor to example-line-itemsLine Items
Anchor to example-custom-saleCustom Sale
Anchor to example-customersCustomers
Anchor to example-addressesAddresses
Anchor to example-cart-discountsCart Discounts
Anchor to example-line-item-discountsLine Item Discounts
Anchor to example-cart-propertiesCart Properties
Anchor to example-line-item-propertiesLine Item Properties
Fetch the cart
examples
Fetch the cart
await shopify.pos.cart.fetch();
Subscribe to cart updates
await shopify.pos.cart.subscribe((cart) => { console.log(cart); });
Clear the cart
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', ]);
Anchor to example-dismiss-the-screenDismiss the screen
Dismiss the screen
examples
Dismiss the screen
await shopify.pos.close();
Anchor to example-deviceDevice
Anchor to example-retrieve-pos-device-dataRetrieve POS device data
Retrieve POS device data
examples
Retrieve POS device data
await shopify.pos.device();
Anchor to example-locationLocation
Anchor to example-retrieve-pos-location-dataRetrieve POS location data
Retrieve POS location data
examples
Retrieve POS location data
await shopify.pos.location();