App Bridge Actions Reference

The App Bridge SDK exposes a class for each action family plus the raw dispatch / dispatchAndWait calls underneath. Use the classes when you can — they validate types, manage subscriptions, and handle cleanup. Drop to the raw API when you need an action the SDK hasn’t wrapped yet.

Calling Convention

The SDK signatures are:

app.dispatch(action: string, payload?: object): string
app.dispatchAndWait(action: string, payload?: object): Promise<object>
app.subscribe(action: string, callback: (payload, error?) => void): () => void

action is the string name (e.g. 'TOAST_SHOW'), not an object. The SDK wraps the payload into the wire format { type: 'APP_BRIDGE_ACTION', action, payload, id } and posts it to the host. The host responds with { type: 'APP_BRIDGE_RESPONSE', action, id, payload, error? }.

import { createApp, Toast, Modal, ResourcePicker } from '@launchmystore/app-bridge';

const app = createApp({
  apiKey: 'your-client-id',
  host: new URLSearchParams(location.search).get('host'),
});

// Class-based — preferred
Toast.success(app, 'Saved!');

// Raw — equivalent
app.dispatch('TOAST_SHOW', { message: 'Saved!', type: 'success' });

// Request/response — class (subscribe pattern; dispatch() returns void)
ResourcePicker.create(app, { resourceType: 'product' })
  .subscribe('select', ({ selection }) => console.log(selection))
  .dispatch();

// Request/response — raw (resolves with { pickerId, selection })
const result = await app.dispatchAndWait('RESOURCE_PICKER_OPEN', { resourceType: 'product' });

Action Catalogue

Family	Class	Action names
Toast	`Toast`	`TOAST_SHOW`, `TOAST_DISMISS`
Modal	`Modal`	`MODAL_OPEN`, `MODAL_CLOSE`
Resource Picker	`ResourcePicker`	`RESOURCE_PICKER_OPEN`, `RESOURCE_PICKER_CLOSE`
Title Bar	`TitleBar`	`TITLE_BAR_UPDATE`
Navigation Menu	`NavigationMenu`	`NAV_MENU_UPDATE`
Contextual Save Bar	`ContextualSaveBar`	`CONTEXTUAL_SAVE_BAR`
Redirect	`Redirect`	`REDIRECT`
Loading	(raw)	`LOADING_START`, `LOADING_STOP`
Fullscreen	`Fullscreen`	`FULLSCREEN_ENTER`, `FULLSCREEN_EXIT`, `FULLSCREEN_TOGGLE` (host posts back `FULLSCREEN_ENTERED` / `FULLSCREEN_EXITED`)
Leave Confirmation	`LeaveConfirmation`	`LEAVE_CONFIRMATION_ENABLE`, `LEAVE_CONFIRMATION_DISABLE`
Session Token	`SessionToken`	`SESSION_TOKEN_REQUEST`
User	`User`	`USER_FETCH`
Config	`Config`	`CONFIG_FETCH`
Environment	`Environment`	`ENVIRONMENT_FETCH`
Features	`Features`	`FEATURES_QUERY`
Clipboard	`Clipboard`	`CLIPBOARD_READ_REQUEST` (writes run iframe-side, no postMessage)
Scanner	`Scanner`	`SCANNER_OPEN`, `SCANNER_CLOSE`
History	`History`	`HISTORY_PUSH`, `HISTORY_REPLACE`, `HISTORY_BACK`, `HISTORY_FORWARD`, `HISTORY_GO`
Print	`Print`	`PRINT`
Share	`Share`	`SHARE`
Lifecycle	`Lifecycle`	host-pushed `APP_FOCUS`, `APP_BLUR`, `APP_VISIBLE`, `APP_HIDDEN`
Cart (checkout/post-purchase)	`Cart`	`CART_LINES_CHANGE`, `DISCOUNT_CODE_CHANGE`, `GIFT_CARD_CHANGE`, `NOTE_CHANGE`, `ATTRIBUTE_CHANGE`
Buyer Journey (checkout)	`BuyerJourney`	`BUYER_JOURNEY_INTERCEPT_REQUEST`, `BUYER_JOURNEY_INTERCEPT_RESPONSE`

Cart and BuyerJourney are checkout-only. They’re documented in detail on the Checkout App Bridge page. Everything else runs in the admin host.

UI Actions

