Admin Action Extensions

Admin actions add a button to an admin resource page (e.g. the order detail page). When the merchant clicks it, your app opens in a modal iframe with the current resource id in the URL — perfect for “Refund this order”, “Issue gift card from order”, “Resync inventory”, or any other one-shot operation that needs your app’s UI but does not belong as an always-visible block.

If you need a panel that is always visible on a resource page, use an Admin Block instead. Use an Admin Action when the merchant only needs the UI on demand.

How Admin Actions Work

┌──────────────────────────────────────────────────────────────┐
│  LaunchMyStore Admin · Order #1042                           │
├──────────────────────────────────────────────────────────────┤
│  [Refund]  [Send invoice]  [Refund helper ← your action]     │
│                                                              │
│  Order details ...                                           │
└──────────────────────────────────────────────────────────────┘
                            ↓ click
┌──────────────────────────────────────────────────────────────┐
│  Modal · Refund helper                                       │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ <iframe src="https://app.example.com/refund?orderId..>│  │
│  │  [Your UI: pick line items, partial amount, reason]   │  │
│  │                                                       │  │
│  │  [Cancel]                              [Issue refund] │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

The host renders the button in the resource page’s action toolbar. On click, it opens a modal with an iframe pointing at your appUrl plus query parameters describing the resource. Your app drives the UX inside the modal and uses App Bridge to close it, show a toast, or trigger a host redirect when work is done.

Available Targets

Admin Actions are wired at specific resource-detail action slots. The initial release ships with one target — more will be added in subsequent releases.

Target	Where it renders
`admin.order-details.action.render`	Action toolbar on the order detail page

Additional targets for product, customer, draft order, and collection detail pages are planned next. Track the changelog for new admin.{resource}-details.action.render targets as they ship.

Extension Manifest

Declare admin actions in your app.json under extensions.adminActions, or send them inline to the install pipeline. Each entry corresponds to one button.

Inline in `app.json`

{
  "handle": "refund-helper",
  "name": "Refund Helper",
  "version": "1.0.0",
  "extensions": {
    "adminActions": [
      {
        "handle": "issue-partial-refund",
        "title": "Refund helper",
        "target": "admin.order-details.action.render",
        "appUrl": "https://refund-helper.example.com/admin/refund",
        "icon": "https://refund-helper.example.com/icon.svg"
      }
    ]
  }
}

Schema file form

When installed through the install pipeline, each admin action is persisted as a single schema file at:

extensions/{domainSlug}/{appHandle}/admin-actions/{handle}.schema.json

{
  "target": "admin.order-details.action.render",
  "title": "Refund helper",
  "appUrl": "https://refund-helper.example.com/admin/refund",
  "icon": "https://refund-helper.example.com/icon.svg"
}

Fields

Field	Required	Description
`handle`	yes	URL-safe identifier — unique per app. Also used as the schema filename.
`target`	yes	Action slot the button is rendered into. See Available targets.
`title`	yes	Button label shown to the merchant.
`appUrl`	yes	HTTPS URL loaded into the modal iframe. Receives resource context as query params.
`icon`	no	URL of an SVG/PNG icon shown next to the button label.

Installing Admin Actions

Action manifests are deployed by the install pipeline the same way theme blocks or snippets are. POST /api/apps/install-extensions is a server-to-server endpoint gated by the platform’s internal API key (no CORS) — the backend calls it as part of the app install flow; it is not called directly from a browser with a merchant access token. The endpoint accepts an adminActions array on the extensions payload:

curl -X POST https://store.launchmystore.io/api/apps/install-extensions \
  -H "Content-Type: application/json" \
  -H "X-Internal-API-Key: $INTERNAL_API_KEY" \
  -d '{
    "domainSlug": "acme-store",
    "appHandle": "refund-helper",
    "extensions": {
      "adminActions": [
        {
          "handle": "issue-partial-refund",
          "title": "Refund helper",
          "target": "admin.order-details.action.render",
          "appUrl": "https://refund-helper.example.com/admin/refund",
          "icon": "https://refund-helper.example.com/icon.svg"
        }
      ]
    }
  }'

await fetch('https://store.launchmystore.io/api/apps/install-extensions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    domainSlug: 'acme-store',
    appHandle: 'refund-helper',
    extensions: {
      adminActions: [
        {
          handle: 'issue-partial-refund',
          title: 'Refund helper',
          target: 'admin.order-details.action.render',
          appUrl: 'https://refund-helper.example.com/admin/refund',
          icon: 'https://refund-helper.example.com/icon.svg',
        },
      ],
    },
  }),
});

Each entry produces a {handle}.schema.json file under the app’s admin-actions/ directory. The host’s admin extension API picks it up on the next request — /api/apps/admin-extensions?target=... returns entries with type: "admin_action" for actions, as opposed to type: "admin_block" for blocks.

Iframe Context

When the merchant clicks the action button, your appUrl is loaded into the modal iframe with these query parameters appended:

Parameter	Always set	Description
`target`	yes	The extension’s manifest `target`.
`domainSlug`	yes	The merchant’s domain slug.
`host`	yes	`btoa(window.location.origin)` — base64-encoded admin origin.
`extensionId`	yes	The extension’s id — echo it in `APP_BRIDGE_RESIZE` messages.
`resourceId`	optional	The id of the resource currently being viewed (e.g. `ord_8a7f...`).
`resourceType`	optional	The type of the resource (e.g. `order`).

const params = new URLSearchParams(location.search);
const orderId = params.get('resourceId');
const resourceType = params.get('resourceType');
const domainSlug = params.get('domainSlug');

