Shopify Admin UI Extensions

https://shopify.dev/docs/api/admin-extensions/latest
Admin
Shopify Admin UI Extensions enable developers to build custom integrations that extend the Shopify...
Tokens:206,802
Snippets:3,170
Trust Score:9.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Implement a Drop Zone with File Validation

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/drop-zone

This example demonstrates how to configure the drop zone and handle file uploads with size validation and state management.

```html
<s-drop-zone
id="upload"
label="Product images"
accept="image/*"
multiple
></s-drop-zone>
  

<script>
const dropzone = document.getElementById('upload');
  

dropzone.addEventListener('change', async (e) => {
const files = e.currentTarget.files;
  

// Validate size (5MB max per file)
const maxSize = 5 * 1024 * 1024;
if (files.some(f => f.size > maxSize)) {
dropzone.error = 'Files must be under 5MB';
return;
}
dropzone.error = '';
  

// Disable during upload
dropzone.disabled = true;
  

const formData = new FormData();
files.forEach(f => formData.append('images[]', f));
  

try {
await fetch('/api/upload', { method: 'POST', body: formData });
dropzone.value = ''; // Clear for next upload
// Show success feedback
} catch (error) {
dropzone.error = 'Upload failed. Please try again.';
} finally {
dropzone.disabled = false;
}

```

--------------------------------

### Implementing a Box Layout

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/layout-and-structure/box

A layout example demonstrating the use of s-box to group inventory status and product information sections.

```html
<s-stack gap="base">
<!-- Inventory status section -->
<s-box
padding="base"
background="base"
borderRadius="base"
borderWidth="base"
borderColor="base"
>
<s-stack gap="base">
<s-box padding="small-100" background="subdued" borderRadius="small">
<s-paragraph>In stock: 45 units</s-paragraph>
</s-box>
<s-box padding="small-100" background="subdued" borderRadius="small">
<s-paragraph>Low stock alert: 5 units</s-paragraph>
</s-box>
</s-stack>
</s-box>
  

<!-- Product information section -->
<s-box
padding="base"
background="base"
borderRadius="base"
borderWidth="base"
borderColor="base"
>
<s-stack gap="base">
<s-heading>Product sales</s-heading>
<s-paragraph color="subdued">No recent sales of this product</s-paragraph>
<s-link>View details</s-link>
</s-stack>
</s-box>
</s-stack>
```

--------------------------------

### Create a discount form with select and checkbox

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/form

A form example incorporating text inputs, select dropdowns, and checkboxes for complex data entry.

```html
<s-form>
<s-stack direction="block" gap="base">
<s-text-field label="Discount code" name="code" required></s-text-field>
<s-select label="Discount type" name="type">
<s-option value="percentage">Percentage</s-option>
<s-option value="fixed">Fixed amount</s-option>
<s-option value="shipping">Free shipping</s-option>
</s-select>
<s-checkbox label="Apply to all products" name="allProducts" checked></s-checkbox>
<s-button variant="primary" type="submit">Create discount</s-button>
</s-stack>
</s-form>
```

--------------------------------

### Select Bundle Components with Resource Picker

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/product-details-configuration-api

Open the product resource picker to select up to five components for a bundle. This example filters out draft and archived products, saves the bundle configuration to your backend, and tracks the selection count.

```jsx
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>
  );
}
```

--------------------------------

### Create Article Intent

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api

Launch the article creation workflow from a button click. This example uses shopify.intents.invoke() to open the article editor, awaits the workflow completion, and displays success or cancellation feedback based on the response code.

```jsx
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [result, setResult] = useState(null);
  const [creating, setCreating] = useState(false);

  const handleCreate = async () => {
    setCreating(true);
    
    const activity = await shopify.intents.invoke('create:shopify/Article');
    const response = await activity.complete;

    setResult(response);
    setCreating(false);
  };

  return (
    <s-admin-block heading="Create Article">
      <s-button onClick={handleCreate} disabled={creating}>
        {creating ? 'Creating...' : 'Launch Article Creator'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">Article created successfully!</s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Creation cancelled</s-text>
      )}
    </s-admin-block>
  );
}
```

--------------------------------

### Create Bundle with Resource Picker

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/action-extension-api