Toast (`TOAST_SHOW`)

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

// Convenience helpers
Toast.success(app, 'Changes saved!');
Toast.error(app, 'Save failed');
Toast.warning(app, 'Stock low');
Toast.info(app, 'Sync in progress');

// Full control
Toast.create(app, {
  message: 'Saved with tag',
  type: 'success',
  duration: 4000,
  action: { label: 'Undo', onAction: () => undoChange() },
  onDismiss: () => console.log('toast closed'),
}).dispatch();

// Raw equivalent
app.dispatch('TOAST_SHOW', {
  message: 'Saved!',
  type: 'success',
  duration: 4000,
});

Field	Type	Description
`message`	string	Up to 200 chars (longer is truncated)
`type`	`'success' \| 'error' \| 'warning' \| 'info'`	Default `info`
`duration`	number	ms; default 4000
`action`	object	Optional `{ label, onAction }` button
`onDismiss`	function	Fired when toast closes

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

// dispatch() returns void — outcomes arrive via the action callbacks
// and/or the subscribe() events, not a promise.
const modal = Modal.create(app, {
  title: 'Delete Product?',
  message: 'This cannot be undone.',
  primaryAction: { label: 'Delete', onAction: () => deleteProduct() },
  secondaryActions: [{ label: 'Cancel', onAction: () => {} }],
});

modal
  .subscribe('primary',   () => console.log('Delete clicked'))
  .subscribe('secondary', () => console.log('Cancel clicked'))
  .subscribe('close',     () => console.log('dismissed'));

modal.dispatch();   // opens the modal
modal.close();      // closes it programmatically

Options:

{ title?, message?, url?, size?: 'small' | 'medium' | 'large' | 'full', primaryAction?: { label, onAction }, secondaryActions?: Array<{ label, onAction }> }

. Host events (MODAL_PRIMARY_ACTION, MODAL_SECONDARY_ACTION, MODAL_CLOSE) are matched to the modal by modalId and routed to your callbacks. In React, prefer useConfirmationModal for an awaitable confirm dialog.

Loading (`LOADING_START` / `LOADING_STOP`)

app.dispatch('LOADING_START');
await save();
app.dispatch('LOADING_STOP');

Fullscreen (`FULLSCREEN_ENTER` / `EXIT` / `TOGGLE`)

import { Fullscreen, FullscreenAction } from '@launchmystore/app-bridge';

const fs = Fullscreen.create(app);   // create(app) takes only the app
fs.enter();                          // or fs.exit() / fs.toggle()
fs.dispatch(FullscreenAction.ENTER); // enum form: ENTER | EXIT
// or raw
app.dispatch('FULLSCREEN_ENTER');

// The host posts back FULLSCREEN_ENTERED / FULLSCREEN_EXITED —
// subscribe for state mirroring:
fs.subscribe('enter', () => setIsFullscreen(true))
  .subscribe('exit',  () => setIsFullscreen(false));

Title Bar (`TITLE_BAR_UPDATE`)

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

// Buttons use `label` + an `onAction` FUNCTION — the class routes the
// host's TITLE_BAR_PRIMARY_ACTION / TITLE_BAR_SECONDARY_ACTION events
// to your callbacks; you don't subscribe to custom event names.
TitleBar.create(app, {
  title: 'Product Reviews',
  primaryAction: { label: 'Add Review', onAction: () => addReview() },
  secondaryActions: [
    { label: 'Export',   onAction: () => exportAll() },
    { label: 'Settings', onAction: () => openSettings() },
  ],
  breadcrumbs: [
    { label: 'Apps',   url: '/admin/apps' },
    { label: 'My App', url: '/admin/apps/my-app' },
  ],
}).dispatch();

Redirect (`REDIRECT`)

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

Redirect.create(app, { url: '/admin/products/123' }).dispatch();
// or shorthand
app.redirect.dispatch({ url: '/admin/products/123' });
// or raw
app.dispatch('REDIRECT', { url: '/admin/products/123' });

// External
app.dispatch('REDIRECT', {
  url: 'https://example.com',
  external: true,
  newTab: true,
});

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

NavigationMenu.create(app, {
  items: [
    { label: 'Dashboard', destination: '/' },
    { label: 'Reviews', destination: '/reviews' },
    { label: 'Settings', destination: '/settings' },
  ],
  active: '/reviews',
}).dispatch();

