From ed004a0eae31acad0c929dc7bf32aa90f10a570b Mon Sep 17 00:00:00 2001
From: Victor Chu <victor.chu@shopify.com>
Date: Thu, 10 Sep 2026 13:40:22 -0700
Subject: [PATCH] docs(pos): clarify validation intercept contracts

---
 .changeset/pos-intercept-doc-contracts.md                | 5 +++++
 .../point-of-sale/api/resolution-api/resolution-api.ts   | 4 ++--
 .../components/targets/ResolutionComponents.ts           | 6 +++---
 .../ui-extensions/src/surfaces/point-of-sale/events.ts   | 9 +++++----
 4 files changed, 15 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/pos-intercept-doc-contracts.md

diff --git a/.changeset/pos-intercept-doc-contracts.md b/.changeset/pos-intercept-doc-contracts.md
new file mode 100644
index 0000000000..656fec2762
--- /dev/null
+++ b/.changeset/pos-intercept-doc-contracts.md
@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+Clarify POS validation interceptor and resolution event semantics, including cash amounts, empty results, revalidation updates, and supported resolution components.
diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/api/resolution-api/resolution-api.ts b/packages/ui-extensions/src/surfaces/point-of-sale/api/resolution-api/resolution-api.ts
index c14a8b9c5b..31fed3405f 100644
--- a/packages/ui-extensions/src/surfaces/point-of-sale/api/resolution-api/resolution-api.ts
+++ b/packages/ui-extensions/src/surfaces/point-of-sale/api/resolution-api/resolution-api.ts
@@ -17,8 +17,8 @@ export interface ResolutionApi<TEventData> {
 export interface ResolutionApiContent<TEventData> {
   /**
    * The data of the intercepted event this resolution target was opened for.
-   * The `value` property provides the current data, and `subscribe` allows
-   * listening for host-owned revalidation updates.
+   * The `value` property provides the current data, and `subscribe` receives
+   * Shopify POS revalidation updates.
    */
   event: ReadonlySignalLike<TEventData>;
 }
diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/components/targets/ResolutionComponents.ts b/packages/ui-extensions/src/surfaces/point-of-sale/components/targets/ResolutionComponents.ts
index 71e217734b..6045a8ed0d 100644
--- a/packages/ui-extensions/src/surfaces/point-of-sale/components/targets/ResolutionComponents.ts
+++ b/packages/ui-extensions/src/surfaces/point-of-sale/components/targets/ResolutionComponents.ts
@@ -2,12 +2,12 @@ import type {StandardComponents} from './StandardComponents';
 
 /**
  * Components available on validation resolution targets. Resolution UI renders
- * inside a POS-owned flow step, so page-level and block-level containers are
- * excluded, along with the smart-grid-only `Tile`.
+ * inside a POS-owned flow step, so page-level, block-level, smart-grid, and
+ * legacy navigation components are excluded.
  *
  * @private
  */
 export type ResolutionComponents = Exclude<
   StandardComponents,
-  'Page' | 'POSBlock' | 'PosBlock' | 'Tile'
+  'Page' | 'POSBlock' | 'PosBlock' | 'QrCode' | 'Route' | 'Router' | 'Tile'
 >;
diff --git a/packages/ui-extensions/src/surfaces/point-of-sale/events.ts b/packages/ui-extensions/src/surfaces/point-of-sale/events.ts
index 0de2a3da88..72dcf790e6 100644
--- a/packages/ui-extensions/src/surfaces/point-of-sale/events.ts
+++ b/packages/ui-extensions/src/surfaces/point-of-sale/events.ts
@@ -132,7 +132,7 @@ export interface PaymentValidationsEventData {
   /** The payment method staff selected. */
   readonly paymentMethod: InterceptedPaymentMethod;
 
-  /** The amount this tender would charge, in presentment currency. */
+  /** The cash amount received for this tender, in presentment currency. */
   readonly amount: MoneyV2;
 }
 
@@ -193,8 +193,9 @@ export type ShopifyInterceptor<K extends keyof ShopifyInterceptMap> = (
 ) => InterceptResult<ValidationTargetMap[K]>;
 
 /**
- * The result an interceptor returns. An empty `operations` list allows the
- * workflow; an `ERROR` validation blocks it.
+ * The result an interceptor returns. An empty `operations` list adds no
+ * findings from this interceptor and doesn't remove or override findings from
+ * other interceptors.
  *
  * @private
  */
@@ -226,7 +227,7 @@ export type ValidationLevel = 'WARNING' | 'ERROR';
 export interface ValidationAdd<
   TTarget extends ValidationTarget = ValidationTarget,
 > {
-  /** `ERROR` blocks the workflow. `WARNING` does not. */
+  /** `ERROR` creates a finding labeled `Required`. `WARNING` creates a finding labeled `Recommended`. */
   level: ValidationLevel;
 
   /**