Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

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.

Anchor to Use casesUse 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.

Anchor to Transaction events targetsTransaction events targets

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

Anchor to Cart update event ,[object Object]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.

Anchor to cartupdateeventdataCartUpdateEventData

The data object provided to cart update extension targets. Contains the current cart state along with device, session, and connectivity information. This data is passed to extensions whenever the cart changes, enabling real-time cart monitoring and cart-based business logic.

Anchor to 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.
Anchor to connectivity connectivity 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.
Anchor to 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.
Anchor to locale locale string required: The IETF BCP 47 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.
Anchor to 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.
Anchor to 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.
```
Discount
```
cartDiscounts
An array of cart-level discounts to apply during bulk update. Replaces all existing cart discounts with the provided array.
```
Discount[]
```
customer
The customer to associate with the cart during bulk update. Replaces existing customer or converts guest cart to customer cart.
```
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.
```
boolean
```
grandTotal
The final total amount including all items, taxes, and discounts, formatted as a currency string.
```
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.
```
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.
```
string
```
properties
The custom key-value properties to apply to the line item. Merged with existing properties—duplicate keys overwrite existing values.
```
Record<string, string>
```
subtotal
The subtotal amount of the cart before taxes and discounts, formatted as a currency string.
```
string
```
taxTotal
The total tax amount for the cart, formatted as a currency 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.
```
number
```
currency
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
boolean
```
price
The unit price of the line item. Returns 'undefined' for custom sales without set prices. Use for pricing calculations and displays.
```
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.
```
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.
```
{ [key: string]: string; }
```
quantity
The quantity of this item in the cart. Always a positive integer. Use for quantity displays, calculations, and inventory management.
```
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.
```
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.
```
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.
```
string
```
taxable
Determines whether this line item is subject to tax calculations. Use for tax computation, compliance, and pricing displays.
```
boolean
```
taxLines
An array of tax lines applied to this line item, containing tax amounts and rates. Use for detailed tax reporting and compliance.
```
TaxLine[]
```
title
The display title of the line item. Returns 'undefined' for items without titles. Use for customer-facing displays and cart item identification.
```
string
```
uuid
The unique identifier for this line item within the cart. Use for line item-specific operations like updates, removals, or property modifications.
```
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.
```
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.
```
string
```

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.
```
number
```
productId
The unique numeric identifier for the product this component represents, if applicable.
```
number
```
quantity
The quantity of the custom sale item. Must be a positive integer. Use for quantity-based pricing and inventory management.
```
number
```
taxable
Determines whether the custom sale item is taxable. Set to `true` to apply tax calculations, `false` to exempt from taxes.
```
boolean
```
taxLines
An array of tax lines applied to this component.
```
TaxLine[]
```
title
The display name for the custom sale item. Appears on receipts and in cart displays. Should be descriptive and customer-friendly.
```
string
```
variantId
The unique numeric identifier for the product variant this component represents, if applicable.
```
number
```

TaxLine

Represents a tax line applied to an item or transaction.

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

Money

Represents a monetary amount with currency information.

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

DiscountAllocation

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

allocatedAmount
The amount of discount allocated.
```
MoneyV2
```

MoneyV2

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

amount
The monetary amount as a string.
```
string
```
currencyCode
The ISO currency code (for example, USD, CAD).
```
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).
```
string
```
deliveryIntervalCount
The number of intervals between deliveries.
```
number
```
digest
The fingerprint of the applied selling plan within this cart session. Provided by POS. Not available during refund / exchanges.
```
string
```
id
The unique identifier of the selling plan.
```
number
```
name
The name of the POS device.
```
string
```

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

ConnectivityStateSeverity

'Connected' | 'Disconnected'

Device

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