Launch the resource picker to select component products for a bundle, then save the bundle configuration to your backend. This example demonstrates opening a resource picker from within an action modal and handling the selection result.

```jsx
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(null);

  const currentProductId = data.selected[0]?.id;

  const handleSelectProducts = async () => {
    const selectedProducts = await shopify.resourcePicker({
      type: 'product',
      multiple: 5,
      action: 'select',
    });

    if (selectedProducts) {
      setSelected(selectedProducts);

      await fetch('/api/create-bundle', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          mainProduct: currentProductId,
          components: selectedProducts.map((p) => p.id),
        }),
      });

      shopify.close();
    }
  };

  return (
    <s-admin-action title="Create Bundle">
      <s-text>Main product: {currentProductId}</s-text>
      <s-button onClick={handleSelectProducts}>
        Select Component Products
      </s-button>
      {selected && <s-text>Selected {selected.length} products</s-text>}
    </s-admin-action>
  );
}
```

--------------------------------

### Create Catalog Intent

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api

Launch the catalog creation workflow to set up B2B customer groups or market-specific product collections. This example invokes the create intent, manages loading state, and displays success or cancellation feedback.

```jsx
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleAction = async () => {
    setLoading(true);
    
    const activity = await shopify.intents.invoke('create:shopify/Catalog');
    const response = await activity.complete;

    setResult(response);
    setLoading(false);
  };

  return (
    <s-admin-block heading="Create Catalog">
      <s-button onClick={handleAction} disabled={loading}>
        {loading ? 'Creating...' : 'Launch Catalog Creator'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">Catalog created successfully!</s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Creation cancelled</s-text>
      )}
    </s-admin-block>
  );
}
```

--------------------------------

### Launch Product Creation Workflow

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/product-details-configuration-api

Launch the product creation workflow using intents and capture the new product ID. This example invokes the create intent, waits for completion, and displays the created product ID from the response data.

```jsx
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>
  );
}
```

--------------------------------

### Basic Choice List Implementation

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/choice-list

A standard choice list example with a disabled state and pre-selected option.

```html
<s-choice-list label="Account type" name="account-type" disabled>
<s-choice value="basic" selected>Basic</s-choice>
<s-choice value="advanced">Advanced</s-choice>
<s-choice value="enterprise">Enterprise</s-choice>
</s-choice-list>
```

--------------------------------

### Bulk Process Products Action

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/action-extension-api

Send selected product IDs to your backend for bulk processing. This example shows how to map selected items, make an authenticated API call, and close the modal when the operation completes.

```jsx
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const {data} = shopify;

  const handleProcess = async () => {
    const productIds = data.selected.map((item) => item.id);

    const response = await fetch('/api/bulk-process', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({productIds}),
    });

    if (response.ok) {
      console.log('Products processed successfully');
      shopify.close();
    } else {
      console.error('Failed to process products');
    }
  };

  return (
    <s-admin-action title="Bulk Process">
      <s-text>Processing {data.selected.length} products</s-text>
      <s-button onClick={handleProcess}>Process Products</s-button>
    </s-admin-action>
  );
}
```

--------------------------------

### Edit Article Intent

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api

Open the article editor for a selected blog post. This example retrieves the article GID from extension context, passes it to the edit intent, and handles both successful updates and cancellations.

```jsx
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const {data} = shopify;
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const resourceId = data.selected[0]?.id || 'gid://shopify/Article/123456789';

  const handleAction = async () => {
    setLoading(true);
    
    const activity = await shopify.intents.invoke('edit:shopify/Article', {
      value: resourceId,
    });
    
    const response = await activity.complete;
    setResult(response);
    setLoading(false);
  };

  return (
    <s-admin-block heading="Edit Article">
      <s-text>Editing: {resourceId}</s-text>
      <s-button onClick={handleAction} disabled={loading}>
        {loading ? 'Opening...' : 'Edit Article'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">Article updated!</s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Edit cancelled</s-text>
      )}
    </s-admin-block>
  );
}
```

--------------------------------

### get(key)

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/discount-function-settings-api

Gets the value of a key in the storage.