History (`HISTORY_PUSH` / `REPLACE` / `BACK` / `FORWARD` / `GO`)

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

// push/replace take the path as a STRING (optional state object second)
History.create(app).push('/reviews?filter=pending');
History.create(app).replace('/reviews');
History.create(app).back();
History.create(app).forward();
History.create(app).go(-2);

Resource Picker (`RESOURCE_PICKER_OPEN` / `CLOSE`)

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

// Class API: dispatch() returns void — results arrive via subscribe().
ResourcePicker.create(app, {
  resourceType: 'product',
  multiple: true,
  selectionIds: ['prod_123', 'prod_987'],   // preferred
  filter: { query: 'shirt' },
})
  .subscribe('select', ({ selection }) => console.log('Selected:', selection))
  .subscribe('cancel', () => console.log('cancelled'))
  .dispatch();

// Raw API: dispatchAndWait resolves with { pickerId, selection }
const result = await app.dispatchAndWait('RESOURCE_PICKER_OPEN', {
  resourceType: 'product',
  multiple: true,
});
if (result.selection.length > 0) {
  console.log('Selected:', result.selection);
}

multiple: true lets the picker return more than one resource. Pass selectionIds (an array of ids) to pre-select. The legacy initialSelectionIds: [{ id }] shape still works but selectionIds is the recommended shape going forward. On cancel the picker responds with { selection: [] } — selection is always an array and there is no cancelled field; an empty selection is the cancel signal (class consumers get the dedicated cancel event).

Resource Type	Description
`product`	Products
`product_variant`	Product variants
`collection`	Collections
`customer`	Customers
`order`	Orders
`blog`	Blogs
`article`	Blog articles
`page`	Pages
`menu`	Navigation menus
`file`	Files / media — browse and upload (no app scope required; runs under the merchant admin session)
`metaobject`	Metaobjects

Response payload: { pickerId, selection: [...] } — selection is always an array (length 1 for single-select; empty on cancel). For non-file types each element is a stable handle string: handle for product / collection / blog / article / page / menu, email for customer, order_number for order, id for product_variant. Store the handle; resolve extra fields server-side. For file each element is a rich object so you get a usable URL directly — no extra lookup needed:

{ "id": "<mediaId>", "url": "https://cdn…/asset.png", "filename": "asset.png", "mimeType": "image/png" }

The file picker is the full Media Library — the merchant can search, browse, and upload new files in-place, then pick one or more. multiple: true returns several objects. id is the stable mediaId; url is a permanent CDN URL. Other resource types select existing records only.

Save Bar (`CONTEXTUAL_SAVE_BAR`)

import { ContextualSaveBar, SaveBarAction } from '@launchmystore/app-bridge';

const bar = ContextualSaveBar.create(app, {
  saveAction:    { label: 'Save' },
  discardAction: { label: 'Discard' },
  fullWidth: false,
});

// Events come through the bar instance, not app.subscribe():
bar.subscribe('save', async () => {
  bar.setSaveLoading(true);
  await saveChanges();
  bar.hide();
});
bar.subscribe('discard', () => {
  discardChanges();
  bar.hide();
});

bar.show();
// bar.update({ saveAction: { disabled: true } }) while visible

The raw dispatch is a single CONTEXTUAL_SAVE_BAR action with payload { action: 'SHOW' | 'HIDE' | 'UPDATE', ... }; the host emits CONTEXTUAL_SAVE_BAR_SAVE / CONTEXTUAL_SAVE_BAR_DISCARD events which the class routes to your subscribe callbacks — use the class.

Leave Confirmation (`LEAVE_CONFIRMATION_ENABLE` / `DISABLE`)

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

LeaveConfirmation.create(app, {
  message: 'You have unsaved changes. Are you sure you want to leave?',
}).enable();

// later
LeaveConfirmation.create(app).disable();

Session & Auth (`SESSION_TOKEN_REQUEST`)

// Simple — but NOT cached: each call issues a fresh SESSION_TOKEN_REQUEST
const token = await app.getSessionToken();

fetch('/api/v1/data', {
  headers: { Authorization: `Bearer ${token}` },
});

app.getSessionToken() is a thin wrapper over dispatchAndWait('SESSION_TOKEN_REQUEST') — it returns { token } but does not cache. For caching + auto-refresh (reuse the token while more than 30s from its JWT exp, refresh otherwise), use the SessionToken action class or the useSessionToken React hook.

