@shopify/ui-extensions 2025.10.13 → 2025.10.14

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

@@ -0,0 +1,57 @@
+import {render} from 'preact';
+import {useState, useEffect} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [orders, setOrders] = useState([]);
+  const [printUrl, setPrintUrl] = useState(null);
+
+  useEffect(() => {
+    const fetchOrders = async () => {
+      const orderIds = data.selected.map((item) => item.id);
+
+      const {data: ordersData} = await shopify.query(
+        `query GetOrders($ids: [ID!]!) {
+          nodes(ids: $ids) {
+            ... on Order {
+              id
+              name
+              shippingAddress {
+                address1
+                city
+                country
+              }
+            }
+          }
+        }`,
+        {variables: {ids: orderIds}},
+      );
+
+      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]);
+
+  return (
+    <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>
+      ))}
+    </s-admin-print-action>
+  );
+}

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

@@ -4,21 +4,24 @@ import type {Data} from '../shared';
 import type {ResourcePickerApi} from '../resource-picker/resource-picker';
 import type {PickerApi} from '../picker/picker';
 
+/**
+ * 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.
+ */
 export interface PrintActionExtensionApi<
   ExtensionTarget extends AnyExtensionTarget,
 > extends StandardApi<ExtensionTarget> {
   /**
-   * Information about the currently viewed or selected items.
+   * An array of currently viewed or selected resource identifiers. Use this to access the IDs of items to include in the print document, such as selected orders or products.
    */
   data: Data;
 
   /**
-   * Renders the [Resource Picker](resource-picker), allowing users to select a resource for the extension to use as part of its flow.
+   * Opens the [Resource Picker API](/docs/api/admin-extensions/{API_VERSION}/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose additional resources to include in the print document.
    */
   resourcePicker: ResourcePickerApi;
 
   /**
-   * Renders a custom [Picker](picker) dialog allowing users to select values from a list.
+   * Opens a custom [Picker API](/docs/api/admin-extensions/{API_VERSION}/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose print settings or document configurations.
    */
   picker: PickerApi;
 }

package/src/surfaces/admin/api/product-configuration/examples/create-variant-component.jsx