```APIDOC
## get(key)

### Description
Gets the value of a key in the storage. The value is automatically deserialized from JSON to its original type.

### Signature
`<StorageTypes, Keys extends keyof StorageTypes>(key: Keys) => Promise<StorageTypes[Keys]>`
```

--------------------------------

### Storage get operation

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/print-action-extension-api

Gets the value of a key in the storage.

```typescript
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys) => Promise<StorageTypes[Keys]>
```

--------------------------------

### entries()

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/discount-function-settings-api

Gets all the keys and values in the storage.

```APIDOC
## entries()

### Description
Gets all the keys and values in the storage. The returned iterator provides entries as [key, value] tuples.

### Signature
`<StorageTypes, Keys extends keyof StorageTypes>() => Promise<IterableIterator<[Keys, StorageTypes[Keys]]>>`
```

--------------------------------

### getMany(keys)

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/discount-function-settings-api

Gets the values of multiple keys in the storage at once.

```APIDOC
## getMany(keys)

### Description
Gets the values of multiple keys in the storage at once. The returned array is in the same order as the provided keys.

### Signature
`<StorageTypes, Keys extends keyof StorageTypes>(keys: Keys[]) => Promise<StorageTypes[Keys][]>`
```

--------------------------------

### Storage entries operation

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/print-action-extension-api

Gets all the keys and values in the storage.

```typescript
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>() => Promise<IterableIterator<[Keys, StorageTypes[Keys]]>>
```

--------------------------------

### Storage getMany operation

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/print-action-extension-api

Gets the values of multiple keys in the storage at once.

```typescript
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(keys: Keys[]) => Promise<StorageTypes[Keys][]>
```

--------------------------------

### Get intent launch URL

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/discount-function-settings-api

Retrieves the URL that initiated the current intent workflow.

```typescript
string | URL
```

--------------------------------

### Collect text with a placeholder

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/text-area

Uses a placeholder to guide user input and disables browser autocomplete.

```html
<s-text-area
label="Product description"
placeholder="Enter a detailed description..."
autocomplete="off"
></s-text-area>
```

--------------------------------

### Pre-populate Resource Picker

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/resource-picker-api

Opens the picker with existing products pre-selected by passing GIDs to the selectionIds option.

```jsx
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 result = await shopify.resourcePicker({
      type: 'product',
      selectionIds: [
        'gid://shopify/Product/123',
        'gid://shopify/Product/456',
      ],
    });
    setSelected(result);
  };

  return (
    <s-admin-block heading="Resource Picker">
      <s-button onClick={handlePick}>Select Products</s-button>
      {selected && <s-text>{selected.length} products selected</s-text>}
    </s-admin-block>
  );
}
```

--------------------------------

### Settings menu with sections

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/actions/menu

A settings-style menu implementation with multiple sections and a standalone sign-out action.

```html
<s-button icon="settings" commandFor="admin-settings">Settings</s-button>
  

<s-menu id="admin-settings" accessibilityLabel="Settings menu">
<s-section heading="Account">
<s-button icon="profile">Profile settings</s-button>
<s-button icon="lock">Security</s-button>
<s-button>Billing information</s-button>
</s-section>
<s-section heading="Store">
<s-button icon="store">Store settings</s-button>
<s-button>Payment providers</s-button>
<s-button icon="delivery">Shipping rates</s-button>
</s-section>
<s-button href="javascript:void(0)" icon="person-exit">Sign out</s-button>
</s-menu>
```

--------------------------------

### Limit input length with a character cap

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/text-area

Enforces a maximum character length and provides help text to guide the user.

```html
<s-text-area
label="Meta description"
maxLength="160"
details="Appears in search results. Keep under 160 characters for best visibility."
placeholder="Write a compelling description that will appear in Google search results..."
rows="3"
autocomplete="off"
></s-text-area>
```

--------------------------------

### Create a numbered step list

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/layout-and-structure/ordered-list

Use s-ordered-list with s-list-item elements to define a basic sequence of instructions.

```html
<s-ordered-list>
<s-list-item>Add products to your catalog</s-list-item>
<s-list-item>Set up payment methods</s-list-item>
<s-list-item>Configure shipping zones</s-list-item>
</s-ordered-list>
```

--------------------------------

### Set up tiered discount rules

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/function-settings