User / Config / Environment / Features

import { User, Config, Environment, Features } from '@launchmystore/app-bridge';

const user = await User.create(app).fetch();
// { id, email, name, locale, timezone? }

const config = await Config.create(app).fetch();
// { storeId, shopDomain, primaryDomain, hasCustomDomain, shopName,
//   currency, currencySymbol, country, locale, timezone?, plan, features }

const env = await Environment.create(app).fetch();
// { platform, version, apiVersion, embedded, mobile, pos, features }

// Features is a LOCAL capability check — it never round-trips to the host:
const features = Features.create(app);
features.isAvailable('ResourcePicker');       // boolean
features.getAll();                            // string[] of available features
features.checkMultiple(['Toast', 'Share']);   // { Toast: true, Share: false }

// If you want the host's own answer, use the raw action:
const hostFlags = await app.dispatchAndWait('FEATURES_QUERY');

Raw action names: USER_FETCH, CONFIG_FETCH, ENVIRONMENT_FETCH, FEATURES_QUERY (raw only — the Features class does not dispatch it).

Browser APIs

Clipboard (`CLIPBOARD_WRITE` / `CLIPBOARD_READ_REQUEST`)

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

const clipboard = Clipboard.create(app);
await clipboard.write('Copied!');       // or clipboard.copy(text)
const text = await clipboard.read();    // or clipboard.paste()

// One-shot static helper for writes:
await Clipboard.copyText(app, 'Copied!');

Reads go through the host because Chrome blocks clipboard-read in cross-origin iframes. Writes (copy()) work iframe-side directly.

Scanner (`SCANNER_OPEN` / `SCANNER_CLOSE`)

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

try {
  const result = await Scanner.create(app).capture();
  console.log('Scanned:', result.data, result.type); // type: 'qr' | 'barcode'
} catch (err) {
  // Cancel REJECTS with Error('Scanner cancelled'); scanner failures
  // reject with the host's error message.
}

Mobile-only. On desktop (or when the merchant dismisses the scanner) the capture() promise rejects with Error('Scanner cancelled') — there is no cancelled field on a resolved payload.

Print (`PRINT`)

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

Print.create(app).dispatch();
// or
app.dispatch('PRINT');

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

Share.create(app, {
  title: 'Check out this product',
  url: 'https://store.com/products/widget',
  text: 'Best socks ever',
}).dispatch();

Lifecycle

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

const lifecycle = Lifecycle.create(app);
const off = lifecycle.subscribe('visible', () => loadData());
lifecycle.subscribe('hidden', () => saveState());

// Or several at once:
lifecycle.subscribeAll({
  focus:  () => console.log('focused'),
  blur:   () => console.log('blurred'),
});

lifecycle.isFocused();   // boolean helpers
lifecycle.isVisible();

Events: 'focus' | 'blur' | 'visible' | 'hidden' — driven by the iframe’s own focus/blur/visibilitychange plus the host-pushed APP_FOCUS / APP_BLUR / APP_VISIBLE / APP_HIDDEN actions. There are no mount/unmount events — run mount logic in your own bootstrap.

Checkout-only Surfaces

The following actions are wired into the customer-checkout host and the post-purchase host. See Checkout App Bridge for the full contract.

Cart (`CART_LINES_CHANGE`, `DISCOUNT_CODE_CHANGE`, `NOTE_CHANGE`, `ATTRIBUTE_CHANGE`, `GIFT_CARD_CHANGE`)

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

const cart = Cart.create(app);

await cart.applyCartLinesChange({
  type: 'addCartLine',
  merchandiseId: 'gid://launchmystore/Variant/abc-123',
  quantity: 1,
});

await cart.applyDiscountCodeChange({
  type: 'addDiscountCode',
  code: 'WELCOME10',
});

await cart.applyNoteChange({
  type: 'updateNote',
  note: 'Leave with concierge',
});

await cart.applyAttributeChange({
  type: 'updateAttribute',
  key: 'gift_wrap',
  value: 'true',
});

Buyer Journey (`BUYER_JOURNEY_INTERCEPT_REQUEST/RESPONSE`)

Block the customer from advancing to payment until your condition is met.

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

