@shopify/ui-extensions 2026.1.2 → 2026.1.4

package/package.json

@@ -1,11 +1,9 @@
 {
   "name": "@shopify/ui-extensions",
-  "version": "2026.1.2",
+  "version": "2026.1.4",
   "scripts": {
     "docs:admin": "node ./docs/surfaces/admin/build-docs.mjs",
     "docs:checkout": "bash ./docs/surfaces/checkout/build-docs.sh",
-    "docs:checkout:fast": "bash ./docs/surfaces/checkout/build-docs-fast.sh",
-    "docs:checkout:dev": "bash ./docs/surfaces/checkout/build-docs-watch.sh",
     "docs:point-of-sale": "node ./docs/surfaces/point-of-sale/build-docs.mjs",
     "docs:customer-account": "node ./docs/surfaces/customer-account/build-docs.mjs"
   },
@@ -129,7 +127,7 @@
   ],
   "devDependencies": {
     "@remote-ui/async-subscription": "^2.1.16",
-    "@shopify/generate-docs": "https://registry.npmjs.org/@shopify/generate-docs/-/generate-docs-0.19.8.tgz",
+    "@shopify/generate-docs": "1.2.2",
     "@quilted/react-testing": "^0.6.11",
     "typescript": "^4.9.0",
     "@faker-js/faker": "^8.4.1",

package/src/shared.ts

@@ -14,22 +14,23 @@ export type ApiVersion =
   | 'unstable'
   | '2025-07'
   | '2025-10'
-  | '2026-01';
+  | '2026-01'
+  | '2026-04';
 
 /**
  * The capabilities an extension has access to.
  *
- * * [`api_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#api-access): the extension can access the Storefront API.
+ * * `api_access`: The extension can access the Storefront API.
  *
- * * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls.
+ * * `network_access`: The extension can make external network calls.
  *
- * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
+ * * `block_progress`: The extension can block a buyer's progress and the merchant has allowed this blocking behavior.
  *
- * * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect buyer consent for SMS marketing.
+ * * `collect_buyer_consent.sms_marketing`: The extension can collect buyer consent for SMS marketing.
  *
- * * [`collect_buyer_consent.customer_privacy`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can register buyer consent decisions that will be honored on Shopify-managed services.
+ * * `collect_buyer_consent.customer_privacy`: The extension can register buyer consent decisions that will be honored on Shopify-managed services.
  *
- * * [`iframe.sources`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#iframe): the extension can embed an external URL in an iframe.
+ * * `iframe.sources`: The extension can embed an external URL in an iframe.
  */
 
 export type Capability =
@@ -849,10 +850,14 @@ export type CountryCode =
   | 'ZW'
   | 'ZZ';
 
+/**
+ * A buyer's country, identified by its ISO country code.
+ */
 export interface Country {
   /**
-   * The ISO-3166-1 code for this country.
-   * @see https://www.iso.org/iso-3166-country-codes.html
+   * The two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
+   *
+   * @example 'CA' for Canada, 'US' for United States.
    */
   isoCode: CountryCode;
 }
@@ -901,7 +906,7 @@ export type LocalizedFieldKey =
   | 'TAX_EMAIL_IT';
 
 /**
- * Union of supported storefront API versions
+ * The supported Storefront API versions. Pass one of these values to `query()` to target a specific API version when querying the Storefront GraphQL API.
  */
 export type StorefrontApiVersion =
   | '2022-04'
@@ -920,21 +925,37 @@ export type StorefrontApiVersion =
   | '2025-07'
   | '2025-10';
 
+/**
+ * A buyer's country, identified by its ISO country code.
+ */
 export interface Country {
   /**
-   * The ISO-3166-1 code for this country.
-   * @see https://www.iso.org/iso-3166-country-codes.html
+   * The two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
+   *
+   * @example 'CA' for Canada, 'US' for United States.
    */
   isoCode: CountryCode;
 }
 
 /**
- * GraphQL error returned by the Shopify Storefront APIs.
+ * An error returned by the Storefront GraphQL API. Contains a human-readable `message` and an `extensions` object with the request ID and error code for debugging.
  */
 export interface GraphQLError {
+  /**
+   * A human-readable description of the error.
+   */
   message: string;
+  /**
+   * Additional error metadata including the request ID and error code.
+   */
   extensions: {
+    /**
+     * The unique identifier for the API request, useful for debugging with Shopify support.
+     */
     requestId: string;
+    /**
+     * A machine-readable error code identifying the type of error.
+     */
     code: string;
   };
 }

package/src/surfaces/admin/api/action/action.ts

@@ -4,6 +4,8 @@ import type {Data} from '../shared';
 
 /**
  * The `ActionExtensionApi` object provides methods for action extensions that render in modal overlays. Access the following properties on the `ActionExtensionApi` object to interact with the current context, control the modal, and display picker dialogs.
+ *
+ * @publicDocs
  */
 export interface ActionExtensionApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardRenderingExtensionApi<ExtensionTarget> {

package/src/surfaces/admin/api/block/block.ts

@@ -4,6 +4,7 @@ import type {Data} from '../shared';
 
 /**
  * The `Navigation` object provides methods for navigating between extensions and admin pages.
+ * @publicDocs
  */
 export interface Navigation {
   /**
@@ -17,6 +18,8 @@ export interface Navigation {
 
 /**
  * The `BlockExtensionApi` object provides methods for block extensions that render inline content on admin pages. Access the following properties on the `BlockExtensionApi` object to interact with the current context, navigate to other extensions, and display picker dialogs.
+ *
+ * @publicDocs
  */
 export interface BlockExtensionApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardRenderingExtensionApi<ExtensionTarget> {

package/src/surfaces/admin/api/checkout-rules/launch-options.ts

@@ -36,6 +36,8 @@ interface ShopifyFunction {
 
 /**
  * The `data` object exposed to validation settings extensions in the `admin.settings.validation.render` target. Use this to access the current validation configuration and populate your settings interface with existing values.
+ *
+ * @publicDocs
  */
 export interface ValidationData {
   /** The validation configuration containing the validation ID and metafields. Present when editing an existing validation, absent when creating a new validation. Use the presence of this value to determine if you're in create or edit mode. */

package/src/surfaces/admin/api/checkout-rules/metafields.ts

@@ -60,6 +60,8 @@ type MetafieldChangeResult =
 
 /**
  * A function that applies metafield changes to validation settings. Call this function with an update or removal operation, then await the Promise to receive a result indicating success or failure. Use the result to provide feedback or handle errors in your settings interface.
+ *
+ * @publicDocs
  */
 export type ApplyMetafieldChange = (
   change: MetafieldChange,

package/src/surfaces/admin/api/customer-segment-template/customer-segment-template.ts

@@ -4,6 +4,8 @@ import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-target
 
 /**
  * The `CustomerSegmentTemplateApi` object provides methods for creating customer segment templates. Access the following properties on the `CustomerSegmentTemplateApi` object to build templates with translated content.
+ *
+ * @publicDocs
  */
 export interface CustomerSegmentTemplateApi<
   ExtensionTarget extends AnyExtensionTarget,

package/src/surfaces/admin/api/discount-function-settings/launch-options.ts

@@ -24,14 +24,7 @@ interface Metafield {
 /**
  * The discount class that determines where the discount applies in the purchase flow. Use this to understand what type of discount the merchant is configuring (product-level, order-level, or shipping).
  */
-export enum DiscountClass {
-  /** The discount applies to specific products or product variants. Use this for discounts that reduce the price of individual line items (for example, "20% off selected products"). */
-  Product = 'PRODUCT',
-  /** The discount applies to the entire order total. Use this for cart-wide discounts that reduce the subtotal (for example, "$10 off orders over $50"). */
-  Order = 'ORDER',
-  /** The discount applies to shipping costs. Use this for free shipping or reduced shipping rate discounts (for example, "Free shipping on orders over $100"). */
-  Shipping = 'SHIPPING',
-}
+export type DiscountClass = 'product' | 'order' | 'shipping';
 
 /**
  * The method used to apply a discount. Use `'automatic'` for discounts that apply automatically at checkout, or `'code'` for discounts that require a code entered by the customer.
@@ -40,6 +33,8 @@ type DiscountMethod = 'automatic' | 'code';
 
 /**
  * The `data` object exposed to discount function settings extensions in the `admin.discount-details.function-settings.render` target. Use this to access the current discount configuration and populate your settings interface with existing values.
+ *
+ * @publicDocs
  */
 export interface DiscountFunctionSettingsData {
   /** The discount's unique global identifier (GID) in the [GraphQL Admin API](/docs/api/admin-graphql) format (for example, `gid://shopify/DiscountAutomaticApp/123`). Use this ID to associate settings with the correct discount or query discount data. */

package/src/surfaces/admin/api/discount-function-settings/metafields.ts

@@ -60,6 +60,8 @@ type MetafieldChangeResult =
 
 /**
  * A function that applies metafield changes to discount function settings. Call this function with an update or removal operation, then await the Promise to receive a result indicating success or failure. Use the result to provide feedback or handle errors in your settings interface.
+ *
+ * @publicDocs
  */
 export type ApplyMetafieldChange = (
   change: MetafieldChange,

package/src/surfaces/admin/api/intents/intents.ts

@@ -37,6 +37,8 @@ export interface ErrorIntentResponse {
 
 /**
  * The result of an intent workflow. Check the `code` property to determine the outcome: `'ok'` for success, `'error'` for failure, or `'closed'` if the merchant cancelled.
+ *
+ * @publicDocs
  */
 export type IntentResponse =
   | SuccessIntentResponse
@@ -127,6 +129,8 @@ export interface IntentQuery extends IntentQueryOptions {
  * });
  * const response = await activity.complete;
  * ```
+ *
+ * @publicDocs
  */
 export interface IntentInvokeApi {
   (query: IntentQuery): Promise<IntentActivity>;

package/src/surfaces/admin/api/order-routing-rule/order-routing-rule.ts

@@ -6,6 +6,8 @@ import {Data} from './data';
 
 /**
  * The `OrderRoutingRuleApi` object provides methods for configuring order routing rules. Access the following properties on the `OrderRoutingRuleApi` object to manage rule settings and metafields.
+ *
+ * @publicDocs
  */
 export interface OrderRoutingRuleApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardRenderingExtensionApi<ExtensionTarget> {

package/src/surfaces/admin/api/picker/picker.ts

@@ -108,5 +108,7 @@ interface Item {
 
 /**
  * The `picker` function opens a custom selection dialog with your app-specific data. It accepts configuration options to define the picker's heading, items, headers, and selection behavior. It returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.
+ *
+ * @publicDocs
  */
 export type PickerApi = (options: PickerOptions) => Promise<Picker>;

package/src/surfaces/admin/api/print-action/examples/custom-product-labels.jsx

@@ -1,5 +1,5 @@
 import {render} from 'preact';
-import {useState} from 'preact/hooks';
+import {useState, useCallback} from 'preact/hooks';
 
 export default async () => {
   render(<Extension />, document.body);
@@ -7,38 +7,41 @@ export default async () => {
 
 function Extension() {
   const {data} = shopify;
-  const [additionalCount, setAdditionalCount] = useState(0);
+  const [additionalProducts, setAdditionalProducts] = useState([]);
+  const [printUrl, setPrintUrl] = useState(null);
 
   const handleSelectMore = async () => {
-    const additionalProducts = await shopify.resourcePicker({
+    const picked = await shopify.resourcePicker({
       type: 'product',
       multiple: 10,
       action: 'add',
     });
 
-    if (additionalProducts) {
-      setAdditionalCount(additionalProducts.length);
+    if (picked) {
+      setAdditionalProducts((prev) => [...prev, ...picked]);
     }
   };
 
-  const handleGenerate = async () => {
-    const productIds = data.selected.map((item) => item.id);
-    
+  const handleGenerate = useCallback(async () => {
+    const selectedIds = data.selected.map((item) => item.id);
+    const additionalIds = additionalProducts.map((item) => item.id);
+    const productIds = [...selectedIds, ...additionalIds];
+
     const response = await fetch('/api/generate-labels', {
       method: 'POST',
       headers: {'Content-Type': 'application/json'},
       body: JSON.stringify({productIds}),
     });
 
-    const {printUrl} = await response.json();
-    return printUrl;
-  };
+    const {printUrl: url} = await response.json();
+    setPrintUrl(url);
+  }, [data, additionalProducts]);
 
   return (
-    <s-admin-print-action onPrint={handleGenerate}>
-      <s-text>{data.selected.length} products selected</s-text>
+    <s-admin-print-action src={printUrl}>
+      <s-text>{data.selected.length + additionalProducts.length} products selected</s-text>
       <s-button onClick={handleSelectMore}>Add More Products</s-button>
-      {additionalCount > 0 && <s-text>+{additionalCount} additional</s-text>}
+      <s-button onClick={handleGenerate}>Generate Labels</s-button>
     </s-admin-print-action>
   );
 }

package/src/surfaces/admin/api/print-action/examples/generate-packing-slip.jsx

@@ -1,4 +1,5 @@
 import {render} from 'preact';
+import {useState, useEffect} from 'preact/hooks';
 
 export default async () => {
   render(<Extension />, document.body);
@@ -6,23 +7,28 @@ export default async () => {
 
 function Extension() {
   const {data} = shopify;
+  const [printUrl, setPrintUrl] = useState(null);
 
-  const handleGenerate = async () => {
-    const orderIds = data.selected.map((item) => item.id);
+  useEffect(() => {
+    const generateSlip = async () => {
+      const orderIds = data.selected.map((item) => item.id);
 
-    const response = await fetch('/api/generate-packing-slip', {
-      method: 'POST',
-      headers: {'Content-Type': 'application/json'},
-      body: JSON.stringify({orderIds}),
-    });
+      const response = await fetch('/api/generate-packing-slip', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({orderIds}),
+      });
 
-    const {printUrl} = await response.json();
-    return printUrl;
-  };
+      const {printUrl: url} = await response.json();
+      setPrintUrl(url);
+    };
+
+    generateSlip();
+  }, [data]);
 
   return (
-    <s-admin-print-action onPrint={handleGenerate}>
-      <s-text>Generating packing slip for {data.selected.length} orders</s-text>
+    <s-admin-print-action src={printUrl}>
+      <s-text>Packing slip for {data.selected.length} orders</s-text>
     </s-admin-print-action>
   );
 }

package/src/surfaces/admin/api/print-action/examples/shipping-manifest.jsx

@@ -8,6 +8,7 @@ export default async () => {
 function Extension() {
   const {data} = shopify;
   const [orders, setOrders] = useState([]);
+  const [printUrl, setPrintUrl] = useState(null);
 
   useEffect(() => {
     const fetchOrders = async () => {
@@ -31,24 +32,22 @@ function Extension() {
       );
 
       setOrders(ordersData.nodes);
+
+      const response = await fetch('/api/generate-shipping-manifest', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({orders: ordersData.nodes}),
+      });
+
+      const {printUrl: url} = await response.json();
+      setPrintUrl(url);
     };
 
     fetchOrders();
   }, [data]);
 
-  const handleGenerate = async () => {
-    const response = await fetch('/api/generate-shipping-manifest', {
-      method: 'POST',
-      headers: {'Content-Type': 'application/json'},
-      body: JSON.stringify({orders}),
-    });
-
-    const {printUrl} = await response.json();
-    return printUrl;
-  };
-
   return (
-    <s-admin-print-action onPrint={handleGenerate}>
+    <s-admin-print-action src={printUrl}>
       <s-text>Shipping manifest for {orders.length} orders</s-text>
       {orders.map((order) => (
         <s-text key={order.id}>{order.name}</s-text>

package/src/surfaces/admin/api/print-action/print-action.ts

@@ -4,6 +4,8 @@ import type {Data} from '../shared';
 
 /**
  * The `PrintActionExtensionApi` object provides methods for print action extensions that generate custom printable documents. Access the following properties on the `PrintActionExtensionApi` object to access selected resources and display picker dialogs for print configuration.
+ *
+ * @publicDocs
  */
 export interface PrintActionExtensionApi<
   ExtensionTarget extends AnyExtensionTarget,

package/src/surfaces/admin/api/product-configuration/product-details-configuration.ts

@@ -65,6 +65,8 @@ export interface ProductComponent {
 
 /**
  * The `ProductDetailsConfigurationApi` object provides methods for configuring product bundles and relationships. Access the following properties on the `ProductDetailsConfigurationApi` object to build product configuration interfaces.
+ *
+ * @publicDocs
  */
 export interface ProductDetailsConfigurationApi<
   ExtensionTarget extends AnyExtensionTarget,

package/src/surfaces/admin/api/product-configuration/product-variant-details-configuration.ts

@@ -66,6 +66,8 @@ export interface ProductVariantComponent {
 
 /**
  * The `ProductVariantDetailsConfigurationApi` object provides methods for configuring product variant bundles and relationships. Access the following properties on the `ProductVariantDetailsConfigurationApi` object to build variant configuration interfaces.
+ *
+ * @publicDocs
  */
 export interface ProductVariantDetailsConfigurationApi<
   ExtensionTarget extends AnyExtensionTarget,

package/src/surfaces/admin/api/purchase-options-card-action.ts

@@ -3,6 +3,8 @@ import type {ExtensionTarget as AnyExtensionTarget} from '../extension-targets';
 
 /**
  * The `PurchaseOptionsCardConfigurationApi` object provides methods for action extensions that interact with purchase options and selling plans. Access the following properties on the `PurchaseOptionsCardConfigurationApi` object to work with selected products and their associated subscription configurations.
+ *
+ * @publicDocs
  */
 export interface PurchaseOptionsCardConfigurationApi<
   ExtensionTarget extends AnyExtensionTarget,

package/src/surfaces/admin/api/resource-picker/resource-picker.ts

@@ -323,8 +323,10 @@ type WithSelection<T> = T & {
 
 /**
  * The payload returned when resources are selected from the picker.
+ *
+ * @publicDocs
  */
-type SelectPayload<Type extends keyof ResourceTypes> = WithSelection<
+export type SelectPayload<Type extends keyof ResourceTypes> = WithSelection<
   ResourceSelection<Type>[]
 >;
 
@@ -360,6 +362,8 @@ interface Filters {
 
 /**
  * The `ResourcePickerOptions` object defines how the resource picker behaves, including which resource type to display, selection limits, filters, and preselected items. Access the following properties on the `ResourcePickerOptions` object to configure the resource picker's appearance and functionality.
+ *
+ * @publicDocs
  */
 export interface ResourcePickerOptions {
   /**
@@ -394,6 +398,8 @@ export interface ResourcePickerOptions {
 
 /**
  * Opens the resource picker modal for selecting products, variants, or collections. Returns the selected resources when the user confirms their selection, or undefined if they cancel.
+ *
+ * @publicDocs
  */
 export type ResourcePickerApi = (
   options: ResourcePickerOptions,

package/src/surfaces/admin/api/should-render/should-render.ts

@@ -12,6 +12,8 @@ export interface ShouldRenderOutput {
 
 /**
  * The `ShouldRenderApi` object provides methods for controlling action extension visibility. Access the following properties on the `ShouldRenderApi` object to determine whether an associated action should appear based on the current context.
+ *
+ * @publicDocs
  */
 export interface ShouldRenderApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardApi<ExtensionTarget> {

package/src/surfaces/admin/api/standard/standard.ts

@@ -37,6 +37,8 @@ interface Auth {
 
 /**
  * The `StandardApi` object provides core methods available to all extension targets. Access the following properties on the `StandardApi` object to authenticate users, query the [GraphQL Admin API](/docs/api/admin-graphql), translate content, handle intents, and persist data.
+ *
+ * @publicDocs
  */
 export interface StandardApi<ExtensionTarget extends AnyExtensionTarget> {
   /**

package/src/surfaces/admin/components/ActionExtensionComponents.ts

@@ -1,7 +1,7 @@
 import {StandardComponents} from './StandardComponents';
 
 /**
- * The components available for building action extensions. Includes all standard components plus the `AdminAction` component required for action extension setup.
+ * The components available for building action extensions. Includes all standard components plus the admin action component required for action extension setup.
  */
 export type ActionExtensionComponents = StandardComponents | 'AdminAction';
 

package/src/surfaces/admin/components/{ButtonGroup/examples/default.jsx → AdminAction/examples/default.html}

@@ -1,4 +1,5 @@
-<s-button-group>
+<s-admin-action heading="My App Action">
+  Modal content
   <s-button slot="primary-action">Save</s-button>
   <s-button slot="secondary-actions">Cancel</s-button>
-</s-button-group>
+</s-admin-action>

package/src/surfaces/admin/components/AdminAction/examples/destructive-action.html

@@ -0,0 +1,10 @@
+<s-admin-action heading="Delete product">
+  <s-stack direction="block" gap="base">
+    <s-banner tone="critical">
+      This will permanently delete the product and all its variants. This action cannot be undone.
+    </s-banner>
+    <s-text>Product: Winter Jacket — 12 variants</s-text>
+  </s-stack>
+  <s-button slot="primary-action" variant="primary" tone="critical">Delete product</s-button>
+  <s-button slot="secondary-actions">Cancel</s-button>
+</s-admin-action>

package/src/surfaces/admin/components/AdminAction/examples/loading-state.html

@@ -0,0 +1,5 @@
+<s-admin-action heading="Loading order details" loading>
+  <s-text>Fetching data…</s-text>
+  <s-button slot="primary-action" disabled>Save</s-button>
+  <s-button slot="secondary-actions">Cancel</s-button>
+</s-admin-action>

package/src/surfaces/admin/components/AdminAction/examples/with-form-content.html

@@ -0,0 +1,8 @@
+<s-admin-action heading="Edit shipping settings">
+  <s-stack direction="block" gap="base">
+    <s-text-field label="Shipping rate name" value="Standard shipping"></s-text-field>
+    <s-number-field label="Flat rate amount" prefix="$" value="5.99"></s-number-field>
+  </s-stack>
+  <s-button slot="primary-action" variant="primary">Save changes</s-button>
+  <s-button slot="secondary-actions">Discard</s-button>
+</s-admin-action>

package/src/surfaces/admin/components/AdminAction/examples/with-resource-details.html

@@ -0,0 +1,15 @@
+<s-admin-action heading="Order summary">
+  <s-stack direction="block" gap="base">
+    <s-stack direction="block" gap="small">
+      <s-text type="strong">Order #1042</s-text>
+      <s-text>3 items · $129.97</s-text>
+    </s-stack>
+    <s-divider></s-divider>
+    <s-stack direction="block" gap="small">
+      <s-text>Shipping: Standard (3–5 days)</s-text>
+      <s-text>Status: <s-badge tone="info">Unfulfilled</s-badge></s-text>
+    </s-stack>
+  </s-stack>
+  <s-button slot="primary-action" variant="primary">Fulfill order</s-button>
+  <s-button slot="secondary-actions">Close</s-button>
+</s-admin-action>