The action modal does append an extensionId query param — same as admin blocks. Read it from the query string and echo it in your APP_BRIDGE_RESIZE messages, or the host ignores the resize. Resize clamp for the modal is Math.min(height, 800), with a 400px default.

// Auto-resize the action modal
const extensionId = new URLSearchParams(location.search).get('extensionId');
window.parent.postMessage({
  type: 'APP_BRIDGE_RESIZE',
  extensionId,
  height: document.body.scrollHeight,
}, '*');

Communicating with the Host

Admin actions use the standard App Bridge SDK. app.dispatch(action, payload) and app.dispatchAndWait(action, payload) take an action string plus payload — not a {type, payload} envelope. After your action completes, dismiss the modal so the merchant returns to the resource page:

import { createApp } from '@launchmystore/app-bridge';

const app = createApp({
  apiKey: process.env.NEXT_PUBLIC_APP_CLIENT_ID,
  host: new URLSearchParams(location.search).get('host'),
});

// Refund completed → close the modal
app.dispatch('MODAL_CLOSE');

Show a toast on success

app.dispatch('TOAST_SHOW', {
  message: 'Refund issued for $24.00',
  duration: 3000,
  type: 'success',          // 'success' | 'error' | 'warning' | 'info'
});
app.dispatch('MODAL_CLOSE');

Block close while a request is in flight

import { LeaveConfirmation } from '@launchmystore/app-bridge';

const leave = LeaveConfirmation.create(app, {
  message: 'Refund in progress — leave anyway?',
});

leave.enable();
await issueRefund();
leave.disable();

app.dispatch('MODAL_CLOSE');

The LeaveConfirmation helper also dispatches the underlying LEAVE_CONFIRMATION_ENABLE / LEAVE_CONFIRMATION_DISABLE actions for you, and wires the browser’s beforeunload event so closing the tab triggers the confirmation too.

Complete Example

A minimal refund helper that loads the order, takes a partial amount, and issues the refund via your app’s backend before closing the modal.

import { createApp } from '@launchmystore/app-bridge';
import { useEffect, useState } from 'react';

export default function RefundHelper() {
  const [order, setOrder] = useState(null);
  const [amount, setAmount] = useState('');
  const [submitting, setSubmitting] = useState(false);

  const app = createApp({
    apiKey: process.env.NEXT_PUBLIC_APP_CLIENT_ID,
    host: new URLSearchParams(location.search).get('host'),
  });

  useEffect(() => {
    const params = new URLSearchParams(location.search);
    const orderId = params.get('resourceId');
    if (orderId) loadOrder(orderId);
  }, []);

  const loadOrder = async (orderId) => {
    const token = await app.getSessionToken();
    const response = await fetch(`/api/orders/${orderId}`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    setOrder(await response.json());
  };

  const submit = async () => {
    setSubmitting(true);
    try {
      const token = await app.getSessionToken();
      await fetch(`/api/orders/${order.id}/refunds`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${token}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ amount: parseFloat(amount) }),
      });
      app.dispatch('TOAST_SHOW', {
        message: `Refunded $${amount}`,
        type: 'success',
      });
      app.dispatch('MODAL_CLOSE');
    } catch (err) {
      app.dispatch('TOAST_SHOW', {
        message: 'Refund failed — please try again',
        type: 'error',
      });
    } finally {
      setSubmitting(false);
    }
  };

  if (!order) return <p>Loading order...</p>;

  return (
    <div className="refund-helper">
      <h3>Refund order {order.name}</h3>
      <p>Total paid: ${order.total}</p>

      <label>
        Refund amount
        <input
          type="number"
          step="0.01"
          value={amount}
          onChange={(e) => setAmount(e.target.value)}
        />
      </label>

      <div className="actions">
        <button onClick={() => app.dispatch('MODAL_CLOSE')}>
          Cancel
        </button>
        <button onClick={submit} disabled={submitting || !amount}>
          {submitting ? 'Refunding...' : 'Issue refund'}
        </button>
      </div>
    </div>
  );
}

Admin Actions vs Admin Blocks

	Admin Action	Admin Block
Trigger	Click a button	Always rendered with the page
Layout	Modal iframe on top of the page	Inline iframe in the page layout
Use cases	Refund, resync, issue gift card, one-shot ops	Reviews summary, warehouse status, KPIs
`type` field	`admin_action`	`admin_block`
File location	`admin-actions/{handle}.schema.json`	`app.json` → `extensions.adminExtensions[]`
Discovery API	`/api/apps/admin-extensions?type=admin_action`	`/api/apps/admin-extensions?type=admin_block`

Get Started

Guides

Extensions

Functions

App Bridge

Billing

AI & MCP

Admin Action Extensions

Admin Action Extensions

How Admin Actions Work

Available Targets

Extension Manifest

Inline in `app.json`

Schema file form

Fields

Installing Admin Actions

Iframe Context

Communicating with the Host

Show a toast on success

Block close while a request is in flight

Complete Example

Admin Actions vs Admin Blocks

See Also

​Admin Action Extensions

​How Admin Actions Work

​Available Targets

​Extension Manifest

​Inline in app.json

​Schema file form

​Fields

​Installing Admin Actions

​Iframe Context

​Communicating with the Host

​Close the modal when done

​Show a toast on success

​Block close while a request is in flight

​Complete Example

​Admin Actions vs Admin Blocks

​See Also

Admin Action Extensions

How Admin Actions Work

Available Targets

Extension Manifest

Inline in `app.json`

Schema file form

Fields

Installing Admin Actions

Iframe Context

Communicating with the Host

Close the modal when done

Show a toast on success

Block close while a request is in flight

Complete Example

Admin Actions vs Admin Blocks

See Also