const journey = BuyerJourney.create(app);
const unsubscribe = journey.intercept(() => {
  if (!termsAccepted) {
    return {
      behavior: 'block',
      reason: 'You must accept the terms before continuing.',
    };
  }
  return { behavior: 'allow' };
});

// later
unsubscribe();

Error Handling

try {
  const result = await app.dispatchAndWait('RESOURCE_PICKER_OPEN', {
    resourceType: 'product',
  });
} catch (error) {
  // Timeouts reject with Error('App Bridge: timeout waiting for <ACTION> response');
  // host-reported failures reject with the host's error string verbatim.
  if (error.message.includes('timeout')) {
    // Host did not respond — likely action not supported on this host
  } else {
    console.error(error);
  }
}

The SDK rejects with a timeout error after 10 seconds if the host never responds. That’s the most common failure mode when calling an admin-only action from a checkout host (or vice versa) — check the table at the top of this page for which host each action is wired to.

Complete Example

import {
  createApp, Toast, ResourcePicker, ContextualSaveBar,
} from '@launchmystore/app-bridge';

const app = createApp({
  apiKey: 'your-client-id',
  host: new URLSearchParams(location.search).get('host'),
});

document.getElementById('add-review').addEventListener('click', async () => {
  // Raw round-trip: resolves with { pickerId, selection }
  const picker = await app.dispatchAndWait('RESOURCE_PICKER_OPEN', {
    resourceType: 'product',
  });
  if (picker.selection.length === 0) return;   // empty = cancelled

  app.dispatch('LOADING_START');
  try {
    const token = await app.getSessionToken();
    await fetch('/api/reviews', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ productId: picker.selection[0].id }),
    });
    Toast.success(app, 'Review added!');
  } catch (err) {
    Toast.error(app, 'Failed to add review');
  } finally {
    app.dispatch('LOADING_STOP');
  }
});

I18n (`I18N_UPDATE`)

The host pushes the merchant’s admin locale to your iframe and re-pushes on every change. Subscribe via the I18n action class — it caches the last dictionary and exposes translate / formatNumber / formatDate helpers backed by Intl.*.

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

const i18n = I18n.create(app);
i18n.subscribe(({ locale, dictionary }) => {
  console.log('Locale changed to', locale);
});

// Plain interpolation map (no reserved keys → second arg is treated as vars).
const greeting = i18n.translate('hello', { name: 'Alex' });

// Options form: supply a fallback string when the key is missing AND
// interpolation vars under `vars`. The fallback wins over the bare key.
const label = i18n.translate('settings.title', {
  default: 'Settings',
  vars: { user: 'Alex' },
});

const price = i18n.formatNumber(19.99, { style: 'currency', currency: 'USD' });

The wire payload is { locale: string, dictionary: Record<string,string> }. The host derives locale from the admin’s cookie/localStorage and the dictionary from /api/i18n/admin?locale=... (silently {} if the endpoint is absent — your app should fall back to Intl.* for formatting).

REST API (`CONFIG_GET` + session tokens)

Use the RestApi action class to call the LaunchMyStore REST API (/api/v1/...) with an automatically-attached session token. The host exposes the API base URL via CONFIG_GET so your iframe doesn’t have to hardcode api.launchmystore.io.

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

const api = RestApi.create(app);
const { products } = await api.fetchJson('/api/v1/products?limit=50');

// Plain-object bodies are auto-JSON-encoded; `Content-Type` is set unless
// you provide one yourself. Pass a string / FormData / Blob to opt out.
await api.fetch('/api/v1/products/123', {
  method: 'PUT',
  body: { title: 'New title' },
});

fetch() resolves to the raw Response. fetchJson<T>() parses JSON and returns the typed body. Token + apiBase are resolved lazily on the first call and cached.

Intents (`INTENT_LAUNCH`)

Launch another app’s admin action from inside your own — for example, chain a “Send invoice” action after editing an order.

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

const intents = Intents.create(app);
const result = await intents.launchAndWait('invoice-app.send-invoice', {
  orderId: 'gid://launchmystore/Order/123',
});

if (result.launched) {
  console.log('Opened intent', result.target);
}

The target string is <appHandle>.<extensionHandle> — the host resolves it against the merchant’s registered admin extensions and opens the matching admin_action modal. Missing targets return { error: '...' }.

Action constants

The SDK does not export a centralised ACTIONS enum — every action name is a plain string passed to app.dispatch / app.dispatchAndWait. The canonical source of truth for each name is the corresponding action class itself:

