The POS API provides the ability to retrieve POS user, device, and location data, while also interacting with the cart and closing the app. > 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 [POS UI Extensions](/docs/apps/pos/ui-extensions).
await shopify.pos.cart.fetch();
Retrieve cart data and perform actions.
Add a new address to a customer.
Add properties for the cart.
Add custom sale for the cart.
Add a product to the cart.
Add properties to a line item.
Apply a code discount to the whole cart.
Apply a percentage or fixed amount discount to the whole cart.
Clear all contents from the cart.
Fetch the current cart.
Clears all applied discounts from the cart and optionally disables automatic discounts.
Remove the discount applied to the whole cart.
Remove properties from the cart.
Remove the current customer from the cart.
Remove a line item in the cart.
Remove a discount from a line item.
Remove properties from a line item.
Add a new or existing customer to the cart.
Apply a discount to a line item.
Subscribe the cart changes.
Update an address for a customer.
Make changes to a line item in the cart.
The customer's primary address.
Any extra information associated with the address (Apartment #, Suite #, Unit #, etc.).
The name of the customer's city.
The company name associated with address.
The country of the address.
The Country Code in ISO 3166-1 (alpha-2) format.
The first name of the customer.
The last name of the customer.
The name of the address.
The phone number of the customer.
The province or state of the address.
The acronym of the province or state.
The ZIP or postal code of the address.
Price of line item
Quantity of line item.
If line item charges tax.
Title of line item.
'Percentage' | 'FixedAmount'
The current discount applied to the entire cart.
All current discounts applied to the entire cart and line items.
The customer associated to the current cart.
The total cost of the current cart, after taxes and discounts have been applied. Value is based on the shop's existing currency settings.
A list of lineItem objects.
A list of objects containing cart properties.
The total cost of the current cart including discounts, but before taxes and shipping. Value is based on the shop's existing currency settings.
The sum of taxes for the current cart. Value is based on the shop's existing currency settings.
Amount of discount. Only for fixed or percentage discounts.
Description of discount.
Type of discount.
The email for a new customer.
The first name for new customer.
The ID of existing customer.
The last name for new customer.
The note for new customer.
Discount applied to line item.
If the line item is a gift card.
Price of line item
Product identifier for line item.
Properties of the line item.
Quantity of line item.
Stock keeping unit of the line item.
If line item charges tax.
Title of line item.
Unique id of line item
Variant identifier for line item.
Vendor of line item.
Callback to execute when cart updates.
cart: Cart
type CartSubscriber = (cart: Cart) => void;
Callback to unsubscribe
type Unsubscribe = () => void;
Close the app
type PosClose = () => Promise<void>;
Retrieve device data
type PosDevice = () => Promise<Device>;
The name of the device.
The unique ID associated device ID and app ID..
Retrieve location data
type PosLocation = () => Promise<Location>;
The status of current location.
The primary address of current location.
Any extra information associated with the address (Apartment #, Suite #, Unit #, etc.).
The name of the city.
The Country Code in ISO 3166-1 (alpha-2) format.
The country of the address.
The ID of current location.
The type of current location.
The name of current location.
The phone number of the location.
TThe province or state of the address.
The ZIP or postal code of the address.
Refer to the [user API](/docs/api/app-bridge-library/apis/user) to learn more about retrieving POS user data.
export type POSUserAPI = () => Promise<POSUser>;
The account access level of the logged-in user
The user's account type.
The user's email address.
The user's first name.
The ID of the user's staff.
The user's last name.
The POS API provides the ability to retrieve POS user, device, and location data, while also interacting with the cart and closing the app. > 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 [POS UI Extensions](/docs/apps/pos/ui-extensions).
await shopify.pos.cart.fetch();
await shopify.pos.cart.subscribe((cart) => {
console.log(cart);
});
await shopify.pos.cart.clear();
await shopify.pos.cart.addLineItem(40202439393345, 10);
const cart = await shopify.pos.cart.fetch();
const lineItemUuid = cart.lineItems[0].uuid;
await shopify.pos.cart.updateLineItem(lineItemUuid, 4);
const cart = await shopify.pos.cart.fetch();
const lineItemUuid = cart.lineItems[0].uuid;
await shopify.pos.cart.removeLineItem(lineItemUuid);
await shopify.pos.cart.addCustomSale({
price: 10,
quantity: 1,
title: 'Custom sale',
taxable: true,
});
await shopify.pos.cart.setCustomer({
email: 'foo@shopify.com',
firstName: 'Jane',
lastName: 'Doe',
note: 'Customer note',
});
await shopify.pos.cart.setCustomer({
id: 5945486803009,
note: 'Customer note',
});
await shopify.pos.cart.removeCustomer();
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',
});
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',
});
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',
});
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',
});
await shopify.pos.cart.applyCartDiscount('FixedAmount', 'Holiday sale', '10');
await shopify.pos.cart.applyCartCodeDiscount('HOLIDAY SALE');
await shopify.pos.cart.removeCartDiscount();
await shopify.pos.cart.removeAllDiscounts(true);
const cart = await shopify.pos.cart.fetch();
const lineItemUuid = cart.lineItems[0].uuid;
await shopify.pos.cart.setLineItemDiscount(
lineItemUuid,
'Percentage',
'Holiday sale',
'0.5',
);
const cart = await shopify.pos.cart.fetch();
const lineItemUuid = cart.lineItems[0].uuid;
await shopify.pos.cart.removeLineItemDiscount(lineItemUuid);
await shopify.pos.cart.addCartProperties({
referral: 'Shopify',
employee: '472',
});
await shopify.pos.cart.removeCartProperties(['referral', 'employee']);
const cart = await shopify.pos.cart.fetch();
const lineItemUuid = cart.lineItems[0].uuid;
await shopify.pos.cart.addLineItemProperties(lineItemUuid, {
referral: 'Shopify',
employee: '472',
});
const cart = await shopify.pos.cart.fetch();
const lineItemUuid = cart.lineItems[0].uuid;
await shopify.pos.cart.removeLineItemProperties(lineItemUuid, [
'referral',
'employee',
]);
const cart = await shopify.pos.cart.fetch();
const lineItemUuid = cart.lineItems[0].uuid;
await shopify.pos.cart.addLineItemProperties(lineItemUuid, {
referral: 'Shopify',
employee: '472',
});
const cart = await shopify.pos.cart.fetch();
const lineItemUuid = cart.lineItems[0].uuid;
await shopify.pos.cart.removeLineItemProperties(lineItemUuid, [
'referral',
'employee',
]);
await shopify.pos.close();
await shopify.pos.device();
await shopify.pos.location();