@@ -0,0 +1,56 @@
+import {render} from 'preact';
+import {useState, useEffect} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [created, setCreated] = useState(null);
+  const [productId, setProductId] = useState(null);
+
+  useEffect(() => {
+    const getParentProduct = async () => {
+      const variantId = data.selected[0]?.id;
+
+      const {data: parentData} = await shopify.query(
+        `query GetParentProduct($id: ID!) {
+          productVariant(id: $id) {
+            product {
+              id
+            }
+          }
+        }`,
+        {variables: {id: variantId}},
+      );
+
+      setProductId(parentData.productVariant.product.id);
+    };
+
+    getParentProduct();
+  }, [data]);
+
+  const handleCreate = async () => {
+    const activity = await shopify.intents.invoke('create:shopify/ProductVariant', {
+      data: {productId},
+    });
+
+    const response = await activity.complete;
+
+    if (response.code === 'ok') {
+      setCreated(true);
+    }
+  };
+
+  return (
+    <s-admin-block heading="Add Variant Component">
+      {productId && (
+        <>
+          <s-button onClick={handleCreate}>Create Component Variant</s-button>
+          {created && <s-banner status="success">Component variant created</s-banner>}
+        </>
+      )}
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/product-configuration/examples/load-bundle-config.jsx

@@ -0,0 +1,47 @@
+import {render} from 'preact';
+import {useState, useEffect} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [components, setComponents] = useState([]);
+
+  useEffect(() => {
+    const loadConfig = async () => {
+      const productId = data.selected[0]?.id;
+
+      const {data: bundleData} = await shopify.query(
+        `query GetBundleComponents($id: ID!) {
+          product(id: $id) {
+            id
+            title
+            metafield(namespace: "bundle", key: "components") {
+              value
+            }
+          }
+        }`,
+        {variables: {id: productId}},
+      );
+
+      const comps = bundleData.product.metafield
+        ? JSON.parse(bundleData.product.metafield.value)
+        : [];
+
+      setComponents(comps);
+    };
+
+    loadConfig();
+  }, [data]);
+
+  return (
+    <s-admin-block heading="Current Bundle">
+      <s-text>{components.length} components configured</s-text>
+      {components.map((comp, i) => (
+        <s-text key={i}>Component {i + 1}</s-text>
+      ))}
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/product-configuration/examples/load-variant-bundle-config.jsx

@@ -0,0 +1,54 @@
+import {render} from 'preact';
+import {useState, useEffect} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [components, setComponents] = useState([]);
+  const [variantInfo, setVariantInfo] = useState(null);
+
+  useEffect(() => {
+    const loadConfig = async () => {
+      const variantId = data.selected[0]?.id;
+
+      const {data: variantData} = await shopify.query(
+        `query GetVariantBundleComponents($id: ID!) {
+          productVariant(id: $id) {
+            id
+            displayName
+            sku
+            metafield(namespace: "bundle", key: "variant_components") {
+              value
+            }
+          }
+        }`,
+        {variables: {id: variantId}},
+      );
+
+      setVariantInfo(variantData.productVariant);
+      
+      const comps = variantData.productVariant.metafield
+        ? JSON.parse(variantData.productVariant.metafield.value)
+        : [];
+
+      setComponents(comps);
+    };
+
+    loadConfig();
+  }, [data]);
+
+  return (
+    <s-admin-block heading="Variant Bundle">
+      {variantInfo && (
+        <>
+          <s-text>{variantInfo.displayName}</s-text>
+          <s-text>SKU: {variantInfo.sku}</s-text>
+          <s-text>{components.length} variant components configured</s-text>
+        </>
+      )}
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/product-configuration/examples/navigate-to-component.jsx

@@ -0,0 +1,27 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const [created, setCreated] = useState(null);
+
+  const handleCreate = async () => {
+    const activity = await shopify.intents.invoke('create:shopify/Product');
+    const response = await activity.complete;
+
+    if (response.code === 'ok') {
+      const newProductId = response.data?.product?.id;
+      setCreated(newProductId);
+    }
+  };
+
+  return (
+    <s-admin-block heading="Add Component">
+      <s-button onClick={handleCreate}>Create New Component Product</s-button>
+      {created && <s-text>Component created: {created}</s-text>}
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/product-configuration/examples/select-bundle-components.jsx

@@ -0,0 +1,50 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [selected, setSelected] = useState([]);
+
+  const parentProductId = data.selected[0]?.id;
+
+  const handleSelectComponents = async () => {
+    const componentProducts = await shopify.resourcePicker({
+      type: 'product',
+      multiple: 5,
+      action: 'select',
+      filter: {
+        draft: false,
+        archived: false,
+      },
+    });
+
+    if (componentProducts) {
+      setSelected(componentProducts);
+      
+      await fetch('/api/bundles/configure', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({
+          bundleProductId: parentProductId,
+          components: componentProducts.map((p) => ({
+            productId: p.id,
+            quantity: 1,
+          })),
+        }),
+      });
+    }
+  };
+
+  return (
+    <s-admin-block heading="Bundle Configuration">
+      <s-button onClick={handleSelectComponents}>Select Components</s-button>
+      {selected.length > 0 && (
+        <s-text>{selected.length} components selected</s-text>
+      )}
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/product-configuration/examples/select-variant-components.jsx

@@ -0,0 +1,50 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [selected, setSelected] = useState([]);
+
+  const parentVariantId = data.selected[0]?.id;
+
+  const handleSelectComponents = async () => {
+    const componentVariants = await shopify.resourcePicker({
+      type: 'variant',
+      multiple: 5,
+      action: 'select',
+      filter: {
+        draft: false,
+        archived: false,
+      },
+    });
+
+    if (componentVariants) {
+      setSelected(componentVariants);
+      
+      await fetch('/api/bundles/configure-variant', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({
+          bundleVariantId: parentVariantId,
+          componentVariants: componentVariants.map((v) => ({
+            variantId: v.id,
+            quantity: 1,
+          })),
+        }),
+      });
+    }
+  };
+
+  return (
+    <s-admin-block heading="Variant Bundle Configuration">
+      <s-button onClick={handleSelectComponents}>Select Variant Components</s-button>
+      {selected.length > 0 && (
+        <s-text>{selected.length} variant components selected</s-text>
+      )}
+    </s-admin-block>
+  );
+}

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

@@ -2,51 +2,81 @@ import type {BlockExtensionApi} from '../block/block';
 import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
 import type {Data} from '../shared';
 
-/* @deprecated */
+/**
+ * A product configuration.
+ * @deprecated
+ */
 interface Product {
+  /** The product's unique global identifier (GID). */
   id: string;
+  /** The product's display name shown to merchants and customers. */
   title: string;
+  /** The URL-friendly unique identifier used in product URLs (for example, `'blue-t-shirt'`). */
   handle: string;
+  /** The publication status indicating whether the product is active (published), archived (discontinued), or draft (unpublished). */
   status: 'ACTIVE' | 'ARCHIVED' | 'DRAFT';
+  /** The total number of variants this product has. */
   totalVariants: number;
+  /** The total available inventory summed across all variants and locations. */
   totalInventory: number;
+  /** Whether the product has only the default variant with no custom options. When `true`, the product has no size, color, or other option variations. */
   hasOnlyDefaultVariant: boolean;
+  /** The URL to view this product on the online store. Use this to create "View in store" links. */
   onlineStoreUrl?: string;
+  /** Product options that define how variants differ (for example, Size, Color, Material). Each option has an ID, name, position, and array of possible values. */
   options: {
     id: string;
     name: string;
     position: number;
     values: string[];
   }[];
+  /** The product category or type used for organization (for example, "T-Shirt", "Shoes"). */
   productType: string;
+  /** The standardized product category taxonomy. Use this for product classification in search and organization. */
   productCategory?: string;
+  /** An array of component products that make up this bundle. Each component represents a product included in the bundle configuration. */
   productComponents: ProductComponent[];
 }
 
-/* @deprecated */
+/**
+ * A component product that is part of a bundle. Represents an individual product included in a bundle configuration.
+ * @deprecated
+ */
 export interface ProductComponent {
+  /** The component product's unique global identifier (GID). */
   id: string;
+  /** The product's display name. Use this to show which product is included in the bundle. */
   title: string;
+  /** The featured image displayed for this component product with ID, URL, and alt text properties. Use this for showing component previews in bundle configuration interfaces. */
   featuredImage?: {
     id?: string | null;
     url?: string | null;
     altText?: string | null;
   } | null;
+  /** The total number of variants this component product has. Use this to determine if variant selection is needed for this component. */
   totalVariants: number;
+  /** The admin URL for this component product. Use this to create links to the product's details page in the admin. */
   productUrl: string;
+  /** The count of variants from this product that are used as bundle components. Use this to understand how many variants are configured in bundles. */
   componentVariantsCount: number;
+  /** The count of variants from this product that aren't used in any bundles. Use this to identify available variants for adding to bundle configurations. */
   nonComponentVariantsCount: number;
 }
 
+/**
+ * The `ProductDetailsConfigurationApi` object provides methods for configuring product bundles and relationships. Access the following properties on the `ProductDetailsConfigurationApi` object to build product configuration interfaces.
+ */
 export interface ProductDetailsConfigurationApi<
   ExtensionTarget extends AnyExtensionTarget,
 > extends BlockExtensionApi<ExtensionTarget> {
+  /** Product configuration data including the current product, selected items, and app URLs. Use this to access the product being configured and build your configuration interface. */
   data: Data & {
-    /*
-      @deprecated 
-      The product currently being viewed in the admin.
-    */
+    /**
+     * The product currently being viewed in the admin.
+     * @deprecated
+     */
     product: Product;
+    /** URLs for launching and navigating to your app, including the launch URL and base application URL. Use these to create links or redirect merchants to your app. */
     app: {
       launchUrl: string;
       applicationUrl: string;

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

@@ -2,52 +2,82 @@ import type {BlockExtensionApi} from '../block/block';
 import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
 import type {Data} from '../shared';
 
-/* @deprecated */
+/**
+ * A product variant configuration.
+ * @deprecated
+ */
 interface ProductVariant {
+  /** The variant's unique global identifier (GID). */
   id: string;
+  /** The Stock Keeping Unit (SKU) identifier for inventory tracking. */
   sku: string;
+  /** The barcode, UPC, or ISBN number for the variant. */
   barcode: string;
+  /** The display name showing only the variant's option values (for example, "Medium / Blue"). */
   title: string;
+  /** A human-readable display name that combines the product title with the variant's option values (for example, "T-Shirt - Medium / Blue"). */
   displayName: string;
+  /** The current selling price for this variant. */
   price: string;
+  /** The original price before any discounts or markdowns. */
   compareAtPrice: string;
+  /** Whether this variant is subject to taxes. When `true`, applicable taxes are calculated at checkout. */
   taxable: boolean;
+  /** The harmonized system (HS) tax code for international shipping and customs. */
   taxCode: string;
+  /** The physical weight of the variant as a number. */
   weight: number;
+  /** The option values that define this specific variant with name and value pairs (for example, Size: Large, Color: Blue). */
   selectedOptions: {
     name: string;
     value: string;
   }[];
+  /** An array of component variants that make up this bundle variant. Each component represents a product variant included in the bundle. */
   productVariantComponents: ProductVariantComponent[];
 }
 
-/* @deprecated */
+/**
+ * A component variant that is part of a product bundle. Represents an individual product variant included in a bundle configuration.
+ * @deprecated
+ */
 export interface ProductVariantComponent {
+  /** The component variant's unique global identifier (GID). */
   id: string;
+  /** A human-readable display name that combines the product title with the variant's option values (for example, "T-Shirt - Medium / Blue"). */
   displayName: string;
+  /** The display name showing only the variant's option values (for example, "Medium / Blue"). */
   title: string;
+  /** The Stock Keeping Unit (SKU) identifier for this component variant. */
   sku?: string;
+  /** The image displayed for this component variant with ID, URL, and alt text properties. Use this for showing component previews in bundle configuration interfaces. */
   image?: {
     id?: string | null;
     url?: string | null;
     altText?: string | null;
   } | null;
+  /** The admin URL for this product variant. Use this to create links to the variant's details page in the admin. */
   productVariantUrl: string;
+  /** The option values that define this specific component variant with name and value pairs (for example, Size: Large, Color: Blue). */
   selectedOptions: {
     name: string;
     value: string;
   }[];
 }
 
+/**
+ * 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.
+ */
 export interface ProductVariantDetailsConfigurationApi<
   ExtensionTarget extends AnyExtensionTarget,
 > extends BlockExtensionApi<ExtensionTarget> {
+  /** Product variant configuration data including the current variant, selected items, and app URLs. Use this to access the variant being configured and build your configuration interface. */
   data: Data & {
-    /*
-      @deprecated
-      The product variant currently being viewed in the admin.
-    */
+    /**
+     * The product variant currently being viewed in the admin.
+     * @deprecated
+     */
     variant: ProductVariant;
+    /** URLs for launching and navigating to your app, including the launch URL and base application URL. Use these to create links or redirect merchants to your app. */
     app: {
       launchUrl: string;
       applicationUrl: string;

package/src/surfaces/admin/api/purchase-options-card/examples/manage-subscription.jsx

@@ -0,0 +1,45 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [updated, setUpdated] = useState(false);
+
+  const {id: productId, sellingPlanId} = data.selected[0];
+
+  const handleUpdate = async () => {
+    if (!sellingPlanId) {
+      console.error('No selling plan selected');
+      shopify.close();
+      return;
+    }
+
+    const response = await fetch('/api/subscriptions/update', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({
+        productId,
+        sellingPlanId,
+        action: 'modify',
+      }),
+    });
+
+    if (response.ok) {
+      setUpdated(true);
+      setTimeout(() => shopify.close(), 1500);
+    }
+  };
+
+  return (
+    <s-admin-action title="Manage Subscription">
+      <s-text>Product: {productId}</s-text>
+      <s-text>Selling Plan: {sellingPlanId}</s-text>
+      <s-button onClick={handleUpdate}>Update Subscription</s-button>
+      {updated && <s-banner status="success">Subscription updated!</s-banner>}
+    </s-admin-action>
+  );
+}

package/src/surfaces/admin/api/purchase-options-card/examples/remove-from-plan.jsx

@@ -0,0 +1,44 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [confirming, setConfirming] = useState(false);
+  const [removed, setRemoved] = useState(false);
+
+  const {id: productId, sellingPlanId} = data.selected[0];
+
+  const handleRemove = async () => {
+    setConfirming(false);
+    
+    await fetch('/api/selling-plans/remove-product', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({productId, sellingPlanId}),
+    });
+
+    setRemoved(true);
+    setTimeout(() => shopify.close(), 1500);
+  };
+
+  return (
+    <s-admin-action title="Remove from Selling Plan">
+      {!confirming ? (
+        <s-button onClick={() => setConfirming(true)}>
+          Remove Product
+        </s-button>
+      ) : (
+        <>
+          <s-text>Are you sure you want to remove this product?</s-text>
+          <s-button onClick={handleRemove}>Confirm Remove</s-button>
+          <s-button onClick={() => setConfirming(false)}>Cancel</s-button>
+        </>
+      )}
+      {removed && <s-banner status="success">Product removed from plan</s-banner>}
+    </s-admin-action>
+  );
+}