Guides

Examples

A complete sample app: block, headless action, modal action, hook, iframe page and a bulk action on warehouse transfers.

View Markdown

Field names follow the Open API.

The "ERP sync" sample app contains:

  1. A block in the order form showing the order's ERP sync status.
  2. A headless "Push to ERP" action.
  3. A "Warranty card" modal action with a form.
  4. A hook that blocks saving orders above 20 million without a phone number.
  5. An "ERP reconciliation" iframe page listing orders.
  6. A bulk action that pushes the selected warehouse transfers to the ERP, showing that other resources work the same way.

The ERP in this example is https://erp.example.com, managed by the shop, with CORS enabled for the app's sandbox domain.

Manifest

JSON
{
  "handle": "erp-sync",
  "name": "ERP sync",
  "version": "1.0.0",
  "api_version": "2026-01",
  "access": { "methods": ["GET", "PUT"] },
  "network": { "allowed_origins": ["https://erp.example.com"] },
  "extensions": [
    { "target": "nav.item", "id": "nav", "label": "ERP reconciliation", "page": "reconcile" },
    { "target": "app.page", "id": "reconcile", "title": "ERP reconciliation", "render": "iframe", "entry": "page/index.html" },
    {
      "target": "order.details.block",
      "id": "erp-status",
      "module": "extensions/erp-status.tsx",
      "conditions": { "mode": ["edit"] }
    },
    {
      "target": "order.details.action",
      "id": "push-erp",
      "label": "Push to ERP",
      "presentation": "headless",
      "module": "extensions/push-erp.ts",
      "conditions": { "mode": ["edit"] }
    },
    {
      "target": "order.details.action",
      "id": "warranty",
      "label": "Warranty card",
      "presentation": "modal",
      "module": "extensions/warranty.tsx",
      "conditions": { "mode": ["edit"] }
    },
    {
      "target": "order.before_submit",
      "id": "require-phone",
      "module": "extensions/require-phone.ts",
      "timeout_ms": 1000,
      "on_error": "allow"
    },
    {
      "target": "warehouse_transfer.index.selection-action",
      "id": "push-transfers",
      "label": "Push to ERP",
      "presentation": "headless",
      "module": "extensions/push-transfers.ts"
    }
  ]
}

1. ERP status block

extensions/erp-status.tsx

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

type Status = { synced: boolean; erp_code?: string; synced_at?: string };

function ErpStatus({ systemId }: { systemId: number }) {
  const [status, setStatus] = useState<Status | null>(null);
  const [error, setError] = useState<string | null>(null);

  const load = async () => {
    setError(null);
    try {
      const res = await fetch(`https://erp.example.com/api/orders/${systemId}`);
      if (!res.ok) throw new Error(`ERP returned ${res.status}`);
      setStatus(await res.json());
    } catch (e) {
      setError(e.message);
    }
  };

  useEffect(() => { load(); }, [systemId]);

  return (
    <pos-section heading="ERP">
      <pos-button slot="actions" variant="tertiary" onClick={load}>Reload</pos-button>
      {error && <pos-banner tone="critical">{error}</pos-banner>}
      {!error && !status && <pos-spinner size="small" />}
      {status && (
        <pos-stack direction="horizontal" gap="small" align="center">
          <pos-badge tone={status.synced ? 'success' : 'warning'}>
            {status.synced ? 'Synced' : 'Not synced'}
          </pos-badge>
          {status.erp_code && <pos-text tone="subdued">ERP code: {status.erp_code}</pos-text>}
        </pos-stack>
      )}
    </pos-section>
  );
}

export default async function (data) {
  render(<ErpStatus systemId={data.record.system_id} />, document.body);
}

2. Headless action "Push to ERP"

extensions/push-erp.ts

TypeScript
export default async function (data) {
  const shopId = pos.shop.id;
  const systemId = data.record.system_id;

  const { data: order } = await pos.api.get(`/shops/${shopId}/orders/${systemId}`);

  const res = await fetch('https://erp.example.com/api/orders', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      pos_order_id: systemId,
      customer_name: order.bill_full_name,
      total: order.total_price,
      items: order.items,
    }),
  });
  if (!res.ok) throw new Error(`ERP rejected the order (${res.status})`);
  const { erp_code } = await res.json();

  // Store the ERP code in the order note; see the Open API docs for updatable fields.
  const note = [order.note, `ERP: ${erp_code}`].filter(Boolean).join('\n');
  await pos.api.put(`/shops/${shopId}/orders/${systemId}`, { note });

  return { message: `Pushed to ERP: ${erp_code}`, refresh: true };
}

Thrown errors (throw) are shown by POS as error toasts.

3. Modal action "Warranty card"

extensions/warranty.tsx

TSX
import { render } from 'preact';
import { useState } from 'preact/hooks';