Organizes settings into repeating groups using sections to define multi-level configurations.

```html
<s-function-settings>
<s-stack direction="block" gap="base">
<s-section heading="Tier 1">
<s-stack direction="inline" gap="base">
<s-number-field label="Minimum quantity" name="tier1Qty" value="5" min="1" step="1"></s-number-field>
<s-number-field label="Discount" name="tier1Discount" value="10" min="0" max="100" step="1" suffix="%"></s-number-field>
</s-stack>
</s-section>
<s-section heading="Tier 2">
<s-stack direction="inline" gap="base">
<s-number-field label="Minimum quantity" name="tier2Qty" value="10" min="1" step="1"></s-number-field>
<s-number-field label="Discount" name="tier2Discount" value="20" min="0" max="100" step="1" suffix="%"></s-number-field>
</s-stack>
</s-section>
</s-stack>
</s-function-settings>
```

--------------------------------

### Customer management menu

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/actions/menu

A menu example featuring grouped customer management and account actions with a critical delete button.

```html
<s-button commandFor="customer-menu">Edit customer</s-button>
  

<s-menu id="customer-menu" accessibilityLabel="Customer actions">
<s-section heading="Customer management">
<s-button icon="edit">Edit customer</s-button>
<s-button icon="email">Send email</s-button>
<s-button icon="order">View orders</s-button>
</s-section>
<s-section heading="Account actions">
<s-button icon="reset">Reset password</s-button>
<s-button icon="lock">Disable account</s-button>
</s-section>
<s-button tone="critical" icon="delete">Delete customer</s-button>
</s-menu>
```

--------------------------------

### DiscountsApi Interface

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/order-routing-rule-api

Reactive access methods for discount configuration.

```text
ReadonlySignalLike<DiscountClass[]>
```

```text
ReadonlySignalLike<DiscountMethod>
```

```text
UpdateSignalFunction<DiscountClass[]>
```

--------------------------------

### Render product configuration

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/discount-function-settings-api

Renders product configuration settings for bundles and customizable products.

```typescript
RenderExtension<
    ProductDetailsConfigurationApi<'admin.product-details.configuration.render'>,
    BlockExtensionComponents
  >
```

--------------------------------

### Implement a date range selector

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/date-field

Pairs two date fields side-by-side to allow users to select a start and end date range.

```html
<s-stack gap="base">
<s-heading>Sales report period</s-heading>
  

<s-stack direction="inline" gap="base">
<s-date-field
label="Start date"
name="startDate"
id="report-start"
></s-date-field>
  

<s-date-field
label="End date"
name="endDate"
id="report-end"
></s-date-field>
</s-stack>
  

<s-button variant="primary">Generate report</s-button>
</s-stack>
```

--------------------------------

### Implement basic file upload zone

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/drop-zone

A standard drop zone configuration with event logging for input, change, and rejection events.

```html
<s-drop-zone
label="Upload"
accessibilityLabel="Upload image of type jpg, png, or gif"
accept=".jpg,.png,.gif"
multiple
onInput="console.log('onInput', event.currentTarget?.value)"
onChange="console.log('onChange', event.currentTarget?.value)"
onDropRejected="console.log('onDropRejected', event.currentTarget?.value)"
></s-drop-zone>
```

--------------------------------

### Intents.invoke

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/print-action-extension-api

Launches a native Shopify admin workflow for creating or editing resources.

```APIDOC
## invoke

### Description
Launches an intent workflow for creating or editing Shopify resources. Returns a handle that resolves when the merchant completes, cancels, or encounters an error in the workflow.

### Signature
IntentInvokeApi
```

--------------------------------

### PrintActionExtensionComponents

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/print-action-extension-api

The components available for building print action extensions. Includes all standard components plus the admin print action component required for print action setup.

```APIDOC
## PrintActionExtensionComponents

### Description
The components available for building print action extensions. Includes all standard components plus the admin print action component required for print action setup.

### Type
StandardComponents | 'AdminPrintAction'
```

--------------------------------

### Create a responsive stack with container queries

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/layout-and-structure/stack

Uses container queries to dynamically adjust the stack direction and gap based on the container's width.

