---
title: pos.cart-update.event.observe
description: >-
  Observes cart updates during active transactions, triggering whenever
  merchants add, remove, or modify line items. Use this target for real-time
  responses to cart changes like dynamic pricing, inventory validation, or
  promotional offer applications based on current cart contents.


  Extensions at this target receive complete cart data including line items,
  totals, discounts, and customer information whenever the cart state changes.
api_version: 2025-07
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/cart-details/pos-cart-update-event-observe
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/cart-details/pos-cart-update-event-observe.md
---

# pos.​cart-update.​event.​observe

Observes cart updates during active transactions, triggering whenever merchants add, remove, or modify line items. Use this target for real-time responses to cart changes like dynamic pricing, inventory validation, or promotional offer applications based on current cart contents.

Extensions at this target receive complete cart data including line items, totals, discounts, and customer information whenever the cart state changes.

## CartUpdateEventData

The data object provided to this extension target.

* cart

  Cart

  required

  The complete current `Cart` object containing all cart data including line items with products and quantities, pricing totals (subtotal, tax, grand total), associated customer information, applied discounts, custom properties, and editability state. This represents the cart's state at the moment the extension is triggered, reflecting all recent changes. The cart object is read-only in this context—modifications should be made through the Cart API methods.

* connectivity

  ConnectivityState

  required

  The current Internet connectivity state of the POS device. Indicates whether the device is connected to or disconnected from the Internet. This state updates in real-time as connectivity changes, allowing extensions to adapt behavior for offline scenarios, show connectivity warnings, or queue operations for when connectivity is restored.

* device

  Device

  required

  Comprehensive information about the physical POS device where the extension is currently running. Includes the device name, unique device ID, and form factor information (tablet vs other). This data is static for the session and helps extensions adapt to different device types, log device-specific information, or implement device-based configurations.

* locale

  string

  required

  The [IETF BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) locale string for the current POS session (for example, `"en-US"`, `"fr-CA"`, `"de-DE"`). This indicates the merchant's language and regional preferences. Commonly used for internationalization (i18n), locale-specific date/time/number formatting, translating UI text, and providing localized content. The locale remains constant for the session and reflects the language selected in POS settings.

* session

  Session

  required

  Comprehensive information about the current POS session including shop ID and domain, authenticated user, pinned staff member, active location, currency settings, and POS version. This session data remains constant for the session duration and provides critical context for business logic, permissions, API authentication, and transaction processing. Session data updates when users switch locations or change pinned staff members.

* storage

  Storage

  required

  Provides access to the persistent local storage methods for storing and retrieving extension data.

### Cart

Represents the shopping cart state, including line items, pricing, customer information, and applied discounts. Provides comprehensive access to all cart data and operations.