deviceId
The unique identifier for the POS device.
```
number
```
isTablet
Whether the device is a tablet form factor.
```
boolean
```
name
The name of the POS device.
```
string
```

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.
```
CurrencyCode
```
locationId
The location ID associated with the POS device's current location.
```
number
```
posVersion
The version of [the POS app](https://apps.shopify.com/shopify-pos) currently running.
```
string
```
shopDomain
The shop domain associated with the shop currently logged into POS.
```
string
```
shopId
The shop ID associated with the shop currently logged into POS.
```
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.
```
number
```
userId
The user ID associated with the Shopify account currently authenticated on POS.
```
number
```

CurrencyCode

'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

The `StorageApi` object provides access to persistent local storage for your POS UI extension. Access these properties through `api.storage` to store, retrieve, and manage data that persists across sessions.

clear
Clears all data from storage, removing all key-value pairs.
```
() => 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.
```
<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.
```
<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.
```
<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.
```
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys, value: StorageTypes[Keys]) => Promise<void>
```

Anchor to Cash tracking start ,[object Object]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.

Anchor to cashtrackingsessionstartdataCashTrackingSessionStartData

The data object provided to cash tracking session start extension targets. Contains information about a newly opened cash tracking session along with device and session context.

Anchor to cashTrackingSessionStart cashTrackingSessionStart { id: number; openingTime: string; } required: The cash tracking session start data containing the session identifier and the time when the session began. Cash tracking sessions represent the period during which a cash drawer is open and being used for transactions, typically corresponding to a staff member's shift.
Anchor to connectivity connectivity 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.
Anchor to 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.
Anchor to locale locale string required: The IETF BCP 47 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.
Anchor to 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.
Anchor to storage storage required: Provides access to the persistent local storage methods for storing and retrieving extension data.

Anchor to Cash tracking complete ,[object Object]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.

Anchor to cashtrackingsessioncompletedataCashTrackingSessionCompleteData

The data object provided to cash tracking session complete extension targets. Contains information about a completed cash tracking session including when it opened and closed, along with device and session context.

Anchor to cashTrackingSessionComplete cashTrackingSessionComplete { id: number; openingTime: string; closingTime: string; } required: The cash tracking session complete data containing the session identifier, opening time, and closing time. This represents the full lifecycle of a cash drawer session from opening to closing.
Anchor to connectivity connectivity 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.
Anchor to 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.
Anchor to locale locale string required: The IETF BCP 47 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.
Anchor to 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.
Anchor to storage storage required: Provides access to the persistent local storage methods for storing and retrieving extension data.

Anchor to Transaction complete event ,[object Object]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.

Anchor to transactioncompletedataTransactionCompleteData

The data object provided to receipt targets containing transaction details.

Anchor to connectivity connectivity 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.
Anchor to 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.
Anchor to locale locale string required: The IETF BCP 47 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.
Anchor to 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.
Anchor to storage storage <Record<string, unknown>> required: Provides access to persistent local storage methods for your POS UI extension. Use this to store, retrieve, and manage data that persists across sessions.
Anchor to transaction transaction | | | required: The transaction data, which can be one of the following types:

SaleTransactionData: Defines the data structure for completed sale transactions.

ReturnTransactionData: Defines the data structure for completed return transactions.

ExchangeTransactionData: Defines the data structure for completed exchange transactions.

SaleTransactionData

Defines the data structure for completed sale transactions.

balanceDue
The remaining balance still owed on this transaction as a `Money` object. Typically `{amount: 0, currency: "USD"}` for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: grandTotal minus sum of all payment amounts.
```
Money
```
customer
The customer information if this transaction is associated with a customer account. Contains the customer ID for linking to customer records. Returns `undefined` for guest transactions where no customer was selected or when the transaction doesn't support customer association.
```
Customer
```
discounts
An array of all discounts applied to this transaction, including cart-level discounts, automatic discounts, and discount codes. Each discount entry contains the discount amount, type, and description. Returns `undefined` or empty array when no discounts were applied. The sum of discount amounts reduces the final transaction total.
```
Discount[]
```
draftCheckoutUuid
The UUID of the draft checkout if the sale originated from a draft order.
```
string
```
executedAt
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the transaction was executed and completed (for example, `"2024-05-15T14:30:00Z"`). This marks the exact moment the transaction was finalized, payment was processed, and the order was created. Commonly used for transaction history, chronological sorting, reporting, audit trails, and synchronization with external systems.
```
string
```
grandTotal
The final total amount the customer pays for this transaction as a `Money` object. This includes all line items, shipping charges, taxes, and accounts for all discounts. This is the amount that must be tendered through payment methods. Calculated as: subtotal + taxTotal + shipping - discounts.
```
Money
```
lineItems
An array of line items included in the sale transaction.
```
LineItem[]
```
orderId
The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` for transactions that don't create orders (for example, reprints) or when order creation is pending.
```
number
```
paymentMethods
An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount tendered, and currency. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal`.
```
Payment[]
```
shippingLines
An array of shipping charges applied to this transaction. Each shipping line represents a shipping method with its price and associated taxes. Multiple entries can exist when different shipping methods apply to different items or when combining shipping with pickup. Returns `undefined` or empty array for transactions with no shipping charges (for example, in-store purchases, digital products).
```
ShippingLine[]
```
subtotal
The subtotal amount before taxes and after discounts are applied, as a `Money` object. This represents the sum of all line item prices (quantity × unit price) minus any discounts, but before tax is added. This is the taxable base amount for most tax calculations.
```
Money
```
taxLines
An array of individual tax lines showing the detailed tax breakdown by jurisdiction and tax type. Each tax line represents a specific tax (for example, state tax, federal tax, VAT, GST) with its rate and calculated amount. Multiple tax lines can apply to a single transaction based on location, product taxability, and tax rules. Returns `undefined` or empty array for tax-exempt transactions or when detailed tax breakdown isn't available.
```
TaxLine[]
```
taxTotal
The total tax amount charged on this transaction as a `Money` object. This is the sum of all tax lines and represents the combined tax from all applicable tax jurisdictions and rules. Tax calculations are based on the location, products, customer, and tax settings configured in Shopify.
```
Money
```
transactionType
The transaction type identifier, always 'Sale' for sale transactions.
```
'Sale'
```

Payment

Represents a payment applied to a transaction, including the amount, currency, and payment method type.

amount
The payment amount.
```
number
```
currency
The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
```
string
```
type
The payment method type.
```
PaymentMethod
```

PaymentMethod

The available payment method types for POS transactions.

'Cash' | 'Custom' | 'CreditCard' | 'CardPresentRefund' | 'StripeCardPresentRefund' | 'GiftCard' | 'StripeCreditCard' | 'ShopPay' | 'StoreCredit' | 'Unknown'

ShippingLine

Represents a shipping charge applied to an order, including the price and applicable taxes.

handle
The handle identifier for the shipping method.
```
string
```
price
The price of the shipping as a Money object.
```
Money
```
taxLines
An array of individual tax lines showing tax breakdown.
```
TaxLine[]
```
title
The display title of the shipping method.
```
string
```

ReturnTransactionData

Defines the data structure for completed return transactions.

balanceDue
The remaining balance still owed on this transaction as a `Money` object. Typically `{amount: 0, currency: "USD"}` for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: grandTotal minus sum of all payment amounts.
```
Money
```
customer
The customer information if this transaction is associated with a customer account. Contains the customer ID for linking to customer records. Returns `undefined` for guest transactions where no customer was selected or when the transaction doesn't support customer association.
```
Customer
```
discounts
An array of all discounts applied to this transaction, including cart-level discounts, automatic discounts, and discount codes. Each discount entry contains the discount amount, type, and description. Returns `undefined` or empty array when no discounts were applied. The sum of discount amounts reduces the final transaction total.
```
Discount[]
```
exchangeId
The exchange ID if the return is part of an exchange transaction.
```
number
```
executedAt
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the transaction was executed and completed (for example, `"2024-05-15T14:30:00Z"`). This marks the exact moment the transaction was finalized, payment was processed, and the order was created. Commonly used for transaction history, chronological sorting, reporting, audit trails, and synchronization with external systems.
```
string
```
grandTotal
The final total amount the customer pays for this transaction as a `Money` object. This includes all line items, shipping charges, taxes, and accounts for all discounts. This is the amount that must be tendered through payment methods. Calculated as: subtotal + taxTotal + shipping - discounts.
```
Money
```
lineItems
An array of line items included in the sale transaction.
```
LineItem[]
```
orderId
The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` for transactions that don't create orders (for example, reprints) or when order creation is pending.
```
number
```
paymentMethods
An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount tendered, and currency. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal`.
```
Payment[]
```
refundId
The refund ID if a refund was issued for the return.
```
number
```
returnId
The return ID for the completed return transaction.
```
number
```
shippingLines
An array of shipping charges applied to this transaction. Each shipping line represents a shipping method with its price and associated taxes. Multiple entries can exist when different shipping methods apply to different items or when combining shipping with pickup. Returns `undefined` or empty array for transactions with no shipping charges (for example, in-store purchases, digital products).
```
ShippingLine[]
```
subtotal
The subtotal amount before taxes and after discounts are applied, as a `Money` object. This represents the sum of all line item prices (quantity × unit price) minus any discounts, but before tax is added. This is the taxable base amount for most tax calculations.
```
Money
```
taxLines
An array of individual tax lines showing the detailed tax breakdown by jurisdiction and tax type. Each tax line represents a specific tax (for example, state tax, federal tax, VAT, GST) with its rate and calculated amount. Multiple tax lines can apply to a single transaction based on location, product taxability, and tax rules. Returns `undefined` or empty array for tax-exempt transactions or when detailed tax breakdown isn't available.
```
TaxLine[]
```
taxTotal
The total tax amount charged on this transaction as a `Money` object. This is the sum of all tax lines and represents the combined tax from all applicable tax jurisdictions and rules. Tax calculations are based on the location, products, customer, and tax settings configured in Shopify.
```
Money
```
transactionType
The transaction type identifier, always 'Sale' for sale transactions.
```
'Return'
```

ExchangeTransactionData

Defines the data structure for completed exchange transactions.

balanceDue
The remaining balance still owed on this transaction as a `Money` object. Typically `{amount: 0, currency: "USD"}` for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: grandTotal minus sum of all payment amounts.
```
Money
```
customer
The customer information if this transaction is associated with a customer account. Contains the customer ID for linking to customer records. Returns `undefined` for guest transactions where no customer was selected or when the transaction doesn't support customer association.
```
Customer
```
discounts
An array of all discounts applied to this transaction, including cart-level discounts, automatic discounts, and discount codes. Each discount entry contains the discount amount, type, and description. Returns `undefined` or empty array when no discounts were applied. The sum of discount amounts reduces the final transaction total.
```
Discount[]
```
exchangeId
The exchange ID if the return is part of an exchange transaction.
```
number
```
executedAt
The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp when the transaction was executed and completed (for example, `"2024-05-15T14:30:00Z"`). This marks the exact moment the transaction was finalized, payment was processed, and the order was created. Commonly used for transaction history, chronological sorting, reporting, audit trails, and synchronization with external systems.
```
string
```
grandTotal
The final total amount the customer pays for this transaction as a `Money` object. This includes all line items, shipping charges, taxes, and accounts for all discounts. This is the amount that must be tendered through payment methods. Calculated as: subtotal + taxTotal + shipping - discounts.
```
Money
```
lineItemsAdded
An array of line items added to the customer in the exchange.
```
LineItem[]
```
lineItemsRemoved
An array of line items removed from the customer in the exchange.
```
LineItem[]
```
orderId
The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` for transactions that don't create orders (for example, reprints) or when order creation is pending.
```
number
```
paymentMethods
An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount tendered, and currency. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal`.
```
Payment[]
```
returnId
The return ID for the completed return transaction.
```
number
```
shippingLines
An array of shipping charges applied to this transaction. Each shipping line represents a shipping method with its price and associated taxes. Multiple entries can exist when different shipping methods apply to different items or when combining shipping with pickup. Returns `undefined` or empty array for transactions with no shipping charges (for example, in-store purchases, digital products).
```
ShippingLine[]
```
subtotal
The subtotal amount before taxes and after discounts are applied, as a `Money` object. This represents the sum of all line item prices (quantity × unit price) minus any discounts, but before tax is added. This is the taxable base amount for most tax calculations.
```
Money
```
taxLines
An array of individual tax lines showing the detailed tax breakdown by jurisdiction and tax type. Each tax line represents a specific tax (for example, state tax, federal tax, VAT, GST) with its rate and calculated amount. Multiple tax lines can apply to a single transaction based on location, product taxability, and tax rules. Returns `undefined` or empty array for tax-exempt transactions or when detailed tax breakdown isn't available.
```
TaxLine[]
```
taxTotal
The total tax amount charged on this transaction as a `Money` object. This is the sum of all tax lines and represents the combined tax from all applicable tax jurisdictions and rules. Tax calculations are based on the location, products, customer, and tax settings configured in Shopify.
```
Money
```
transactionType
The transaction type identifier, always 'Sale' for sale transactions.
```
'Exchange'
```

Examples

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 {};

);

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

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

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 {};
  },
);

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

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

Was this page helpful?