```html
<s-query-container>
<s-stack
direction="@container (inline-size > 500px) inline, block"
gap="@container (inline-size > 500px) base, small-300"
>
<s-box
padding="large-100"
borderColor="base"
borderWidth="small"
borderRadius="large-100"
>
Content 1
</s-box>
<s-box
padding="large-100"
borderColor="base"
borderWidth="small"
borderRadius="large-100"
>
Content 2
</s-box>
</s-stack>
</s-query-container>
```

--------------------------------

### Query Bundle Metafields

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/product-details-configuration-api

Query a product's bundle metafield and parse the JSON components array. This example fetches bundle data in useEffect, parses the stored configuration, and displays the component count.

```jsx
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>
  );
}
```

--------------------------------

### Invoke Create Discount Intent

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api

Launches the discount creation form. Manages loading state and displays feedback upon completion of the creation intent.

```jsx
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleAction = async () => {
    setLoading(true);
    
    const activity = await shopify.intents.invoke('create:shopify/Discount');
    const response = await activity.complete;

    setResult(response);
    setLoading(false);
  };

  return (
    <s-admin-block heading="Create Discount">
      <s-button onClick={handleAction} disabled={loading}>
        {loading ? 'Creating...' : 'Launch Discount Creator'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">Discount created successfully!</s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Creation cancelled</s-text>
      )}
    </s-admin-block>
  );
}
```

--------------------------------

### Fulfill Order with Error Handling

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/action-extension-api

Fulfill an order through your app backend with proper error handling. This example uses try-catch blocks to catch errors and displays error messages when your backend fulfillment service fails.

```jsx
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const {data} = shopify;
  const [error, setError] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleFulfill = async () => {
    setLoading(true);
    setError(null);
    
    try {
      const orderId = data.selected[0]?.id;
      
      const response = await fetch(`/api/orders/${orderId}/fulfill`, {
        method: 'POST',
      });
      
      const result = await response.json();
      
      if (!response.ok) {
        throw new Error(result.error || 'Fulfillment failed');
      }
      
      console.log('Order fulfilled:', result);
      shopify.close();
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <s-admin-action title="Fulfill Order">
      {error && <s-banner tone="critical">{error}</s-banner>}
      <s-button onClick={handleFulfill} disabled={loading}>
        {loading ? 'Fulfilling...' : 'Fulfill Order'}
      </s-button>
    </s-admin-action>
  );
}
```

--------------------------------

### Create Menu with Intents API

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api

Launches the menu creation workflow for storefront navigation using Preact.

```jsx
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleAction = async () => {
    setLoading(true);
    
    const activity = await shopify.intents.invoke('create:shopify/Menu');
    const response = await activity.complete;

    setResult(response);
    setLoading(false);
  };

  return (
    <s-admin-block heading="Create Menu">
      <s-button onClick={handleAction} disabled={loading}>
        {loading ? 'Creating...' : 'Launch Menu Creator'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">Menu created successfully!</s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Creation cancelled</s-text>
      )}
    </s-admin-block>
  );
}
```

--------------------------------

### Open Product Resource Picker

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/resource-picker-api

Invokes the resource picker to select products from the store catalog. Returns an array of product objects including GIDs, titles, and handles.

```jsx
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 result = await shopify.resourcePicker({type: 'product'});
    setSelected(result);
  };

  return (
    <s-admin-block heading="Resource Picker">
      <s-button onClick={handlePick}>Select Products</s-button>
      {selected && <s-text>{selected.length} products selected</s-text>}
    </s-admin-block>
  );
}
```

--------------------------------

### Basic Link Usage

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/actions/link

Demonstrates a standard inline link using the href property.

```html
<s-link href="#beep">fulfilling orders</s-link>
```

--------------------------------

### Implement s-chip with truncation and icons

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/typography-and-content/chip

Demonstrates using s-chip with text truncation inside a constrained box and adding icons for visual reinforcement.

```html
<s-box maxInlineSize="200px">
<s-stack gap="base">
<s-chip color="base" accessibilityLabel="Long product name">
This is a very long product name that will be truncated with ellipsis when
it exceeds the container width
</s-chip>
<s-chip color="strong" accessibilityLabel="Long category name">
<s-icon slot="graphic" type="catalog-product" size="small"></s-icon>
Electronics and computer accessories category with extended description
</s-chip>
</s-stack>
</s-box>
```

