Skip to main content

Cart API

The Cart API provides comprehensive access to POS cart management functionality, enabling extensions to read cart state, modify line items, apply discounts, manage customer information, and handle cart properties through a subscribable interface that delivers real-time updates. The API supports both individual and bulk operations for efficient cart manipulation.

Use cases

  • Real-time monitoring: Monitor cart changes to update extension UI in real-time.
  • Custom discounts: Apply discounts at cart and line item levels with percentage or fixed amounts.
  • Product management: Add products programmatically with oversell protection.
  • Staff attribution: Implement staff attribution to track which team members are responsible for sales.
Support
Targets (10)

Supported targets

Anchor to cartapiCartApi

The CartApi object provides access to cart management methods and subscribable cart state. Access these methods through api.cart to build cart-aware extensions that respond to real-time cart updates.

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

Add a new address to the customer associated with the cart. The customer must be present in the cart before adding addresses.

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

Apply a discount code to the cart. The system will validate the code and apply the appropriate discount if the code is valid and applicable to the current cart contents.

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

Add custom key-value properties to the cart for storing metadata, tracking information, or integration data. Properties are merged with existing cart properties.

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

Add a custom sale item to the cart with specified quantity, title, price, and taxable status.

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

Add a product variant to the cart by its numeric ID with the specified quantity.

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

Add custom properties to a specific line item using its UUID. Properties are merged with existing line item properties for metadata storage and tracking.

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

Apply a cart-level discount with the specified type ('Percentage', 'FixedAmount', or 'Code'), title, and optional amount. For discount codes, omit the amount parameter. Enhanced validation ensures proper discount application.

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

Add properties to multiple line items simultaneously using an array of inputs containing line item UUIDs and their respective properties for efficient bulk operations.

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

Apply discounts to multiple line items simultaneously. Each input specifies the line item UUID and discount details for efficient bulk discount operations.

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

Remove all line items and reset the cart to an empty state. This action can't be undone and will clear all cart contents including line items, discounts, properties, and selling plans.

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

Delete an existing address from the customer using the address ID. The customer must be present in the cart to perform this operation.

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

Remove all discounts from both the cart and individual line items. Set disableAutomaticDiscounts to true to prevent automatic discounts from being reapplied after removal.

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

Remove the current cart-level discount. This only affects cart-level discounts and doesn't impact line item discounts or automatic discount eligibility.

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

Remove specific cart properties by their keys. Only the specified property keys will be removed while other properties remain intact.

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

Remove the currently associated customer from the cart, converting it back to a guest cart without customer-specific benefits or information while preserving cart contents.

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

Remove a specific line item from the cart using its UUID. The line item will be completely removed from the cart along with any associated discounts, properties, or selling plans.

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

Remove all discounts from a specific line item identified by its UUID. This will clear any custom discounts applied to the line item while preserving discount allocation history.

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

Remove specific properties from a line item by UUID and property keys. Only the specified keys will be removed while other properties remain intact.

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

Set the attributed staff member for all line items in the cart using the staff ID. Pass undefined to clear staff attribution from all line items.

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

Set the attributed staff member for a specific line item using the staff ID and line item UUID. Pass undefined as staffId to clear attribution from the line item.

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

Associate a customer with the current cart using the customer object containing the customer ID. This enables customer-specific pricing, discounts, and checkout features with customer data validation.

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

Apply a discount to a specific line item using its UUID. Specify the discount type ('Percentage' or 'FixedAmount'), title, and amount value.

Anchor to subscribable
subscribable
RemoteSubscribable<>
required

Subscribes to real-time cart state changes. Provides initial cart value and triggers callbacks on updates. Supports only one active subscription—use makeStatefulSubscribable for multiple subscribers.

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

Set a specific address as the default address for the customer using the address ID. The customer must be present in the cart to update the default address.

Examples

import React from 'react';
import {
reactExtension,
useApi,
Tile
} from '@shopify/ui-extensions-react/point-of-sale';

const SmartGridTile = () => {
const api = useApi<'pos.home.tile.render'>();

return (
<Tile
title='My App'
subtitle='Call cart function'
enabled
onPress={() => api.cart.addCustomSale({
title: 'New product',
quantity: 1,
price: '10.00',
taxable: true,
})}
/>
);
};

export default reactExtension(
'pos.home.tile.render',
() => <SmartGridTile />
);

Anchor to best-practicesBest practices

  • Manage subscriptions properly: Remember that RemoteSubscribable supports only one subscription at a time. Use makeStatefulSubscribable if you need multiple components to subscribe to cart changes simultaneously.
  • Validate operations before execution: Check cart editability and validate input data before performing cart operations to prevent errors and provide appropriate user feedback.
  • Use bulk operations for efficiency: When performing multiple related operations, use bulk methods like bulkSetLineItemDiscounts and bulkAddLineItemProperties for better performance.
  • Handle errors gracefully: Implement proper error handling for all cart operations, as they may fail due to inventory constraints, validation errors, or business rule violations.

Anchor to limitationsLimitations

  • RemoteSubscribable supports only one subscription at a time. Use makeStatefulSubscribable if you need multiple components to subscribe to cart events simultaneously.
  • Cart operations may fail due to business rules, inventory constraints, or validation errors—always implement appropriate error handling.
  • Some operations require specific preconditions. For example, customer must be present for address operations.
Was this page helpful?