import {
  Toast,             // 'TOAST_SHOW', 'TOAST_DISMISS'
  Modal,             // 'MODAL_OPEN', 'MODAL_CLOSE'
  ResourcePicker,    // 'RESOURCE_PICKER_OPEN', 'RESOURCE_PICKER_CLOSE'
  TitleBar,          // 'TITLE_BAR_UPDATE'
  NavigationMenu,    // 'NAV_MENU_UPDATE'
  ContextualSaveBar, // 'CONTEXTUAL_SAVE_BAR'
  Redirect,          // 'REDIRECT'
  Fullscreen,        // 'FULLSCREEN_ENTER' | 'EXIT' | 'TOGGLE'
  LeaveConfirmation, // 'LEAVE_CONFIRMATION_ENABLE' | 'DISABLE'
  Scanner,           // 'SCANNER_OPEN', 'SCANNER_CLOSE'
  User,              // 'USER_FETCH'
  Config,            // 'CONFIG_FETCH' (admin) / 'CONFIG_GET' (RestApi)
  Environment,       // 'ENVIRONMENT_FETCH'
  Features,          // 'FEATURES_QUERY'
  Clipboard,         // 'CLIPBOARD_READ_REQUEST' (writes run iframe-side)
  Print,             // 'PRINT'
  Share,             // 'SHARE'
  History,           // 'HISTORY_PUSH' | 'REPLACE' | 'BACK' | 'FORWARD' | 'GO'
  Lifecycle,         // host-pushed 'APP_FOCUS' | 'APP_BLUR' | 'APP_VISIBLE' | 'APP_HIDDEN'
  SessionToken,      // 'SESSION_TOKEN_REQUEST'
  Cart,              // 'CART_LINES_CHANGE' | 'DISCOUNT_CODE_CHANGE'
                     // | 'GIFT_CARD_CHANGE'  | 'NOTE_CHANGE'
                     // | 'ATTRIBUTE_CHANGE'  | 'METAFIELD_CHANGE'
  BuyerJourney,      // 'BUYER_JOURNEY_INTERCEPT_REQUEST/RESPONSE'
  I18n,              // 'I18N_UPDATE'           (host-pushed)
  RestApi,           // 'CONFIG_GET' (resolves apiBase)
  Intents,           // 'INTENT_LAUNCH'
} from '@launchmystore/app-bridge';

APP_BRIDGE_FEATURES (exported from the package root) is the one named constant the SDK ships — a readonly array of PascalCase feature names ('Toast', 'Modal', 'ResourcePicker', …). Use it with the local Features helper:

import { Features, APP_BRIDGE_FEATURES } from '@launchmystore/app-bridge';

const features = Features.create(app);
if (features.isAvailable('ResourcePicker')) {
  // Safe to call ResourcePicker
}
APP_BRIDGE_FEATURES.includes('Scanner');   // array membership check

If you need a raw string action name that no class wraps yet (rare — this only happens for in-flight features) call app.dispatch(name, ...) directly. Action names are case-sensitive and the host silently ignores unknown names, so a typo will surface as a 10-second timeout in dispatchAndWait. See Error Handling for the recovery pattern.

Get Started

Guides

Extensions

Functions

App Bridge

Billing

AI & MCP

Actions Reference

App Bridge Actions Reference

Calling Convention

Action Catalogue

UI Actions

Toast (`TOAST_SHOW`)

Loading (`LOADING_START` / `LOADING_STOP`)

Fullscreen (`FULLSCREEN_ENTER` / `EXIT` / `TOGGLE`)

Title Bar (`TITLE_BAR_UPDATE`)

Navigation

Redirect (`REDIRECT`)

Navigation Menu (`NAV_MENU_UPDATE`)

History (`HISTORY_PUSH` / `REPLACE` / `BACK` / `FORWARD` / `GO`)

Resource Picker (`RESOURCE_PICKER_OPEN` / `CLOSE`)

Save Bar (`CONTEXTUAL_SAVE_BAR`)

Leave Confirmation (`LEAVE_CONFIRMATION_ENABLE` / `DISABLE`)

Session & Auth (`SESSION_TOKEN_REQUEST`)

User / Config / Environment / Features

Browser APIs

Clipboard (`CLIPBOARD_WRITE` / `CLIPBOARD_READ_REQUEST`)