* cartDiscount

  The cart-level discount to apply during bulk update. Replaces existing cart discount. Set to \`undefined\` to remove current discount.

  ```ts
  Discount
  ```

* cartDiscounts

  An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array.

  ```ts
  Discount[]
  ```

* customer

  The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart.

  ```ts
  Customer
  ```

* editable

  Indicates whether the cart is currently editable. An \`undefined\` value should be treated as \`true\` for backward compatibility. Use this to determine if cart modification operations are allowed.

  ```ts
  boolean
  ```

* grandTotal

  The final total amount including all items, taxes, and discounts, formatted as a currency string.

  ```ts
  string
  ```

* lineItems

  An array of line items to set during bulk update. Completely replaces existing cart contents—removes all current items and adds the provided ones.

  ```ts
  LineItem[]
  ```

* note

  The cart note to set during bulk update. Replaces existing note or sets new note if none exists. Set to \`undefined\` to remove current note.

  ```ts
  string
  ```

* properties

  The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values.

  ```ts
  Record<string, string>
  ```

* subtotal

  The subtotal amount of the cart before taxes and discounts, formatted as a currency string.

  ```ts
  string
  ```

* taxTotal

  The total tax amount for the cart, formatted as a currency string.

  ```ts
  string
  ```

```ts
export interface Cart {
  /**
   * Indicates whether the cart is currently editable. An `undefined` value should be treated as `true` for backward compatibility. Use this to determine if cart modification operations are allowed.
   */
  editable?: boolean;
  /**
   * The subtotal amount of the cart before taxes and discounts, formatted as a currency string.
   */
  subtotal: string;
  /**
   * The total tax amount for the cart, formatted as a currency string.
   */
  taxTotal: string;
  /**
   * The final total amount including all items, taxes, and discounts, formatted as a currency string.
   */
  grandTotal: string;
  /**
   * The cart note to set during bulk update. Replaces existing note or sets new note if none exists. Set to `undefined` to remove current note.
   */
  note?: string;
  /**
   * The cart-level discount to apply during bulk update. Replaces existing cart discount. Set to `undefined` to remove current discount.
   */
  cartDiscount?: Discount;
  /**
   * An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array.
   */
  cartDiscounts: Discount[];
  /**
   * The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart.
   */
  customer?: Customer;
  /**
   * An array of line items to set during bulk update. Completely replaces existing cart contents—removes all current items and adds the provided ones.
   */
  lineItems: LineItem[];
  /**
   * The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values.
   */
  properties: Record<string, string>;
}
```

### Discount

Represents a discount applied to a cart or transaction, including amount and description.

* amount

  The discount value to apply. For \`'Percentage'\` type, this represents the percentage value (For example, "10" for 10% off). For \`'FixedAmount'\` type, this represents the fixed monetary amount to deduct from the line item price. Commonly used for discount calculations and displaying the discount value to merchants.

  ```ts
  number
  ```

* currency

  The \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) currency code associated with the location currently active on POS.

  ```ts
  string
  ```

* discountDescription

  A human-readable description of the discount shown to merchants and customers. This typically includes the discount name, promotion details, or discount code (for example, "SUMMER2024", "10% off entire order", "Buy 2 Get 1 Free"). Returns \`undefined\` when no description is provided.

  ```ts
  string
  ```

* type

  The \[discount type]\(https://help.shopify.com/en/manual/discounts/discount-types) applied to this line item. Can be either \`'Percentage'\` for percentage-based discounts or \`'FixedAmount'\` for fixed monetary amount discounts. This determines how the discount amount is calculated and displayed.

  ```ts
  string
  ```

```ts
export interface Discount {
  /**
   * The discount value to apply. For `'Percentage'` type, this represents the percentage value (For example, "10" for 10% off). For `'FixedAmount'` type, this represents the fixed monetary amount to deduct from the line item price. Commonly used for discount calculations and displaying the discount value to merchants.
   */
  amount: number;
  /**
   * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
   */
  currency?: string;
  /**
   * A human-readable description of the discount shown to merchants and customers. This typically includes the discount name, promotion details, or discount code (for example, "SUMMER2024", "10% off entire order", "Buy 2 Get 1 Free"). Returns `undefined` when no description is provided.
   */
  discountDescription?: string;
  /**
   * The [discount type](https://help.shopify.com/en/manual/discounts/discount-types) applied to this line item. Can be either `'Percentage'` for percentage-based discounts or `'FixedAmount'` for fixed monetary amount discounts. This determines how the discount amount is calculated and displayed.
   */
  type?: string;
}
```

### Customer

Represents basic customer identification information. Contains the customer ID for linking to detailed customer data and enabling customer-specific features.

* id

  The unique numeric identifier for the customer in Shopify's system. This ID is consistent across all Shopify systems and APIs. Used to link this customer reference to the full customer record with complete profile information. Commonly used for customer lookups, applying customer-specific pricing or discounts, linking orders to customer accounts, or integrating with customer management systems.

  ```ts
  number
  ```

```ts
export interface Customer {
  /**
   * The unique numeric identifier for the customer in Shopify's system. This ID is consistent across all Shopify systems and APIs. Used to link this customer reference to the full customer record with complete profile information. Commonly used for customer lookups, applying customer-specific pricing or discounts, linking orders to customer accounts, or integrating with customer management systems.
   */
  id: number;
}
```

### LineItem

Represents an individual item in the shopping cart. Contains product information, pricing, quantity, discounts, and customization details for a single cart entry.

* attributedUserId

  The staff member 'ID' attributed to this line item. Returns 'undefined' if no staff attribution is set. Use for commission tracking and performance analytics.

  ```ts
  number
  ```

* components

  Bundle components for this line item. Only present for \[product bundles]\(/docs/apps/build/product-merchandising/bundles). Each component represents an individual item within the bundle with its own tax information.

  ```ts
  LineItemComponent[]
  ```

* discountAllocations

  An array of discount allocations applied to this line item, providing detailed breakdown of how discounts are distributed. Returns 'undefined' if no allocations exist. Use for enhanced discount tracking and reporting.

  ```ts
  DiscountAllocation[]
  ```

* discounts

  An array of discounts applied to this line item. Empty array if no discounts are active. Use for displaying line item savings and discount details.

  ```ts
  Discount[]
  ```

* hasSellingPlanGroups

  Determines whether this line item has selling plan groups (subscription options) available. Returns 'undefined' if selling plan information is unavailable. Use for displaying subscription options.

  ```ts
  boolean
  ```

* isGiftCard

  Determines whether this line item is a gift card. Gift cards have special handling requirements and business logic. Use for implementing gift card-specific workflows.

  ```ts
  boolean
  ```

* price

  The unit price of the line item. Returns 'undefined' for custom sales without set prices. Use for pricing calculations and displays.

  ```ts
  number
  ```

* productId

  The product 'ID' this line item represents. Returns 'undefined' for custom sales or non-product items. Use for product-specific operations and linking to product details.

  ```ts
  number
  ```

* properties

  The custom key-value properties attached to this line item. Empty object if no properties are set. Use for metadata, customization options, or integration data.

  ```ts
  { [key: string]: string; }
  ```

* quantity

  The quantity of this item in the cart. Always a positive integer. Use for quantity displays, calculations, and inventory management.

  ```ts
  number
  ```

* requiresSellingPlan

  Determines whether this line item requires a selling plan (subscription) to be purchased. Returns 'undefined' if selling plan information is unavailable. Use for implementing subscription-based product handling.

  ```ts
  boolean
  ```

* sellingPlan

  The currently selected selling plan for this line item. Returns 'undefined' if no selling plan is applied. Contains selling plan details including 'ID', name, and delivery intervals. Use for subscription management and recurring purchase functionality.

  ```ts
  SellingPlan
  ```

* sku

  The Stock Keeping Unit (SKU) identifier for this line item. Returns 'undefined' if no SKU is configured. Use for inventory tracking and product identification.

  ```ts
  string
  ```

* taxable

  Determines whether this line item is subject to tax calculations. Use for tax computation, compliance, and pricing displays.

  ```ts
  boolean
  ```

* taxLines

  An array of tax lines applied to this line item, containing tax amounts and rates. Use for detailed tax reporting and compliance.

  ```ts
  TaxLine[]
  ```

* title

  The display title of the line item. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification.

  ```ts
  string
  ```

* uuid

  The unique identifier for this line item within the cart. Use for line item-specific operations like updates, removals, or property modifications.

  ```ts
  string
  ```

* variantId

  The product variant 'ID' this line item represents. Returns 'undefined' for custom sales or non-variant items. Use for variant-specific operations and product details.

  ```ts
  number
  ```

* vendor

  The vendor or brand name for this line item. Returns 'undefined' if no vendor is set. Use for vendor-specific displays and organization.

  ```ts
  string
  ```

```ts
export interface LineItem {
  /**
   * The unique identifier for this line item within the cart. Use for line item-specific operations like updates, removals, or property modifications.
   */
  uuid: string;
  /**
   * The unit price of the line item. Returns 'undefined' for custom sales without set prices. Use for pricing calculations and displays.
   */
  price?: number;
  /**
   * The quantity of this item in the cart. Always a positive integer. Use for quantity displays, calculations, and inventory management.
   */
  quantity: number;
  /**
   * The display title of the line item. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification.
   */
  title?: string;
  /**
   * The product variant 'ID' this line item represents. Returns 'undefined' for custom sales or non-variant items. Use for variant-specific operations and product details.
   */
  variantId?: number;
  /**
   * The product 'ID' this line item represents. Returns 'undefined' for custom sales or non-product items. Use for product-specific operations and linking to product details.
   */
  productId?: number;
  /**
   * An array of discounts applied to this line item. Empty array if no discounts are active. Use for displaying line item savings and discount details.
   */
  discounts: Discount[];
  /**
   * An array of discount allocations applied to this line item, providing detailed breakdown of how discounts are distributed. Returns 'undefined' if no allocations exist. Use for enhanced discount tracking and reporting.
   */
  discountAllocations?: DiscountAllocation[];
  /**
   * Determines whether this line item is subject to tax calculations. Use for tax computation, compliance, and pricing displays.
   */
  taxable: boolean;
  /**
   * An array of tax lines applied to this line item, containing tax amounts and rates. Use for detailed tax reporting and compliance.
   */
  taxLines: TaxLine[];
  /**
   * The Stock Keeping Unit (SKU) identifier for this line item. Returns 'undefined' if no SKU is configured. Use for inventory tracking and product identification.
   */
  sku?: string;
  /**
   * The vendor or brand name for this line item. Returns 'undefined' if no vendor is set. Use for vendor-specific displays and organization.
   */
  vendor?: string;
  /**
   * The custom key-value properties attached to this line item. Empty object if no properties are set. Use for metadata, customization options, or integration data.
   */
  properties: {[key: string]: string};
  /**
   * Determines whether this line item is a gift card. Gift cards have special handling requirements and business logic. Use for implementing gift card-specific workflows.
   */
  isGiftCard: boolean;
  /**
   * The staff member 'ID' attributed to this line item. Returns 'undefined' if no staff attribution is set. Use for commission tracking and performance analytics.
   */
  attributedUserId?: number;
  /**
   * Determines whether this line item requires a selling plan (subscription) to be purchased. Returns 'undefined' if selling plan information is unavailable. Use for implementing subscription-based product handling.
   */
  requiresSellingPlan?: boolean;
  /**
   * Determines whether this line item has selling plan groups (subscription options) available. Returns 'undefined' if selling plan information is unavailable. Use for displaying subscription options.
   */
  hasSellingPlanGroups?: boolean;
  /**
   * The currently selected selling plan for this line item. Returns 'undefined' if no selling plan is applied. Contains selling plan details including 'ID', name, and delivery intervals. Use for subscription management and recurring purchase functionality.
   */
  sellingPlan?: SellingPlan;
  /**
   * Bundle components for this line item. Only present for [product bundles](/docs/apps/build/product-merchandising/bundles). Each component represents an individual item within the bundle with its own tax information.
   */
  components?: LineItemComponent[];
}
```

### LineItemComponent

Represents a component of a \[product bundle]\(/docs/apps/build/product-merchandising/bundles) line item. Bundle components contain the individual items that make up a bundle, each with their own pricing and tax information.

* price

  The price for the custom sale item as currency string. Must be a valid positive amount. Use for non-catalog items and custom pricing.

  ```ts
  number
  ```

* productId

  The unique numeric identifier for the product this component represents, if applicable.

  ```ts
  number
  ```

* quantity

  The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management.

  ```ts
  number
  ```

* taxable

  Determines whether the custom sale item is taxable. Set to \`true\` to apply tax calculations, \`false\` to exempt from taxes.

  ```ts
  boolean
  ```

* taxLines

  An array of tax lines applied to this component.

  ```ts
  TaxLine[]
  ```

* title

  The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly.

  ```ts
  string
  ```

* variantId

  The unique numeric identifier for the product variant this component represents, if applicable.

  ```ts
  number
  ```

```ts
export interface LineItemComponent {
  /**
   * The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly.
   */
  title?: string;
  /**
   * The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management.
   */
  quantity: number;
  /**
   * The price for the custom sale item as currency string. Must be a valid positive amount. Use for non-catalog items and custom pricing.
   */
  price?: number;
  /**
   * Determines whether the custom sale item is taxable. Set to `true` to apply tax calculations, `false` to exempt from taxes.
   */
  taxable: boolean;
  /**
   * An array of tax lines applied to this component.
   */
  taxLines: TaxLine[];
  /**
   * The unique numeric identifier for the product variant this component represents, if applicable.
   */
  variantId?: number;
  /**
   * The unique numeric identifier for the product this component represents, if applicable.
   */
  productId?: number;
}
```

### TaxLine

Represents a tax line applied to an item or transaction.

* enabled

  Whether this tax is currently enabled.

  ```ts
  boolean
  ```

* price

  The tax amount as a Money object.

  ```ts
  Money
  ```

* rate

  The tax rate as a decimal number.

  ```ts
  number
  ```

* rateRange

  The range of tax rates if applicable.

  ```ts
  { min: number; max: number; }
  ```

* title

  The title or name of the tax.

  ```ts
  string
  ```

* uuid

  The unique identifier for this tax line.

  ```ts
  string
  ```

```ts
export interface TaxLine {
  /**
   * The title or name of the tax.
   */
  title: string;
  /**
   * The tax amount as a Money object.
   */
  price: Money;
  /**
   * The tax rate as a decimal number.
   */
  rate: number;
  /**
   * The unique identifier for this tax line.
   */
  uuid?: string;
  /**
   * The range of tax rates if applicable.
   */
  rateRange?: {min: number; max: number};
  /**
   * Whether this tax is currently enabled.
   */
  enabled?: boolean;
}
```

### Money

Represents a monetary amount with currency information.

* amount

  The monetary amount as a number.

  ```ts
  number
  ```

* currency

  The \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) currency code associated with the location currently active on POS.

  ```ts
  string
  ```

```ts
export interface Money {
  /**
   * The monetary amount as a number.
   */
  amount: number;
  /**
   * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
   */
  currency: string;
}
```

### DiscountAllocation

Represents the allocation of a discount to a specific line item.

* allocatedAmount

  The amount of discount allocated.

  ```ts
  MoneyV2
  ```

```ts
export interface DiscountAllocation {
  /**
   * The amount of discount allocated.
   */
  allocatedAmount: MoneyV2;
}
```

### MoneyV2

Represents a monetary amount as a string with explicit currency code.

* amount

  The monetary amount as a string.

  ```ts
  string
  ```

* currencyCode

  The ISO currency code (for example, USD, CAD).

  ```ts
  string
  ```

```ts
export interface MoneyV2 {
  /**
   * The monetary amount as a string.
   */
  amount: string;
  /**
   * The ISO currency code (for example, USD, CAD).
   */
  currencyCode: string;
}
```

### SellingPlan

Represents a selling plan (subscription) associated with a line item, containing delivery schedule and plan identification details.

* deliveryInterval

  The interval of the selling plan. (DAY, WEEK, MONTH, YEAR).

  ```ts
  string
  ```

* deliveryIntervalCount

  The number of intervals between deliveries.

  ```ts
  number
  ```

* digest

  The fingerprint of the applied selling plan within this cart session. Provided by POS. Not available during refund / exchanges.

  ```ts
  string
  ```

* id

  The unique identifier of the selling plan.

  ```ts
  number
  ```

* name

  The name of the POS device.

  ```ts
  string
  ```

```ts
export interface SellingPlan {
  /**
   * The unique identifier of the selling plan.
   */
  id: number;
  /**
   * The name of the POS device.
   */
  name: string;
  /**
   * The fingerprint of the applied selling plan within this cart session. Provided by POS. Not available during refund / exchanges.
   */
  digest?: string;
  /**
   * The interval of the selling plan. (DAY, WEEK, MONTH, YEAR).
   */
  deliveryInterval?: string;
  /**
   * The number of intervals between deliveries.
   */
  deliveryIntervalCount?: number;
}
```

### ConnectivityState

Represents the current Internet connectivity status of the device. Indicates whether the device is connected or disconnected from the Internet.

* internetConnected

  Whether the device is connected to the Internet. Returns either \`Connected\` or \`Disconnected\` to indicate the current Internet connectivity status. Use for implementing connectivity-aware functionality, displaying connectivity indicators, or controlling network-dependent features.

  ```ts
  ConnectivityStateSeverity
  ```

```ts
export interface ConnectivityState {
  /**
   * Whether the device is connected to the Internet. Returns either `Connected` or `Disconnected` to indicate the current Internet connectivity status. Use for implementing connectivity-aware functionality, displaying connectivity indicators, or controlling network-dependent features.
   */
  internetConnected: ConnectivityStateSeverity;
}
```

### ConnectivityStateSeverity

```ts
'Connected' | 'Disconnected'
```

### Device

Defines information about the POS device where the extension is running.

* deviceId

  The unique identifier for the POS device.

  ```ts
  number
  ```

* isTablet

  Whether the device is a tablet form factor.

  ```ts
  boolean
  ```

* name

  The name of the POS device.

  ```ts
  string
  ```

```ts
export interface Device {
  /**
   * The name of the POS device.
   */
  name: string;
  /**
   * The unique identifier for the POS device.
   */
  deviceId: number;
  /**
   * Whether the device is a tablet form factor.
   */
  isTablet: boolean;
}
```

### Session

Defines information about the current POS session.

* currency

  The \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) currency code associated with the location currently active on POS.

  ```ts
  CurrencyCode
  ```

* locationId

  The location ID associated with the POS device's current location.

  ```ts
  number
  ```

* posVersion

  The version of \[the POS app]\(https://apps.shopify.com/shopify-pos) currently running.

  ```ts
  string
  ```

* shopDomain

  The shop domain associated with the shop currently logged into POS.

  ```ts
  string
  ```

* shopId

  The shop ID associated with the shop currently logged into POS.

  ```ts
  number
  ```

* staffMemberId

  The staff ID of the staff member currently pinned into the POS. This may differ from the user ID if the pinned staff member is different from the logged-in user.

  ```ts
  number
  ```

* userId

  The user ID associated with the Shopify account currently authenticated on POS.

  ```ts
  number
  ```

```ts
export interface Session {
  /**
   * The shop ID associated with the shop currently logged into POS.
   */
  shopId: number;