--------------------------------

### invoke(query, options?)

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api

Launches a Shopify admin workflow for creating or editing resources. The method returns a promise that resolves to an activity handle.

```APIDOC
## invoke(query, options?)

### Description
Launches a Shopify admin workflow for creating or editing resources. The method returns a promise that resolves to an activity handle which can be awaited to retrieve the workflow result.

### Parameters
- **query** (string | object) - Required - Either a string query in the format `${action}:${type},${value}` or an object containing `action`, `type`, `value`, and `data`.
- **options** (IntentQueryOptions) - Optional - Additional configuration for the invoke method.

### IntentQueryOptions
- **value** (string) - Optional - The resource identifier for edit operations (e.g., 'gid://shopify/Product/123'). Required when editing existing resources.
- **data** (object) - Optional - Additional context required by specific resource types (e.g., discount types, product IDs for variants, or metaobject definition types).
```

--------------------------------

### Select related products with resource picker

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/block-extension-api

Opens the resource picker to select products and saves the associations to a backend, tracking the count of selected items.

```jsx
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const {data} = shopify;
  const [relatedCount, setRelatedCount] = useState(0);

  const currentProductId = data.selected[0]?.id;

  const handleSelectRelated = async () => {
    const selectedProducts = await shopify.resourcePicker({
      type: 'product',
      multiple: true,
      filter: {
        hidden: false,
        draft: false,
      },
    });

    if (selectedProducts) {
      await fetch('/api/product-recommendations', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          productId: currentProductId,
          relatedProducts: selectedProducts.map((p) => p.id),
        }),
      });
      
      setRelatedCount(selectedProducts.length);
    }
  };

  return (
    <s-admin-block heading="Product Recommendations">
      <s-button onClick={handleSelectRelated}>Select Related Products</s-button>
      {relatedCount > 0 && (
        <s-text>Added {relatedCount} related products</s-text>
      )}
    </s-admin-block>
  );
}
```

--------------------------------

### Fetch product information with GraphQL

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/block-extension-api

Uses useEffect to query the GraphQL Admin API on load and displays a loading spinner while fetching product details.

```jsx
import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const {data} = shopify;
  const [product, setProduct] = useState(null);

  useEffect(() => {
    const fetchProduct = async () => {
      const productId = data.selected[0]?.id;

      const {data: productData} = await shopify.query(
        `query GetProduct($id: ID!) {
          product(id: $id) {
            title
            totalInventory
            status
          }
        }`,
        {variables: {id: productId}},
      );

      setProduct(productData.product);
    };

    fetchProduct();
  }, [data]);

  return (
    <s-admin-block heading="Product Information">
      {product ? (
        <>
          <s-text>Title: {product.title}</s-text>
          <s-text>Inventory: {product.totalInventory}</s-text>
          <s-text>Status: {product.status}</s-text>
        </>
      ) : (
        <s-spinner />
      )}
    </s-admin-block>
  );
}
```

--------------------------------

### Load and display discount metafields

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/discount-function-settings-api

Reduces existing metafields into a settings object on mount and applies default values if specific keys are missing.

```jsx
import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const {data} = shopify;
  const [settings, setSettings] = useState({});

  useEffect(() => {
    const initializeSettings = async () => {
      const existingSettings = data.metafields.reduce((acc, field) => {
        acc[field.key] = field.value;
        return acc;
      }, {});

      setSettings(existingSettings);

      if (!existingSettings.eligible_tags) {
        await shopify.applyMetafieldChange({
          type: 'updateMetafield',
          namespace: 'discount-config',
          key: 'eligible_tags',
          value: JSON.stringify(['vip', 'wholesale']),
          valueType: 'json',
        });
      }
    };

    initializeSettings();
  }, [data]);

  return (
    <s-function-settings>
      <s-text>Current settings:</s-text>
      {Object.entries(settings).map(([key, value]) => (
        <s-text key={key}>
          {key}: {String(value)}
        </s-text>
      ))}
    </s-function-settings>
  );
}
```

--------------------------------

### Create Customer via Intents API

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api

