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 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 cart cart required: Provides methods to read and modify the current POS cart, including line items, discounts, customers, and properties.
Anchor to close close required: Closes the app and returns to the POS screen.
Anchor to device device required: Returns information about the POS device, including its name and serial number.
Anchor to location location required: 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 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
```

returns

void

Unsubscribe

Callback to unsubscribe

returns

void

PosClose

Close the app.

returns

Promise<void>

PosDevice

Retrieve device data.

returns

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.

returns

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
```

Examples

js

await shopify.pos.cart.fetch();

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();
```

Was this page helpful?