  /**
   * The user ID associated with the Shopify account currently authenticated on POS.
   */
  userId: number;

  /**
   * The shop domain associated with the shop currently logged into POS.
   */
  shopDomain: string;

  /**
   * The location ID associated with the POS device's current location.
   */
  locationId: number;

  /**
   * The staff ID of the staff member currently pinned into the POS. This may differ from the user ID if the pinned staff member is different from the logged-in user.
   */
  staffMemberId?: number;

  /**
   * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
   */
  currency: CurrencyCode;

  /**
   * The version of [the POS app](https://apps.shopify.com/shopify-pos) currently running.
   */
  posVersion: string;
}
```

### CurrencyCode

```ts
'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL'
```

### Storage

Defines the storage interface for persisting extension data across sessions.

* clear

  Clears all data from storage, removing all key-value pairs.

  ```ts
  () => Promise<void>
  ```

* delete

  Deletes a specific key from storage and returns \`true\` if the key existed, \`false\` if it didn't exist. Returns \`false\` for non-existent keys rather than throwing an error. Commonly used for cleaning up temporary workflow data, removing expired cache entries, or handling user preference changes.

  ```ts
  <StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys) => Promise<boolean>
  ```

* entries

  Retrieves all stored key-value pairs as an array of tuples, preserving original data types. Returns all data at once which may impact memory usage with large datasets. Commonly used for debugging storage contents, implementing data export features, or performing bulk operations across stored data.

  ```ts
  <StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>() => Promise<[Keys, StorageTypes[Keys]][]>
  ```

* get

  Retrieves the value associated with a key, returning \`undefined\` if the key doesn't exist. Always handle the \`undefined\` case by providing fallback values or conditional logic. Commonly used for loading user preferences, retrieving cached data, or accessing contextual information passed between extension targets.

  ```ts
  <StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys) => Promise<StorageTypes[Keys]>
  ```

* set

  Stores a value under the specified key, overwriting any existing value. Values must be JSON-serializable and return \`StorageError\` when storage limits are exceeded. Commonly used for storing user preferences, caching API responses, or passing contextual data from tiles to modals.

  ```ts
  <StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys, value: StorageTypes[Keys]) => Promise<void>
  ```

```ts
export interface Storage<
  BaseStorageTypes extends Record<string, any> = Record<string, unknown>,