function WarrantyForm({ systemId }: { systemId: number }) {
  const [serial, setSerial] = useState('');
  const [expiresOn, setExpiresOn] = useState<string | null>(null);
  const [saving, setSaving] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const submit = async () => {
    if (!serial) return setError('Enter the serial number');
    setSaving(true);
    setError(null);
    try {
      const res = await fetch('https://erp.example.com/api/warranties', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ pos_order_id: systemId, serial, expires_on: expiresOn }),
      });
      if (!res.ok) throw new Error(`ERP returned ${res.status}`);
      pos.toast.show('Warranty card created');
      pos.close();
    } catch (e) {
      setError(e.message);
    } finally {
      setSaving(false);
    }
  };

  return (
    <pos-stack>
      {error && <pos-banner tone="critical">{error}</pos-banner>}
      <pos-text-field label="Serial number" required value={serial} onChange={(e) => setSerial(e.detail)} />
      <pos-date-picker label="Warranty expires on" value={expiresOn} onChange={(e) => setExpiresOn(e.detail)} />
      <pos-stack direction="horizontal" justify="end" gap="small">
        <pos-button onClick={() => pos.close()}>Cancel</pos-button>
        <pos-button variant="primary" loading={saving} onClick={submit}>Create card</pos-button>
      </pos-stack>
    </pos-stack>
  );
}

export default async function (data) {
  render(<WarrantyForm systemId={data.record.system_id} />, document.body);
}

4. Hook that blocks saving an order

extensions/require-phone.ts

TypeScript
const LIMIT = 20_000_000;

export default async function ({ draft }) {
  if (draft.total_price > LIMIT && !draft.bill_phone_number) {
    return { ok: false, message: 'Orders above 20 million need the recipient phone number.' };
  }
  return { ok: true };
}

If the shop hides bill_phone_number through access.hidden_order_fields, the field is always undefined and the hook will block every large order. Check access when writing hooks.

5. "ERP reconciliation" iframe page

page/src/main.tsx (React + Vite)

TSX
import { createRoot } from 'react-dom/client';
import { useEffect, useState } from 'react';
import { PosButton, PosPage, PosProvider, PosSection, PosTable, usePos } from '@pancake-pos/ui';

type Order = { system_id: number; id: number; bill_full_name?: string; total_price?: number; inserted_at: string };

function Reconcile() {
  const pos = usePos();
  const [page, setPage] = useState(1);
  const [orders, setOrders] = useState<Order[]>([]);
  const [total, setTotal] = useState(0);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const controller = new AbortController();
    setLoading(true);
    pos.api
      .get(`/shops/${pos.shop.id}/orders`, { query: { page_number: page, page_size: 20 }, signal: controller.signal })
      .then((res) => {
        setOrders(res.data);
        setTotal(res.total_entries);
        setLoading(false);
      })
      .catch((e) => e.name !== 'AbortError' && pos.toast.show(e.message, { tone: 'error' }));
    return () => controller.abort();
  }, [page]);

  // PosTable takes flat rows: pick the columns instead of passing API objects.
  const rows = orders.map((o) => ({ system_id: o.system_id, id: o.id, bill_full_name: o.bill_full_name ?? null, total_price: o.total_price ?? 0, inserted_at: o.inserted_at }));

  return (
    // heading and the button go to the POS title row.
    <PosPage heading="ERP reconciliation" actions={<PosButton icon="refresh" onClick={() => pos.toast.show('Syncing...', { tone: 'info' })}>Sync again</PosButton>}>
      <PosSection heading="Orders to reconcile">
        <PosTable
          rowKey="system_id"
          loading={loading}
          rows={rows}
          columns={[
            { key: 'id', title: 'Order', format: 'link' },
            { key: 'bill_full_name', title: 'Customer' },
            { key: 'total_price', title: 'Total', format: 'money', align: 'right' },
            { key: 'inserted_at', title: 'Created at', format: 'datetime' },
          ]}
          pagination={{ page, pageSize: 20, total }}
          onPageChange={(e) => setPage(e.detail.page)}
          onCellClick={(e) => pos.navigate({ resource: 'order', id: Number(e.detail.row.system_id) })}
        />
      </PosSection>
    </PosPage>
  );
}

createRoot(document.getElementById('root')!).render(
  <PosProvider>
    <Reconcile />
  </PosProvider>,
);

@pancake-pos/ui components have the names and properties of the pos-* elements (PosTable ↔ pos-table), so the iframe page looks like a POS screen while any React library still works. See Iframe page UI.

6. Bulk action on warehouse transfers

extensions/push-transfers.ts

TypeScript
// warehouse_transfer.index.selection-action: records is WarehouseTransferRef[]
export default async function ({ records }) {
  const res = await fetch('https://erp.example.com/api/stock-transfers', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(
      records.map((t) => ({
        pos_transfer_id: t.id,
        code: t.custom_id || String(t.display_id),
        from_warehouse_id: t.from_warehouse_id,
        to_warehouse_id: t.to_warehouse_id,
        status: t.status,
      }))
    ),
  });
  if (!res.ok) throw new Error(`ERP rejected the transfers (${res.status})`);
  return { message: `Pushed ${records.length} transfers to the ERP`, refresh: false };
}

The module is the same as for orders; only the resource changes: records holds WarehouseTransferRef, whose id is used with the Open API (/shops/{shop_id}/transfers/{id}). Read line items through the Open API when the ERP needs them.