Launches the customer creation form and handles the completion result.

```jsx
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleAction = async () => {
    setLoading(true);
    
    const activity = await shopify.intents.invoke('create:shopify/Customer');
    const response = await activity.complete;

    setResult(response);
    setLoading(false);
  };

  return (
    <s-admin-block heading="Create Customer">
      <s-button onClick={handleAction} disabled={loading}>
        {loading ? 'Creating...' : 'Launch Customer Creator'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">Customer created successfully!</s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Creation cancelled</s-text>
      )}
    </s-admin-block>
  );
}
```

--------------------------------

### Basic Select Implementation

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/select

A standard dropdown menu with an icon and multiple selectable options.

```html
<s-select label="Filter orders by" icon="sort">
<s-option value="date">Order date</s-option>
<s-option value="status">Fulfillment status</s-option>
<s-option value="total">Order total</s-option>
<s-option value="customer">Customer name</s-option>
</s-select>
```

--------------------------------

### admin.product-details.configuration.render

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/product-details-configuration-api

A configuration target that renders product configuration settings for product bundles and customizable products on the product details page. Use this to define bundle component selections, customization options, or product configuration rules.

```APIDOC
## admin.product-details.configuration.render

### Description
A configuration target that renders product configuration settings for product bundles and customizable products on the product details page. Use this to define bundle component selections, customization options, or product configuration rules.

### Signature
RenderExtension<ProductDetailsConfigurationApi<'admin.product-details.configuration.render'>, BlockExtensionComponents>
```

--------------------------------

### Create Market with Intents API

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api

Launches the market creation workflow for international selling using Preact and managing loading states.

```jsx
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleAction = async () => {
    setLoading(true);
    
    const activity = await shopify.intents.invoke('create:shopify/Market');
    const response = await activity.complete;

    setResult(response);
    setLoading(false);
  };

  return (
    <s-admin-block heading="Create Market">
      <s-button onClick={handleAction} disabled={loading}>
        {loading ? 'Creating...' : 'Launch Market Creator'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">Market created successfully!</s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Creation cancelled</s-text>
      )}
    </s-admin-block>
  );
}
```

--------------------------------

### Render discount function settings

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/discount-function-settings-api

Builds a configuration interface for merchants to manage discount function parameters.

```typescript
RenderExtension<
    DiscountFunctionSettingsApi<'admin.discount-details.function-settings.render'>,
    FunctionSettingsComponents
  >
```

--------------------------------

### Build a custom picker for email templates

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api

Define column headers, populate items with searchable data fields, add visual status indicators, and handle the selection promise. Use this pattern for app-specific resources like templates, product reviews, or subscription options.

```jsx
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: [
            {content: 'Templates'},
            {content: 'Created by'},
            {content: '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>
  );
}
```

--------------------------------

### Navigation.navigate

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/discount-function-settings-api

Navigates to a specific extension or admin route.

```APIDOC
## navigate(url)

### Description
Navigates to a specific extension or admin route. Currently supports navigating from a block extension to an action extension on the same resource page.

### Parameters
- **url** (string | URL) - Required - The destination URL or path.
```

--------------------------------

### admin.product-variant-details.configuration.render

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/core-apis/print-action-extension-api

Renders product variant configuration settings for product bundles and customizable products on the product variant details page.

```APIDOC
## admin.product-variant-details.configuration.render

### Description
A configuration target that renders product variant configuration settings for product bundles and customizable products on the product variant details page. Use this to define variant-specific bundle components, customization options, or configuration rules.

### Signature
RenderExtension<ProductVariantDetailsConfigurationApi<'admin.product-variant-details.configuration.render'>, BlockExtensionComponents>
```

--------------------------------

### Create a dropdown menu

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/forms/select

Use s-select with s-option and s-option-group to provide a list of selectable items.

```html
<s-select label="Date range">
<s-option value="1">Today</s-option>
<s-option value="2">Yesterday</s-option>
<s-option value="3">Last 7 days</s-option>
<s-option-group label="Custom ranges">
<s-option value="4">Last 30 days</s-option>
<s-option value="5">Last 90 days</s-option>
</s-option-group>
</s-select>
```

--------------------------------

### shopify.intents.invoke(intent, options)

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api