> {
  /**
   * Stores a value under the specified key, overwriting any existing value. Values must be JSON-serializable and return `StorageError` when storage limits are exceeded. Commonly used for storing user preferences, caching API responses, or passing contextual data from tiles to modals.
   *
   * @param key - The key to set the value for.
   * @param value - The value to set for the key.
   * @throws StorageError when:
   * - Maximum number of records is exceeded (`code: 'RecordsCount'`)
   * - Individual record size exceeds the limit (`code: 'RecordSize'`)
   * - Key is not a string (`code: 'KeyType'`)
   * - Key size exceeds the limit (`code: 'KeySize'`)
   */
  set<
    StorageTypes extends BaseStorageTypes = BaseStorageTypes,
    Keys extends keyof StorageTypes = keyof StorageTypes,
  >(
    key: Keys,
    value: StorageTypes[Keys],
  ): Promise<void>;

  /**
   * Retrieves the value associated with a key, returning `undefined` if the key doesn't exist. Always handle the `undefined` case by providing fallback values or conditional logic. Commonly used for loading user preferences, retrieving cached data, or accessing contextual information passed between extension targets.
   *
   * @param key - The key to get the value for.
   * @returns The value of the key.
   * @throws StorageError when the key isn't a string or exceeds its allotted size.
   */
  get<
    StorageTypes extends BaseStorageTypes = BaseStorageTypes,
    Keys extends keyof StorageTypes = keyof StorageTypes,
  >(
    key: Keys,
  ): Promise<StorageTypes[Keys] | undefined>;

  /**
   * Clears all data from storage, removing all key-value pairs.
   */
  clear: () => Promise<void>;

  /**
   * Deletes a specific key from storage and returns `true` if the key existed, `false` if it didn't exist. Returns `false` for non-existent keys rather than throwing an error. Commonly used for cleaning up temporary workflow data, removing expired cache entries, or handling user preference changes.
   *
   * @param key - The key to delete.
   */
  delete<
    StorageTypes extends BaseStorageTypes = BaseStorageTypes,
    Keys extends keyof StorageTypes = keyof StorageTypes,
  >(
    key: Keys,
  ): Promise<boolean>;

  /**
   * Retrieves all stored key-value pairs as an array of tuples, preserving original data types. Returns all data at once which may impact memory usage with large datasets. Commonly used for debugging storage contents, implementing data export features, or performing bulk operations across stored data.
   *
   * @returns An array containing all the keys and values in the storage.
   */
  entries<
    StorageTypes extends BaseStorageTypes = BaseStorageTypes,
    Keys extends keyof StorageTypes = keyof StorageTypes,
  >(): Promise<[Keys, StorageTypes[Keys]][]>;
}
```

### Examples

* #### Monitor cart changes in real time

  ##### Description

  Subscribe to cart update events to respond to cart modifications automatically. This example demonstrates tracking cart changes for analytics, triggering workflows based on cart contents, or implementing dynamic pricing rules that react to line item additions or removals.

  ##### React

  ```tsx
  import {reactEventExtension} from '@shopify/ui-extensions-react/point-of-sale';

  export default reactEventExtension(
    'pos.cart-update.event.observe',
    (eventData) => {
      // Access cart data from the event
      const {cart} = eventData;

      // Log cart changes for analytics or trigger workflows
      console.log('Cart updated:', {
        lineItemCount: cart.lineItems.length,
        grandTotal: cart.grandTotal,
        hasCustomer: !!cart.customer,
      });

      // Example: Trigger a workflow based on cart contents
      if (cart.lineItems.length > 5) {
        console.log('Large cart detected - consider bulk discount');
      }

      // Return success (no errors)
      return {};
    },
  );
  ```

  ##### TS

  ```ts
  import {eventExtension} from '@shopify/ui-extensions/point-of-sale';

  export default eventExtension('pos.cart-update.event.observe', (eventData) => {
    // Access cart data from the event
    const {cart} = eventData;

    // Log cart changes for analytics or trigger workflows
    console.log('Cart updated:', {
      lineItemCount: cart.lineItems.length,
      grandTotal: cart.grandTotal,
      hasCustomer: !!cart.customer,
    });

    // Example: Trigger a workflow based on cart contents
    if (cart.lineItems.length > 5) {
      console.log('Large cart detected - consider bulk discount');
    }

    // Return success (no errors)
    return {};
  });
  ```