@shopify/ui-extensions 2025.10.13 → 2025.10.14

package/src/surfaces/admin/api/order-routing-rule/examples/configure-location-priority.jsx

@@ -0,0 +1,46 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const [preferred, setPreferred] = useState('gid://shopify/Location/123456789');
+  const [fallback, setFallback] = useState('gid://shopify/Location/987654321');
+
+  const handleSave = () => {
+    shopify.applyMetafieldsChange([
+      {
+        type: 'updateMetafield',
+        namespace: 'routing',
+        key: 'preferred_location',
+        value: preferred,
+        valueType: 'single_line_text_field',
+      },
+      {
+        type: 'updateMetafield',
+        namespace: 'routing',
+        key: 'fallback_location',
+        value: fallback,
+        valueType: 'single_line_text_field',
+      },
+    ]);
+  };
+
+  return (
+    <s-function-settings>
+      <s-text-field
+        label="Preferred location ID"
+        value={preferred}
+        onChange={(value) => setPreferred(value)}
+      />
+      <s-text-field
+        label="Fallback location ID"
+        value={fallback}
+        onChange={(value) => setFallback(value)}
+      />
+      <s-button onClick={handleSave}>Save Location Priority</s-button>
+    </s-function-settings>
+  );
+}

package/src/surfaces/admin/api/order-routing-rule/examples/remove-deprecated-settings.jsx

@@ -0,0 +1,35 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [removed, setRemoved] = useState(false);
+
+  const handleRemove = () => {
+    const deprecatedKeys = ['old_setting', 'legacy_config'];
+
+    const changes = deprecatedKeys.map((key) => ({
+      type: 'removeMetafield',
+      namespace: 'routing',
+      key,
+    }));
+
+    shopify.applyMetafieldsChange(changes);
+    setRemoved(true);
+  };
+
+  return (
+    <s-function-settings>
+      <s-stack direction="block">
+        <s-text>Rule priority: {data.rule.priority}</s-text>
+        <s-text>Current settings: {data.rule.metafields.length}</s-text>
+        <s-button onClick={handleRemove}>Remove Deprecated Settings</s-button>
+        {removed && <s-banner status="success">Deprecated settings removed</s-banner>}
+      </s-stack>
+    </s-function-settings>
+  );
+}

package/src/surfaces/admin/api/order-routing-rule/examples/set-routing-criteria.jsx

@@ -0,0 +1,57 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [distance, setDistance] = useState('50');
+  const [enableInventory, setEnableInventory] = useState(true);
+
+  const handleSave = () => {
+    shopify.applyMetafieldsChange([
+      {
+        type: 'updateMetafield',
+        namespace: 'routing',
+        key: 'max_distance_km',
+        value: distance,
+        valueType: 'number_integer',
+      },
+      {
+        type: 'updateMetafield',
+        namespace: 'routing',
+        key: 'enable_inventory_check',
+        value: String(enableInventory),
+        valueType: 'boolean',
+      },
+      {
+        type: 'updateMetafield',
+        namespace: 'routing',
+        key: 'excluded_zip_codes',
+        value: JSON.stringify(['10001', '90210']),
+        valueType: 'json',
+      },
+    ]);
+  };
+
+  return (
+    <s-function-settings>
+      <s-stack direction="block">
+        <s-number-field
+          label="Maximum distance (km)"
+          value={distance}
+          onChange={(value) => setDistance(value)}
+        />
+        <s-checkbox
+          checked={enableInventory}
+          onChange={(checked) => setEnableInventory(checked)}
+        >
+          Enable inventory check
+        </s-checkbox>
+        <s-button onClick={handleSave}>Save Routing Criteria</s-button>
+      </s-stack>
+    </s-function-settings>
+  );
+}

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

@@ -43,25 +43,49 @@ const supportedDefinitionTypes = [
   'list.weight',
 ] as const;
 
