---
title: Transaction events
description: >-
  Transaction event targets operate in the background, responding to activities
  that occur during POS operations. These extensions don't display user
  interfaces but automatically react to merchant actions.
api_version: 2025-07
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/transaction-events
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/2025-07/targets/transaction-events.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/pos-ui-extensions/latest/web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10) to upgrade your extension.

# Transaction events

Transaction event targets operate in the background, responding to activities that occur during POS operations. These extensions don't display user interfaces but automatically react to merchant actions.

### Use cases

* **Real-time monitoring:** Track cart changes for inventory updates, pricing, or promotions.
* **Cash management:** Monitor cash sessions for compliance, audits, and security.
* **Post-transaction workflows:** Automate loyalty updates, inventory adjustments, and follow-ups.
* **External integrations:** Connect with reporting, fraud detection, and analytics systems.

![Transaction events targets overview](https://shopify.dev/assets/assets/images/api/pos-ui-extensions/targets-overview-images/transaction-targets-D2LWGzlr.png)

***

## Transaction events targets

Use these targets for event monitoring, automated workflows, or integration with external systems for real-time transaction processing.

### Cart update event target

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

### Cash tracking start target

`pos.cash-tracking-session-start.event.observe`

Observes when cash tracking sessions begin, triggering when merchants start cash handling operations. Use this target for monitoring cash handling activities for compliance, security, or operational reporting purposes.

Extensions at this target receive session data including the session ID and opening time when a new cash tracking session is initiated.

### Cash tracking complete target

`pos.cash-tracking-session-complete.event.observe`

Observes when cash tracking sessions complete, triggering when merchants finish cash handling operations. Use this target for monitoring cash handling completion for audit trails, compliance reporting, or operational analytics.

Extensions at this target receive session data including the session ID, opening time, and closing time when a cash tracking session is completed.

### Transaction complete event target

`pos.transaction-complete.event.observe`

Observes completed transactions including sales, returns, and exchanges, triggering when transactions are finalized. Use this target for post-transaction processing, analytics collection, and automated workflows that need to respond to completed sales activities.

Extensions at this target receive detailed transaction information including transaction type, totals, line items, and customer data when any transaction type is completed.

Examples

### Examples

* #### Process completed transactions

  ##### Description

  Subscribe to transaction completion events to trigger post-sale workflows and analytics. This example demonstrates capturing completed sales, returns, and exchanges with detailed transaction data, enabling automated workflows like sending digital receipts, updating external systems, or collecting sales analytics.

  ##### React

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

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

      // Log completed transaction for analytics
      console.log('Transaction completed:', {
        type: transaction.transactionType,
        grandTotal: transaction.grandTotal.amount,
        itemCount: transaction.lineItems?.length || 0,
        hasCustomer: !!transaction.customer,
        executedAt: transaction.executedAt,
      });

      // Example: Trigger post-transaction workflow
      if (transaction.transactionType === 'Sale' && transaction.grandTotal.amount > 100) {
        console.log('High-value sale - send thank you email');
      }

      // Example: Update external analytics system
      // fetch('/api/analytics/transaction', {
      //   method: 'POST',
      //   body: JSON.stringify({
      //     transactionType: transaction.transactionType,
      //     grandTotal: transaction.grandTotal,
      //     lineItems: transaction.lineItems,
      //     executedAt: transaction.executedAt,
      //   }),
      // });

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

  ##### TS

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

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

      // Log completed transaction for analytics
      console.log('Transaction completed:', {
        type: transaction.transactionType,
        grandTotal: transaction.grandTotal.amount,
        itemCount: transaction.lineItems?.length || 0,
        hasCustomer: !!transaction.customer,
        executedAt: transaction.executedAt,
      });

      // Example: Trigger post-transaction workflow
      if (transaction.transactionType === 'Sale' && transaction.grandTotal.amount > 100) {
        console.log('High-value sale - send thank you email');
      }

      // Example: Update external analytics system
      // fetch('/api/analytics/transaction', {
      //   method: 'POST',
      //   body: JSON.stringify({
      //     transactionType: transaction.transactionType,
      //     grandTotal: transaction.grandTotal,
      //     lineItems: transaction.lineItems,
      //     executedAt: transaction.executedAt,
      //   }),
      // });

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

***

## Best practices

* **Implement robust error handling:** Implement robust error handling to prevent event processing failures from affecting POS operations, such as try-catch blocks, graceful degradation, and error logging.
* **Process only relevant events:** Only process events that are relevant to your use case to optimize performance and resource usage, such as filtering by transaction type, checking cart contents, and validating session data.
* **Respect data privacy:** Handle transaction and customer data responsibly in accordance with privacy requirements and business policies. Event extensions have access to sensitive transaction data including customer information, payment details, and business metrics. Ensure you handle this data securely, only collect what's necessary, and comply with applicable privacy regulations and merchant policies.
* **Return consistent responses:** Return appropriate `BaseOutput` responses to indicate successful processing or report errors when needed, such as returning success status, reporting processing errors, and providing meaningful error messages.
* **Validate event data before processing:** Validate event data before processing.

***

## Limitations

* Event extensions can't render UI components or interact with the POS interface. They are designed for background processing and data observation only.

* Event extensions have access to event-specific data and the [Storage API](https://shopify.dev/docs/api/pos-ui-extensions/2025-07/target-apis/platform-apis/storage-api), but can't access other POS UI extensions APIs or modify POS state. To perform actions based on events, use external API calls or integrate with your app backend.

* Event handlers must return a `Promise<BaseOutput>` response to indicate processing completion and report any errors that occurred during event handling.

***