Scanner (`SCANNER_OPEN` / `SCANNER_CLOSE`)

Print (`PRINT`)

Lifecycle

Checkout-only Surfaces

Cart (`CART_LINES_CHANGE`, `DISCOUNT_CODE_CHANGE`, `NOTE_CHANGE`, `ATTRIBUTE_CHANGE`, `GIFT_CARD_CHANGE`)

Buyer Journey (`BUYER_JOURNEY_INTERCEPT_REQUEST/RESPONSE`)

Error Handling

Complete Example

I18n (`I18N_UPDATE`)

REST API (`CONFIG_GET` + session tokens)

Intents (`INTENT_LAUNCH`)

Action constants

See Also

​App Bridge Actions Reference

​Calling Convention

​Action Catalogue

​UI Actions

​Toast (TOAST_SHOW)

​Modal (MODAL_OPEN / MODAL_CLOSE)

​Loading (LOADING_START / LOADING_STOP)

​Fullscreen (FULLSCREEN_ENTER / EXIT / TOGGLE)

​Title Bar (TITLE_BAR_UPDATE)

​Navigation

​Redirect (REDIRECT)

​Navigation Menu (NAV_MENU_UPDATE)

​History (HISTORY_PUSH / REPLACE / BACK / FORWARD / GO)

​Resource Picker (RESOURCE_PICKER_OPEN / CLOSE)

​Save Bar (CONTEXTUAL_SAVE_BAR)

​Leave Confirmation (LEAVE_CONFIRMATION_ENABLE / DISABLE)

​Session & Auth (SESSION_TOKEN_REQUEST)

​User / Config / Environment / Features

​Browser APIs

​Clipboard (CLIPBOARD_WRITE / CLIPBOARD_READ_REQUEST)

​Scanner (SCANNER_OPEN / SCANNER_CLOSE)

​Print (PRINT)

​Share (SHARE)

​Lifecycle

​Checkout-only Surfaces

​Cart (CART_LINES_CHANGE, DISCOUNT_CODE_CHANGE, NOTE_CHANGE, ATTRIBUTE_CHANGE, GIFT_CARD_CHANGE)

​Buyer Journey (BUYER_JOURNEY_INTERCEPT_REQUEST/RESPONSE)

​Error Handling

​Complete Example

​I18n (I18N_UPDATE)

​REST API (CONFIG_GET + session tokens)

​Intents (INTENT_LAUNCH)

​Action constants

​See Also

App Bridge Actions Reference

Calling Convention

Action Catalogue

UI Actions

Toast (`TOAST_SHOW`)

Modal (`MODAL_OPEN` / `MODAL_CLOSE`)

Loading (`LOADING_START` / `LOADING_STOP`)

Fullscreen (`FULLSCREEN_ENTER` / `EXIT` / `TOGGLE`)

Title Bar (`TITLE_BAR_UPDATE`)

Navigation

Redirect (`REDIRECT`)

Navigation Menu (`NAV_MENU_UPDATE`)

History (`HISTORY_PUSH` / `REPLACE` / `BACK` / `FORWARD` / `GO`)

Resource Picker (`RESOURCE_PICKER_OPEN` / `CLOSE`)

Save Bar (`CONTEXTUAL_SAVE_BAR`)

Leave Confirmation (`LEAVE_CONFIRMATION_ENABLE` / `DISABLE`)

Session & Auth (`SESSION_TOKEN_REQUEST`)

User / Config / Environment / Features

Browser APIs

Clipboard (`CLIPBOARD_WRITE` / `CLIPBOARD_READ_REQUEST`)

Scanner (`SCANNER_OPEN` / `SCANNER_CLOSE`)

Print (`PRINT`)

Share (`SHARE`)

Lifecycle

Checkout-only Surfaces

Cart (`CART_LINES_CHANGE`, `DISCOUNT_CODE_CHANGE`, `NOTE_CHANGE`, `ATTRIBUTE_CHANGE`, `GIFT_CARD_CHANGE`)

Buyer Journey (`BUYER_JOURNEY_INTERCEPT_REQUEST/RESPONSE`)

Error Handling

Complete Example

I18n (`I18N_UPDATE`)

REST API (`CONFIG_GET` + session tokens)

Intents (`INTENT_LAUNCH`)

Action constants

See Also