+/**
+ * A metafield update or creation operation. Use this to set or modify metafield values that store order routing rule configuration data.
+ */
 interface MetafieldUpdateChange {
+  /** Identifies this as an update operation. Always set to `'updateMetafield'` for updates. */
   type: 'updateMetafield';
+  /** The unique key identifying the metafield within its namespace. Use descriptive keys that indicate the setting's purpose (for example, `'preferred_location'` or `'routing_priority'`). */
   key: string;
+  /** The namespace that organizes related metafields. When omitted, a default namespace is assigned. Use consistent namespaces to group related settings. */
   namespace?: string;
+  /** The metafield value to store. Can be a string or number depending on your configuration needs. */
   value: string | number;
+  /** The [data type](/docs/apps/build/metafields/list-of-data-types) that defines how the value is formatted and validated. When omitted, preserves the existing type for updates or uses a default for new metafields. Choose a type that matches your value format. */
   valueType?: SupportedDefinitionType;
 }
 
+/**
+ * A metafield removal operation. Use this to delete metafields that are no longer needed for your order routing rule configuration.
+ */
 interface MetafieldRemoveChange {
+  /** Identifies this as a removal operation. Always set to `'removeMetafield'` for deletions. */
   type: 'removeMetafield';
+  /** The unique key of the metafield to remove. Must match the key used when the metafield was created. */
   key: string;
+  /** The namespace containing the metafield to remove. Required to ensure the correct metafield is targeted, as the same key can exist in different namespaces. */
   namespace: string;
 }
 
+/**
+ * One or more metafield change operations to apply to order routing rule settings. Can be a single change or an array of changes for batch operations. Use arrays to apply multiple changes at once.
+ */
 type MetafieldsChange =
   | MetafieldUpdateChange
   | MetafieldRemoveChange
   | MetafieldUpdateChange[]
   | MetafieldRemoveChange[];
 
+/**
+ * The supported [metafield definition types](/docs/apps/build/metafields/list-of-data-types) for storing order routing rule configuration data. Use these types to specify how metafield values should be formatted, validated, and displayed. Types prefixed with `list.` store arrays of values, while other types store single values.
+ */
 export type SupportedDefinitionType = (typeof supportedDefinitionTypes)[number];
+
+/**
+ * A function that applies metafield changes to order routing rule settings. Call this function with one or more change operations to update or remove metafields in batch. Use batch operations to apply multiple configuration changes efficiently.
+ */
 export type ApplyMetafieldsChange = (changes: MetafieldsChange[]) => void;

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

@@ -4,8 +4,13 @@ import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-target
 import {ApplyMetafieldsChange} from './metafields';
 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.
+ */
 export interface OrderRoutingRuleApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardApi<ExtensionTarget> {
+  /** Updates or removes [metafields](/docs/apps/build/metafields) that store order routing rule configuration. */
   applyMetafieldsChange: ApplyMetafieldsChange;
+  /** The order routing rule being configured, including its metadata and associated [metafields](/docs/apps/build/metafields). */
   data: Data;
 }

package/src/surfaces/admin/api/picker/examples/direct-api.jsx