Invokes a system intent to open a specific editor or settings page. Returns an activity object that provides a promise to track the completion of the intent.

```APIDOC
## shopify.intents.invoke(intent, options)

### Description
Invokes a system intent to open a specific editor or settings page. The method returns an activity object, which contains a `complete` promise that resolves with the result of the user's interaction.

### Parameters
- **intent** (string) - Required - The identifier of the intent to invoke (e.g., 'edit:settings/OrderIdFormat', 'edit:settings/OrderProcessing', 'edit:shopify/ProductVariant').
- **options** (object) - Optional - Configuration object for the intent, such as the `value` (resource ID) for specific resource editing.

### Response
- **activity.complete** (Promise) - Resolves to an object containing a `code` property (e.g., 'ok' for success, 'closed' for cancellation).
```

--------------------------------

### Basic Icon Usage

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/media-and-visuals/icon

A simple implementation of the s-icon component.

```html
<s-icon type="settings" id="settings-icon"></s-icon>
```

--------------------------------

### Create Collection via Intents API

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api

Launches the collection creation workflow and displays feedback upon completion.

```jsx
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [result, setResult] = useState(null);
  const [loading, setLoading] = useState(false);

  const handleAction = async () => {
    setLoading(true);
    
    const activity = await shopify.intents.invoke('create:shopify/Collection');
    const response = await activity.complete;

    setResult(response);
    setLoading(false);
  };

  return (
    <s-admin-block heading="Create Collection">
      <s-button onClick={handleAction} disabled={loading}>
        {loading ? 'Creating...' : 'Launch Collection Creator'}
      </s-button>
      {result?.code === 'ok' && (
        <s-banner tone="success">Collection created successfully!</s-banner>
      )}
      {result?.code === 'closed' && (
        <s-text>Creation cancelled</s-text>
      )}
    </s-admin-block>
  );
}
```

--------------------------------

### Mixed Menu with Links and Disabled Items

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/actions/menu

Demonstrates integrating standard buttons with links, disabled states, and download attributes within a single menu.

```html
<s-button commandFor="mixed-menu">Options</s-button>
  

<s-menu id="mixed-menu" accessibilityLabel="Mixed menu options">
<s-button href="javascript:void(0)" target="_blank">
View product page
</s-button>
<s-button disabled>Unavailable action</s-button>
<s-button download href="javascript:void(0)">Download report</s-button>
</s-menu>
```

--------------------------------

### Basic Button Implementation

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/actions/button

Displays a standard button with a text label.

```html
<s-button>Save</s-button>
```

--------------------------------

### Create a responsive grid with container queries

Source: https://shopify.dev/docs/api/admin-extensions/latest/web-components/layout-and-structure/grid

Use the gridTemplateColumns property with container queries to automatically adjust the column count based on available width.

```html
<s-stack gap="base">
<s-text type="strong">Narrow container (375px)</s-text>
<s-box inlineSize="375px">
<s-query-container>
<s-grid
gridTemplateColumns="@container (inline-size > 400px) 1fr 1fr 1fr, 1fr"
gap="base"
>
<s-grid-item>
<s-box padding="small" background="subdued">
<s-text>Item 1</s-text>
</s-box>
</s-grid-item>
<s-grid-item>
<s-box padding="small" background="subdued">
<s-text>Item 2</s-text>
</s-box>
</s-grid-item>
<s-grid-item>
<s-box padding="small" background="subdued">
<s-text>Item 3</s-text>
</s-box>
</s-grid-item>
</s-grid>
</s-query-container>
</s-box>
  

<s-text type="strong">Wide container (450px)</s-text>
<s-box inlineSize="450px">
<s-query-container>
<s-grid
gridTemplateColumns="@container (inline-size > 400px) 1fr 1fr 1fr, 1fr"
gap="base"
>
<s-grid-item>
<s-box padding="small" background="subdued">
```

--------------------------------

### Select Bundle Components with Resource Picker

Source: https://shopify.dev/docs/api/admin-extensions/latest/target-apis/contextual-apis/product-variant-details-configuration-api

Uses the resource picker to select variants and posts the configuration to a backend endpoint.

```jsx
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>
  );
}
```
Tokens:
Raw