Skip to main content

Cart API
APIs

The Cart API enables UI Extensions to manage and interact with POS cart contents, such as discounts, line items, and customer details. It provides a comprehensive set of functions for adding and removing items, alongside a subscribable object that keeps the UI Extension updated with real-time changes to the cart.

Supporting targets

Anchor to cartapiCartApi

Anchor to addAddress
addAddress
(address: ) => Promise<void>
required

Add an address to the customer (Customer must be present)

Anchor to addCartCodeDiscount
addCartCodeDiscount
(code: string) => Promise<void>
required

Add a code discount to the cart

Anchor to addCartProperties
addCartProperties
(properties: Record<string, string>) => Promise<void>
required

Adds custom properties to the cart

Anchor to addCustomSale
addCustomSale
(customSale: ) => Promise<string>
required

Add a custom sale to the cart

Anchor to addLineItem
addLineItem
(variantId: number, quantity: number) => Promise<string>
required

Add a line item by variant ID to the cart. Returns the uuid of the line item added, or the empty string if the user dismissed an oversell guard modal without adding anything. Throws if POS fails to add the line item. Throws if POS fails to add the line item.

Anchor to addLineItemProperties
addLineItemProperties
(uuid: string, properties: Record<string, string>) => Promise<void>
required

Adds custom properties to the specified line item

Anchor to addLineItemSellingPlan
addLineItemSellingPlan
(input: ) => Promise<void>
required

Add a selling plan to a line item in the cart.

Anchor to applyCartDiscount
applyCartDiscount
(type: , title: string, amount?: string) => Promise<void>
required

Apply a cart level discount

Anchor to bulkAddLineItemProperties
bulkAddLineItemProperties
(lineItemProperties: []) => Promise<void>
required

Adds custom properties to multiple line items at the same time.

Anchor to bulkCartUpdate
bulkCartUpdate
(cartState: ) => Promise<>
required

Bulk update the cart

Anchor to bulkSetLineItemDiscounts
bulkSetLineItemDiscounts
(lineItemDiscounts: []) => Promise<void>
required

Set line item discounts to multiple line items at the same time.

Anchor to clearCart
clearCart
() => Promise<void>
required

Clear the cart

Anchor to current
current
<>
required

Provides read-only access to the current cart state and allows subscribing to cart changes. The value property provides the current cart state, and subscribe allows listening to changes.

Anchor to deleteAddress
deleteAddress
(addressId: number) => Promise<void>
required

Delete an address from the customer (Customer must be present)

Anchor to removeAllDiscounts
removeAllDiscounts
(disableAutomaticDiscounts: boolean) => Promise<void>
required

Remove all cart and line item discounts

Anchor to removeCartDiscount
removeCartDiscount
() => Promise<void>
required

Remove the cart discount

Anchor to removeCartProperties
removeCartProperties
(keys: string[]) => Promise<void>
required

Removes the specified cart properties

Anchor to removeCustomer
removeCustomer
() => Promise<void>
required

Remove the current customer from the cart

Anchor to removeLineItem
removeLineItem
(uuid: string) => Promise<void>
required

Remove the line item at this uuid from the cart

Anchor to removeLineItemDiscount
removeLineItemDiscount
(uuid: string) => Promise<void>
required

Remove all discounts from a line item

Anchor to removeLineItemProperties
removeLineItemProperties
(uuid: string, keys: string[]) => Promise<void>
required

Removes the specified line item properties

Anchor to removeLineItemSellingPlan
removeLineItemSellingPlan
(uuid: string) => Promise<void>
required

Remove the selling plan from a line item in the cart.

Anchor to setAttributedStaff
setAttributedStaff
(staffId: number) => Promise<void>
required

Sets an attributed staff to all line items in the cart.

Anchor to setAttributedStaffToLineItem
setAttributedStaffToLineItem
(staffId: number, lineItemUuid: string) => Promise<void>
required

Sets an attributed staff to a specific line items in the cart.

Anchor to setCustomer
setCustomer
(customer: ) => Promise<void>
required

Set the customer in the cart

Anchor to setLineItemDiscount
setLineItemDiscount
(uuid: string, type: , title: string, amount: string) => Promise<void>
required

Add a discount on a line item to the cart

Anchor to updateDefaultAddress
updateDefaultAddress
(addressId: number) => Promise<void>
required

Update the default address for the customer (Customer must be present)

Was this section helpful?

Anchor to examplesExamples

Examples of using the Cart API

Anchor to example-subscribe-to-cart-changes.Subscribe to cart changes.
Anchor to example-check-editable-state-of-the-cartCheck editable state of the cart
Anchor to example-apply-a-cart-level-discountApply a cart level discount
Anchor to example-apply-a-cart-level-discount-codeApply a cart level discount code
Anchor to example-remove-all-the-discounts-on-the-cart-and-line-itemsRemove all the discounts on the cart and line items
Anchor to example-set-a-custom-discount-on-a-line-itemSet a custom discount on a line item
Anchor to example-set-a-custom-discount-on-multiple-line-itemsSet a custom discount on multiple line items
Anchor to example-remove-a-discount-on-a-line-itemRemove a discount on a line item
Anchor to example-clear-the-entire-cartClear the entire cart
Anchor to example-set-the-customer-in-the-cartSet the customer in the cart
Anchor to example-remove-the-customer-in-the-cartRemove the customer in the cart
Anchor to example-add-a-custom-sale-to-the-cartAdd a custom sale to the cart
Anchor to example-add-a-line-item-to-the-cartAdd a line item to the cart
Anchor to example-remove-a-line-item-from-the-cartRemove a line item from the cart
Anchor to example-add-custom-properties-to-the-cartAdd custom properties to the cart
Anchor to example-remove-custom-properties-from-the-cartRemove custom properties from the cart
Anchor to example-add-custom-properties-to-a-line-itemAdd custom properties to a line item
Anchor to example-add-custom-properties-to-multiple-line-itemsAdd custom properties to multiple line items
Anchor to example-remove-custom-properties-from-a-line-itemRemove custom properties from a line item
Anchor to example-set-an-attributed-staff-member-on-the-cartSet an attributed staff member on the cart
Anchor to example-set-an-attributed-staff-member-on-a-line-itemSet an attributed staff member on a line item
Anchor to example-add-an-address-to-the-customer-in-the-cartAdd an address to the customer in the cart
Anchor to example-delete-an-address-corresponding-to-an-idDelete an address corresponding to an ID
Anchor to example-set-the-default-address-of-the-customer-in-the-cartSet the default address of the customer in the cart
Anchor to example-add-a-selling-plan-to-a-line-item-in-the-cartAdd a selling plan to a line item in the cart
Anchor to example-remove-a-selling-plan-from-a-line-item-in-the-cartRemove a selling plan from a line item in the cart
Was this section helpful?

Subscribe to cart changes.

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
render(<Extension />, document.body);
};

const Extension = () => {
const [lineItemCount, setLineItemCount] = useState(
shopify.cart.current.value.lineItems.length
);

useEffect(() => {
const unsubscribe = shopify.cart.current.subscribe((newCart) => {
setLineItemCount(newCart.lineItems.length);
});
return unsubscribe;
}, []);

return (
<s-tile
heading="My App"
subheading={`${lineItemCount} line items in cart`}
/>
);
};