Syncing private package for 2026-01 release (#3730)

* syncing private package for 2026-01 release

* add buyer journey updates

Author: lrsterrett

.changeset/hot-olives-act.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+recommend merchant friendly warning for enabling checkout extension to block progress

packages/ui-extensions/docs/surfaces/checkout/reference/apis/buyer-journey.doc.ts

@@ -39,6 +39,7 @@ const data: ReferenceEntityTemplateSchema = {
         To block checkout progress, you must set the [block_progress](/docs/api/checkout-ui-extensions/configuration#block-progress) capability in your extension's configuration.
         If you do, then you're expected to inform the buyer why navigation was blocked, either by passing validation errors to the checkout UI or rendering the errors in your extension.
         \`useBuyerJourneyIntercept()\` should be called at the top level of the extension, not within an embedded or child component, to avoid errors should the child component get destroyed.
+        It is good practice to show a warning in the checkout editor when the merchant has not given permission for your extension to block checkout progress.
       `,
       type: 'UseBuyerJourneyInterceptGeneratedType',
     },

packages/ui-extensions/docs/surfaces/checkout/reference/examples/buyer-journey-intercept/extension-banner.example.tsx

@@ -2,7 +2,11 @@ import '@shopify/ui-extensions/preact';
 import {render} from 'preact';
 import {useState} from 'preact/hooks';
 
-import {useBuyerJourneyIntercept} from '@shopify/ui-extensions/checkout/preact';
+import {
+  useBuyerJourneyIntercept,
+  useExtensionEditor,
+  useExtensionCapability,
+} from '@shopify/ui-extensions/checkout/preact';
 
 export default function extension() {
   render(<Extension />, document.body);
@@ -11,6 +15,9 @@ export default function extension() {
 function Extension() {
   const [showError, setShowError] =
     useState(false);
+  const editorType = useExtensionEditor()?.type;
+  const blockProgressGranted =
+    useExtensionCapability('block_progress');
 
   useBuyerJourneyIntercept(
     ({canBlockProgress}) => {
@@ -34,9 +41,25 @@ function Extension() {
     },
   );
 
-  return showError ? (
-    <s-banner tone="critical">
-      This item has a limit of one per customer.
-    </s-banner>
-  ) : null;
+  return (
+    <>
+      {editorType === 'checkout' &&
+      !blockProgressGranted ? (
+        <s-banner
+          tone="warning"
+          heading="This app may be misconfigured"
+        >
+          To allow this app to block checkout,
+          enable this behavior in "Checkout
+          behavior" settings.
+        </s-banner>
+      ) : null}
+      {showError ? (
+        <s-banner tone="critical">
+          This item has a limit of one per
+          customer.
+        </s-banner>
+      ) : null}
+    </>
+  );
 }

packages/ui-extensions/docs/surfaces/checkout/reference/examples/buyer-journey-intercept/page-level-error.example.tsx

@@ -1,13 +1,21 @@
 import '@shopify/ui-extensions/preact';
 import {render} from 'preact';
 
-import {useBuyerJourneyIntercept} from '@shopify/ui-extensions/checkout/preact';
+import {
+  useBuyerJourneyIntercept,
+  useExtensionEditor,
+  useExtensionCapability,
+} from '@shopify/ui-extensions/checkout/preact';
 
 export default function extension() {
   render(<Extension />, document.body);
 }
 
 function Extension() {
+  const editorType = useExtensionEditor()?.type;
+  const blockProgressGranted =
+    useExtensionCapability('block_progress');
+
   useBuyerJourneyIntercept(
     ({canBlockProgress}) => {
       return canBlockProgress &&
@@ -32,5 +40,19 @@ function Extension() {
     },
   );
 
-  return null;
+  return (
+    <>
+      {editorType === 'checkout' &&
+      !blockProgressGranted ? (
+        <s-banner
+          tone="warning"
+          heading="This app may be misconfigured"
+        >
+          To allow this app to block checkout,
+          enable this behavior in "Checkout
+          behavior" settings.
+        </s-banner>
+      ) : null}
+    </>
+  );
 }

packages/ui-extensions/docs/surfaces/checkout/reference/examples/buyer-journey-intercept/target-native-field.example.tsx

@@ -1,13 +1,21 @@
 import '@shopify/ui-extensions/preact';
 import {render} from 'preact';
 
-import {useBuyerJourneyIntercept} from '@shopify/ui-extensions/checkout/preact';
+import {
+  useBuyerJourneyIntercept,
+  useExtensionEditor,
+  useExtensionCapability,
+} from '@shopify/ui-extensions/checkout/preact';
 
 export default function extension() {
   render(<Extension />, document.body);
 }
 
 function Extension() {
+  const editorType = useExtensionEditor()?.type;
+  const blockProgressGranted =
+    useExtensionCapability('block_progress');
+
   useBuyerJourneyIntercept(
     ({canBlockProgress}) => {
       return canBlockProgress &&
@@ -39,5 +47,19 @@ function Extension() {
     },
   );
 
-  return null;
+  return (
+    <>
+      {editorType === 'checkout' &&
+      !blockProgressGranted ? (
+        <s-banner
+          tone="warning"
+          heading="This app may be misconfigured"
+        >
+          To allow this app to block checkout,
+          enable this behavior in "Checkout
+          behavior" settings.
+        </s-banner>
+      ) : null}
+    </>
+  );
 }

packages/ui-extensions/docs/surfaces/checkout/reference/examples/extension-targets.example.toml

@@ -1,4 +1,4 @@
-api_version = "2025-10"
+api_version = "2026-01"
 
 [[extensions]]
 name = "My checkout extension"

packages/ui-extensions/docs/surfaces/checkout/reference/examples/settings.example.toml

@@ -1,24 +1,24 @@
-api_version = "2025-10"
+api_version = "2026-01"
 
 [[extensions]]
 name = "My checkout extension"
 handle = "checkout-ui"
 uid = "fddfc370-27c7-c30f-4ee0-a927194e2accadefd40c"
 type = "ui_extension"
 
-  [[extensions.targeting]]
-  target = "purchase.checkout.block.render"
-  module = "./Checkout.jsx"
+[[extensions.targeting]]
+target = "purchase.checkout.block.render"
+module = "./Checkout.jsx"
 
-  [extensions.settings]
-    [[extensions.settings.fields]]
-    key = "banner_title"
-    type = "single_line_text_field"
-    name = "Banner title"
-    description = "Enter a title for the banner."
-    [[extensions.settings.fields.validations]]
-    name = "min"
-    value = "5"
-    [[extensions.settings.fields.validations]]
-    name = "max"
-    value = "20"
+[extensions.settings]
+[[extensions.settings.fields]]
+key = "banner_title"
+type = "single_line_text_field"
+name = "Banner title"
+description = "Enter a title for the banner."
+[[extensions.settings.fields.validations]]
+name = "min"
+value = "5"
+[[extensions.settings.fields.validations]]
+name = "max"
+value = "20"

packages/ui-extensions/docs/surfaces/checkout/staticPages/examples/configuration/default.example.toml

@@ -1,12 +1,11 @@
-api_version = "2025-10"
+api_version = "2026-01"
 
 [[extensions]]
 type = "ui_extension"
 name = "Your checkout extension"
 handle = "checkout-ui"
 uid = "fddfc370-27c7-c30f-4ee0-a927194e2accadefd40c"
 
-  [[extensions.targeting]]
-  target = "purchase.checkout.block.render"
-  module = "./Extension.jsx"
-
+[[extensions.targeting]]
+target = "purchase.checkout.block.render"
+module = "./Extension.jsx"

packages/ui-extensions/docs/surfaces/checkout/staticPages/examples/configuration/extended.example.toml

@@ -1,4 +1,4 @@
-api_version = "2025-10"
+api_version ="2026-01"
 
 [[extensions]]
 type = "ui_extension"

packages/ui-extensions/docs/surfaces/checkout/staticPages/examples/configuration/settings.example.toml

@@ -1,4 +1,4 @@
-api_version = "2025-10"
+api_version = "2026-01"
 
 [[extensions]]
 type = "ui_extension"