@@ -0,0 +1,42 @@
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const handlePick = async () => {
+    const r = await fetch('shopify:admin/api/graphql.json', {
+      method: 'POST',
+      body: JSON.stringify({
+        query: `query GetOrders($first: Int!) {
+          orders(first: $first) {
+            edges {
+              node {
+                id
+                name
+              }
+            }
+          }
+        }`,
+        variables: {first: 10},
+      }),
+    });
+    
+    const {data} = await r.json();
+    
+    await shopify.picker({
+      heading: 'Select orders',
+      items: data.orders.edges.map((edge) => ({
+        id: edge.node.id,
+        heading: edge.node.name,
+      })),
+    });
+  };
+
+  return (
+    <s-admin-block heading="Picker with GraphQL Data">
+      <s-button onClick={handlePick}>Open Order Picker</s-button>
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/picker/examples/disabled.jsx

@@ -0,0 +1,23 @@
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const handlePick = async () => {
+    await shopify.picker({
+      heading: 'Select items',
+      items: [
+        {id: '1', heading: 'Available item'},
+        {id: '2', heading: 'Disabled item', disabled: true},
+      ],
+    });
+  };
+
+  return (
+    <s-admin-block heading="Picker with Disabled Items">
+      <s-button onClick={handlePick}>Open Picker</s-button>
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/picker/examples/minimal.jsx

@@ -0,0 +1,37 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const [selected, setSelected] = useState(null);
+
+  const handlePick = async () => {
+    const pickerInstance = await shopify.picker({
+      heading: 'Select an item',
+      headers: [{title: 'Main heading'}],
+      items: [
+        {
+          id: '1',
+          heading: 'Item 1',
+        },
+        {
+          id: '2',
+          heading: 'Item 2',
+        },
+      ],
+    });
+
+    const result = await pickerInstance.selected;
+    setSelected(result);
+  };
+
+  return (
+    <s-admin-block heading="Simple Picker">
+      <s-button onClick={handlePick}>Open Picker</s-button>
+      {selected && <s-text>{selected.length} items selected</s-text>}
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/picker/examples/multiple-limit.jsx

@@ -0,0 +1,26 @@
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const handlePick = async () => {
+    await shopify.picker({
+      heading: 'Select items (up to 2)',
+      multiple: 2,
+      headers: [{title: 'Main heading'}],
+      items: [
+        {id: '1', heading: 'Item 1'},
+        {id: '2', heading: 'Item 2'},
+        {id: '3', heading: 'Item 3'},
+      ],
+    });
+  };
+
+  return (
+    <s-admin-block heading="Limited Selection Picker">
+      <s-button onClick={handlePick}>Open Picker</s-button>
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/picker/examples/multiple-true.jsx

@@ -0,0 +1,25 @@
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const handlePick = async () => {
+    await shopify.picker({
+      heading: 'Select items',
+      multiple: true,
+      items: [
+        {id: '1', heading: 'Item 1'},
+        {id: '2', heading: 'Item 2'},
+        {id: '3', heading: 'Item 3'},
+      ],
+    });
+  };
+
+  return (
+    <s-admin-block heading="Unlimited Selection Picker">
+      <s-button onClick={handlePick}>Open Picker</s-button>
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/picker/examples/preselected.jsx

@@ -0,0 +1,23 @@
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const handlePick = async () => {
+    await shopify.picker({
+      heading: 'Select items',
+      items: [
+        {id: '1', heading: 'Item 1', selected: true},
+        {id: '2', heading: 'Item 2'},
+      ],
+    });
+  };
+
+  return (
+    <s-admin-block heading="Picker with Preselection">
+      <s-button onClick={handlePick}>Open Picker</s-button>
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/picker/examples/template-picker.jsx

@@ -0,0 +1,58 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const [selected, setSelected] = useState(null);
+
+  const handlePickTemplate = async () => {
+    const pickerInstance = await shopify.picker({
+      heading: 'Select a template',
+      multiple: false,
+      headers: [
+        {title: 'Templates'},
+        {title: 'Created by'},
+        {title: 'Times used', type: 'number'},
+      ],
+      items: [
+        {
+          id: '1',
+          heading: 'Full width, 1 column',
+          data: ['Karine Ruby', '0'],
+          badges: [{content: 'Draft', tone: 'info'}, {content: 'Marketing'}],
+        },
+        {
+          id: '2',
+          heading: 'Large graphic, 3 column',
+          data: ['Russell Winfield', '5'],
+          badges: [
+            {content: 'Published', tone: 'success'},
+            {content: 'New feature'},
+          ],
+          selected: true,
+        },
+        {
+          id: '3',
+          heading: 'Promo header, 2 column',
+          data: ['Russel Winfield', '10'],
+          badges: [{content: 'Published', tone: 'success'}],
+        },
+      ],
+    });
+
+    const result = await pickerInstance.selected;
+    setSelected(result);
+  };
+
+  return (
+    <s-admin-block heading="Template Selector">
+      <s-button onClick={handlePickTemplate}>Choose Template</s-button>
+      {selected && selected.length > 0 && (
+        <s-text>Selected template: {selected[0]}</s-text>
+      )}
+    </s-admin-block>
+  );
+}

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

@@ -1,82 +1,112 @@
+/**
+ * A handle returned when opening a picker dialog. Use this to access the merchant's selection after they confirm or cancel the picker.
+ */
 interface Picker {
   /**
-   * A Promise that resolves with the selected item IDs when the user presses the "Select" button in the picker.
+   * A Promise that resolves with an array of selected item IDs when the merchant presses the **Select** button, or `undefined` if they cancel. Await this Promise to handle the selection result.
    */
   selected: Promise<string[] | undefined>;
 }
 
+/**
+ * The configuration for a table column header in the picker. Each header creates a labeled column that displays corresponding data from items.
+ */
 interface Header {
   /**
-   * The content to display in the table column header.
+   * The label text displayed at the top of the table column. Use clear, concise labels that describe the data in that column (for example, "Price", "Status", "Last Updated").
    */
   content?: string;
   /**
-   * The type of data to display in the column. The type is used to format the data in the column.
-   * If the type is 'number', the data in the column will be right-aligned, this should be used when referencing currency or numeric values.
-   * If the type is 'string', the data in the column will be left-aligned.
+   * The data type that controls column formatting and text alignment. Use `'number'` for currency, prices, or numeric values (displays right-aligned), or `'string'` for text content (displays left-aligned).
    * @defaultValue 'string'
    */
   type?: 'string' | 'number';
 }
 
+/**
+ * The configuration options for the custom picker dialog. Define the picker's appearance, selection behavior, and data structure.
+ */
 interface PickerOptions {
   /**
-   * The heading of the picker. This is displayed in the title of the picker modal.
+   * The heading displayed at the top of the picker modal. Use a clear, descriptive title that tells merchants what they're selecting.
    */
   heading: string;
   /**
-   * The data headers for the picker. These are used to display the table headers in the picker modal.
+   * The selection mode for the picker. Pass `true` to allow unlimited selections, `false` for single-item selection only, or a number to set a maximum selection limit (for example, `3` allows up to three items).
    */
   multiple?: boolean | number;
   /**
-   * The items to display in the picker. These are used to display the rows in the picker modal.
+   * The list of items that merchants can select from. Each item appears as a row in the picker table.
    */
   items: Item[];
   /**
-   * The data headers for the picker. These are used to display the table headers in the picker modal.
+   * The column headers for the picker table. Define headers to label and organize the data columns displayed for each item. The header order determines the column layout.
    */
   headers?: Header[];
 }
 
+/**
+ * The visual tone for picker badges indicating status or importance. Use different tones to communicate urgency or state: `'info'` for neutral information, `'success'` for positive states, `'warning'` for caution, or `'critical'` for urgent issues.
+ */
 export type Tone = 'info' | 'success' | 'warning' | 'critical';
+
+/**
+ * The progress state for picker badges showing completion status. Use this to indicate how complete an item is: `'incomplete'` for not started, `'partiallyComplete'` for in progress, or `'complete'` for finished.
+ */
 export type Progress = 'incomplete' | 'partiallyComplete' | 'complete';
+
+/**
+ * A single data point that can appear in a picker table cell. Can be text, a number, or undefined if the cell should be empty.
+ */
 type DataPoint = string | number | undefined;
+/**
+ * A badge displayed next to an item in the picker to show status or progress. Use badges to highlight important item attributes or states that affect selection decisions.
+ */
 interface PickerBadge {
+  /** The text content of the badge. Keep this short and descriptive (for example, "Draft", "Active", "Incomplete"). */
   content: string;
+  /** The visual tone indicating status or importance. Choose a tone that matches the badge's meaning. */
   tone?: Tone;
+  /** The progress indicator for the badge. Use this to show completion status for items that have progress states. */
   progress?: Progress;
 }
 
+/**
+ * An individual item that merchants can select in the picker. Each item appears as a row in the picker table.
+ */
 interface Item {
   /**
-   * The unique identifier of the item. This will be returned by the picker if selected.
+   * The unique identifier for this item. This ID is returned in the selection array when the merchant selects this item. Use an ID that helps you identify the item in your system (for example, template IDs, review IDs, or custom option keys).
    */
   id: string;
   /**
-   * The primary content to display in the first column of the row.
+   * The primary text displayed in the first column. This is typically the item's name or title and is the most prominent text in the row.
    */
   heading: string;
   /**
-   * The additional content to display in the second and third columns of the row, if provided.
+   * Additional data displayed in subsequent columns after the heading. Each value appears in its own column, and the order must match the `headers` array. For example, if headers are `["Price", "Status"]`, then data would be `[19.99, "Active"]`.
    */
   data?: DataPoint[];
   /**
-   * Whether the item is disabled or not. If the item is disabled, it cannot be selected.
+   * Whether the item can be selected. When `true`, the item is disabled and can't be selected. Disabled items appear grayed out and merchants can't choose them. Use this for items that are unavailable or don't meet selection criteria.
    * @defaultValue false
    */
   disabled?: boolean;
   /**
-   * Whether the item is selected or not when the picker is opened. The user may deselect the item if it is preselected.
+   * Whether the item is preselected when the picker opens. When `true`, the item appears selected by default. Merchants can still deselect preselected items. Use this to show current selections or suggest default choices.
    */
   selected?: boolean;
   /**
-   * The badges to display in the first column of the row. These are used to display additional information about the item, such as progress of an action or tone indicating the status of that item.
+   * Status or context badges displayed next to the heading in the first column. Use badges to highlight item state, completion status, or other important attributes (for example, "Draft", "Published", "Incomplete").
    */
   badges?: PickerBadge[];
   /**
-   * The thumbnail to display at the start of the row. This is used to display an image or icon for the item.
+   * A small preview image or icon displayed at the start of the row. Thumbnails help merchants visually identify items at a glance. Provide a URL to the image file.
    */
   thumbnail?: {url: string};
 }
 
+/**
+ * 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.
+ */
 export type PickerApi = (options: PickerOptions) => Promise<Picker>;

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

@@ -0,0 +1,47 @@
+import {render} from 'preact';
+import {useState, useCallback} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [additionalProducts, setAdditionalProducts] = useState([]);
+  const [printUrl, setPrintUrl] = useState(null);
+
+  const handleSelectMore = async () => {
+    const picked = await shopify.resourcePicker({
+      type: 'product',
+      multiple: 10,
+      action: 'add',
+    });
+
+    if (picked) {
+      setAdditionalProducts((prev) => [...prev, ...picked]);
+    }
+  };
+
+  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: url} = await response.json();
+    setPrintUrl(url);
+  }, [data, additionalProducts]);
+
+  return (
+    <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>
+      <s-button onClick={handleGenerate}>Generate Labels</s-button>
+    </s-admin-print-action>
+  );
+}

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

@@ -0,0 +1,34 @@
+import {render} from 'preact';
+import {useState, useEffect} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [printUrl, setPrintUrl] = useState(null);
+
+  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 {printUrl: url} = await response.json();
+      setPrintUrl(url);
+    };
+
+    generateSlip();
+  }, [data]);
+
+  return (
+    <s-admin-print-action src={printUrl}>
+      <s-text>Packing slip for {data.selected.length} orders</s-text>
+    </s-admin-print-action>
+  );
+}