Applies to api_version: "2026-01".
Every extension gets a pos object to read context, call the Open API and send commands to the POS UI.
- Extensions in the worker (blocks, actions, hooks, Worker UI pages):
posis a global preloaded by the POS runtime before the module runs. - Iframe pages:
<PosProvider>from@pancake-pos/ui(orconnect()from the SDK) gives the page itspos(see Iframe pages).
Full types ship in @pancake-pos/ui-extensions (see SDK & CLI).
Overview
interface Pos {
apiVersion: string; // for example "2026-01"
target: string; // the running extension's target
extensionId: string; // the id declared in the manifest
app: { id: string; handle: string; version: string };
shop: { id: number; name: string; currency: string; country: string; timezone: string };
user: { id: string; name: string; locale: string };
data: unknown; // context data, schema depends on the target
api: PosApi; // Open API calls
format: PosFormat; // numbers, money and dates formatted like POS screens
session: { getToken(): Promise<{ token: string; expiresAt: string }> };
toast: { show(message: string, options?: ToastOptions): void };
ui: {
confirm(options: ConfirmOptions): Promise<boolean>;
modal<T>(options: OverlayOptions): Promise<T | null>; // an iframe page of the app in a POS modal
drawer<T>(options: OverlayOptions): Promise<T | null>;
};
download(file: DownloadFile): Promise<void>;
clipboard: { copy(text: string): Promise<void> };
navigate(to: NavigateTarget): void;
refresh(): void;
close(result?: unknown): void;
on(event: PosEvent, handler: (payload: any) => void): () => void;
}Availability
| API | Block | Headless action | Modal/fullscreen action | Hook, should_render | Page |
|---|---|---|---|---|---|
shop, user, app, data |
✓ | ✓ | ✓ | ✓ | ✓ |
api, session, format |
✓ | ✓ | ✓ | ✓ | ✓ |
toast, ui.confirm, download, clipboard |
✓ | ✓ | ✓ | ✓ | |
ui.modal, ui.drawer |
✓ | ✓ | ✓ | ✓ ¹ | |
navigate |
✓ | ✓ | ✓ | ✓ | |
refresh |
✓ | ✓ | ✓ | ||
close |
✓ | ² | |||
on('data-change') |
✓ | ✓ | ✓ | ||
page.setTitle, page.setPrimaryAction, on('primary-action') |
✓ ¹ | ||||
page.setHeader, page.setFrame, page.setBackdrop, on('header-action'), on('backdrop-dismiss') |
iframe ¹ |
¹ Except a page shown in a pos.ui.modal/drawer (one level, no POS title row).
² Only an iframe page shown in a pos.ui.modal/drawer.
Calling an API outside its availability throws PosRuntimeError with code: 'unavailable'.
pos.data
The context data of the current target, also passed to the export default function. See each target's schema in Extension points.
- Targets on POS records share one shape:
pos.data.resourcenames the resource (order,purchase…),pos.data.recordis the saved record (recordsin the bulk action bar) andpos.data.draftis the detail form content. - Fields hidden by
access.hidden_order_fieldsare not present inpos.data. - For blocks,
pos.dataupdates as the user edits the form; listen todata-changeto re-render.
pos.api
Calls the Open API with the app token. The SDK attaches the token, renews it and retries once when it expires.
interface PosApi {
baseUrl: string; // Open API root, for example "https://pos.pages.fm/api/v1"
request<T = any>(options: {
method: 'GET' | 'POST' | 'PUT' | 'DELETE';
path: string; // relative to baseUrl: /shops/{shop_id}/... or /geo/...
query?: Record<string, unknown>;
body?: unknown; // sent as JSON
signal?: AbortSignal;
}): Promise<T>;
get<T = any>(path: string, options?: { query?: Record<string, unknown>; signal?: AbortSignal; cache?: number }): Promise<T>;
paginate<T = any>(path: string, options?: PaginateOptions): Promise<{ items: T[]; total: number | null; truncated: boolean }>;
post<T = any>(path: string, body?: unknown, options?: { query?: Record<string, unknown>; signal?: AbortSignal }): Promise<T>;
put<T = any>(path: string, body?: unknown, options?: { query?: Record<string, unknown>; signal?: AbortSignal }): Promise<T>;
delete<T = any>(path: string, options?: { query?: Record<string, unknown>; signal?: AbortSignal }): Promise<T>;
}pathmust belong to the current shop (/shops/${pos.shop.id}/...). Calls to other shops are rejected. The only exception is the address catalog:/geo/provinces,/geo/districts,/geo/communes.- The result is the raw Open API JSON (usually
{ success, data, ... }). - The method must be listed in the app's
access.methods; otherwise an error is thrown before the request is sent.
Caching catalogs
get(path, { cache: seconds }) keeps the result in the extension's memory (up to 3600 seconds), for catalogs that rarely change: carriers (/partners), warehouses, tags, provinces (/geo/provinces). Later calls with the same path and query send no request; each call gets its own copy, so changing a result does not affect the next one. A successful write (POST, PUT, DELETE) clears the whole cache.
const { data: partners } = await pos.api.get(`/shops/${pos.shop.id}/partners`, { cache: 600 });Loading many pages
paginate loads an Open API list over several pages, a few at a time, within the rate limit. On 429 it waits and retries (up to 3 times).
type PaginateOptions = {
query?: Record<string, unknown>; // the endpoint's filters; add fields[] to fetch only what you need
pageSize?: number; // 100 by default, at most 200
maxItems?: number; // 2,000 by default, at most 20,000
concurrency?: number; // pages loaded at once, 3 by default, at most 5
pageParam?: 'page_number' | 'page'; // both are sent by default (Open API endpoints use one or the other)
signal?: AbortSignal; // cancel when the user changes the filters
onProgress?: (progress: { loaded: number; total: number | null }) => void;
};
const controller = new AbortController();
const { items, total, truncated } = await pos.api.paginate(`/shops/${pos.shop.id}/orders`, {
query: { startDateTime, endDateTime },
maxItems: 5000,
signal: controller.signal,
onProgress: ({ loaded, total }) => setProgress(total ? (loaded / total) * 100 : 0),
});- The endpoint must return
{ data: [...] }. Withtotal_entriesortotal_pagesthe remaining pages load in parallel; without them pages load one by one until a short page. truncated: truemeans records remain aftermaxItems: ask the user to narrow the filters.- Reports over long periods stay slow because every record is downloaded; default to a short period (7 days) and show progress with
pos-progress.
Errors
class PosApiError extends Error {
status: number; // HTTP status
code?: number | string; // Open API error_code when present
body?: unknown; // response body
}The SDK throws PosApiError when the HTTP status is ≥ 400 or the body has success: false. See the error codes in Data access › Error codes.
try {
const { record } = pos.data; // order.details.action: record is an OrderRef
const res = await pos.api.get(`/shops/${pos.shop.id}/orders/${record.system_id}`);
render(<OrderInfo order={res.data} />, document.body);
} catch (error) {
if (error.status === 403) pos.toast.show('You do not have permission to view this order', { tone: 'error' });
else throw error;
}pos.session.getToken
Gets the current app token to call the Open API with another library.
const { token, expiresAt } = await pos.session.getToken();
await fetch(`${pos.api.baseUrl}/shops/${pos.shop.id}/orders`, {
headers: { Authorization: `Bearer ${token}` },
});Do not store the token long term or send it to external systems, except to the backend of a self-hosted page. Tokens expire after 15 minutes; call getToken() again for a new one.
pos.toast.show
type ToastOptions = {
tone?: 'success' | 'error' | 'info' | 'warning'; // default 'success'
duration?: number; // seconds, default 3, from 1 to 10
};At most 3 toasts per 10 seconds per extension; extra toasts are dropped.
pos.ui.confirm
A confirmation dialog drawn by POS over the whole screen.
type ConfirmOptions = {
title: string;
content?: string;
okText?: string; // defaults to the POS "OK" label
cancelText?: string; // defaults to the POS "Cancel" label
danger?: boolean; // red confirm button
};
if (await pos.ui.confirm({ title: 'Push this order to the ERP?' })) {
// ...
}pos.ui.modal, pos.ui.drawer
Opens an iframe page of the app (an app.page with render: "iframe") in a POS modal or drawer over the whole POS screen. Use it for complex screens opened from a block, an action or a page: picking products, editing delivery details, viewing a record.
type OverlayOptions = {
page?: string; // id of an app.page with render "iframe"; defaults to the first iframe page
path?: string; // path inside the page, "/" by default
query?: Record<string, string>;
title?: string; // modal title; POS adds the app name
width?: 'small' | 'medium' | 'large'; // modal 520/720/1000 px (small by default), drawer 400/560/800 px (medium by default)
};
const picked = await pos.ui.drawer<{ id: number }>({ path: '/pick-product', title: 'Pick a product', width: 'large' });
if (picked) addProduct(picked.id);- The page inside knows it is in a modal through
pos.data.presentation('modal'or'drawer') and closes with a result throughpos.close(result)(up to 256 KB). When the user clicks ×, the result isnull. - A modal is as tall as the page content (
PosProviderreports the height), up to the screen height; the rest scrolls inside the iframe. A drawer is full height. - One level: a page in a modal/drawer cannot open another one and has no
pos.page.*. Moving to another POS page closes the modal. - Not available in hooks and
should_render. Bad arguments (a path not starting with/, an unknownwidth) throwinvalid_argument; an app without any iframe page getsfailed; an app that already has a modal/drawer open getsbusy(one modal per app at a time). - A headless action waiting on a modal does not count toward its 30-second run limit.
pos.download
Downloads a file to the user's computer. Code in the worker cannot create download links, so POS downloads it for the app; iframe pages can call it the same way. Two ways:
- Table (
sheet): the app passes columns and rows, POS builds an.xlsxor.csvfile. Numbers, money, percentages and dates are formatted like POS screens, and the header row follows POS Excel exports. No Excel library needed. - Content (
content): the app builds the file itself (text or bytes).
type SheetColumn = {
key: string; // field of the row, may be a path such as customer.name
title: string;
format?: 'text' | 'number' | 'money' | 'percent' | 'date' | 'datetime' | 'badge' | 'link'; // badge and link export as text
};
type DownloadFile =
| { filename: string; sheet: { name?: string; columns: SheetColumn[]; rows: object[] } } // .xlsx, .csv
| { filename: string; content: string | ArrayBuffer | ArrayBufferView; type?: string }; // .csv, .xlsx, .json, .txt, .pdf
// Reuse the pos-table columns and the Open API records as shown.
await pos.download({ filename: 'orders.xlsx', sheet: { name: 'Orders', columns, rows: orders } });
const csv = ['Order,Customer,Total', ...rows.map((r) => [r.id, r.name, r.total].join(','))].join('\n');
await pos.download({ filename: 'orders.csv', content: csv });sheet: up to 50 columns and 20,000 rows. Object or array values leave the cell empty; text starting with=,+,-or@is written as text, never as a formula.- Up to 10 MB per file. Other types, larger files or a malformed
contentorsheetthrowPosRuntimeErrorwithcode: 'invalid_download'. - CSV files get a UTF-8 BOM so Excel reads Vietnamese correctly.
- Not available in hooks and
should_render.
pos.clipboard.copy
Copies text (tracking codes, order codes, links) to the user's clipboard. The worker cannot reach the clipboard, so POS copies it and shows "Copied."; the app does not need its own message.
await pos.clipboard.copy(order.partner.extend_code);- Up to 10,000 characters. Throws when the browser refuses (for example when the page is not focused).
- To copy a table cell, set
copyable: trueon thepos-tablecolumn instead.
pos.navigate
Navigates to one of the app's pages, or opens a POS record.
type NavigateTarget =
| { page: string; path?: string; query?: Record<string, string> } // page: id of an app.page extension
| { resource: 'order'; id: number | string }; // id: the order's system_id
pos.navigate({ page: 'home', path: '/returns', query: { order_id: String(pos.data.record.system_id) } });
pos.navigate({ resource: 'order', id: order.system_id });resourceopens the record in POS in a new tab, so the app's report or list page keeps its filters and position. Orders (order) are supported;idis the id used in the Open API path (system_id).
When called from a modal, the modal closes before navigating. If that page is already open, POS only updates the URL and emits data-change with the new path and query; the page is not reloaded.
pos.format
Formats values like POS screens for text the app builds itself (headings, descriptions, printouts). Table columns, pos-stat and pos-money are already formatted by POS from their format.
interface PosFormat {
number(value: number, digits?: number): string; // user's language, up to 2 decimals: 1,234.5
percent(value: number, digits?: number): string; // 12.5 → "12.5%"
money(value: number): string; // shop currency: "916.460 ₫", "$ 12,345.67"
date(value: string | number | Date): string; // "01/10/2026"
datetime(value: string | number | Date): string; // "01/10/2026 08:05", user's local time
}
pos.toast.show(`Reconciled ${pos.format.number(count)} orders, ${pos.format.money(diff)} off`);moneytakes the value as the Open API returns it and follows POS currency rules (symbol, decimal mark; currencies with cents such as USD and theVND100,PHP100codes are stored in hundredths).pos.shop.currencycan beVND100orPHP100: POS-internal codes for dong and peso kept to 2 decimals, not ISO 4217. When you need the ISO code (external services), drop the100suffix and divide amounts by 100.datetakesYYYY-MM-DD(a calendar day, no time zone shift), an ISO string, milliseconds or aDate. Invalid values return''.
pos.refresh
Asks POS to reload the data of the current screen (for example the open order or purchase) after the app updated it through the Open API.
- POS reloads the list on screen and the open record. Unsaved changes in that record's form are replaced by the new data.
- Repeated calls are merged: each resource reloads at most once every 3 seconds.
pos.close
Closes the open modal/fullscreen action. An iframe page shown in a pos.ui.modal modal or drawer passes a result back to its opener: pos.close({ id: 5 }).
Events
const off = pos.on('data-change', (data) => {
// data has the same schema as pos.data
});
off(); // unsubscribe| Event | Fires when | Payload |
|---|---|---|
data-change |
Context data changes, for example the user edits a detail form (batched over 300 ms) or a page's path changes | the new pos.data |
primary-action |
The user clicks the page's primary button (iframe or Worker UI) | none |
header-action |
The user clicks a button an iframe page set with pos.page.setHeader |
{ id, item? } (item: the chosen entry of a menu button) |
backdrop-dismiss |
The user clicks the dimmed POS area or presses Esc while an iframe page has pos.page.setBackdrop on |
{ via: 'click' | 'escape' } |
Worker UI pages
A render: "worker" page runs in a worker like a block: it uses the global pos and pos-* elements (see Components › Worker UI pages). pos.page is available on Worker UI pages as on iframe pages:
pos.page.setTitle('Reconciliation 12/05');
pos.page.setPrimaryAction({ label: 'Export Excel', loading: false });
pos.on('primary-action', exportExcel);A pos-page heading, when set, replaces the setTitle title on the title row; setTitle still sets the browser tab title.
In TypeScript pos.page is optional because only pages have it; in a page module use pos.page! or (pos as PosPage).page.
Iframe pages
A render: "iframe" page is a regular web app served from the root of the app's sandbox domain. Every path that is not a static file returns index.html, so routers use / as their basename. Paths starting with /_pos/ are reserved for POS: do not use them as routes or file paths.
The recommended way is @pancake-pos/ui: <PosProvider> connects to POS and applies the theme, font and frame, then usePos() returns pos. Without React, call connect():
import { connect } from '@pancake-pos/ui-extensions/page';
const pos = await connect(); // waits for POS to send context and token
// pos.data: { path, query, presentation? }On top of the APIs above, iframe pages get:
interface PosPage {
setTitle(title: string): void;
setPrimaryAction(action: { label: string; disabled?: boolean; loading?: boolean } | null): void;
setHeader(header: { heading?: string; description?: string; actions?: HeaderAction[] } | null): Promise<boolean>;
setFrame(frame: { background: 'none' | 'card' }): Promise<boolean>; // false: POS does not support it yet
setBackdrop(on: boolean): Promise<boolean>;
}
type HeaderAction = {
id: string;
label?: string; // up to 40 characters; a button needs a label or an icon
icon?: string; // same icons as pos-button
variant?: 'primary' | 'secondary' | 'tertiary' | 'danger';
tooltip?: string;
disabled?: boolean;
loading?: boolean;
items?: { id: string; label: string; danger?: boolean; disabled?: boolean }[]; // with items: a menu button
};
pos.page.setHeader({ heading: 'Debts', description: 'By customer', actions: [{ id: 'export', label: 'Export', icon: 'download' }] });
pos.on('header-action', ({ id, item }) => id === 'export' && exportExcel());
pos.page.setFrame({ background: 'none' });- Title row:
setHeadersets the heading, description and up to 5 buttons on the POS title row (next to thesetPrimaryActionbutton), drawn likepos-pagebuttons. Clicking a button firesheader-action.headingwins oversetTitle;nullrestores the default title. Buttons with neitherlabelnoricon, or with a duplicateid, are dropped. It returnsfalsewhen the POS version does not support it yet: the page then draws its own title (PosProviderdoes this for you).PosPagefrom@pancake-pos/uicallssetHeaderfor you withheading,descriptionand the buttons inactions. - Frame: by default the page sits in a white rounded card.
setFrame({ background: 'none' })removes the card so the page draws on the gray POS background like a Worker UI page (PosProvidercalls it;<PosProvider frame="card">keeps the card). - Backdrop: a modal or drawer drawn in the page only covers the iframe. Call
setBackdrop(true)when it opens andsetBackdrop(false)when it closes: POS dims everything around the iframe (title row, menu, top bar), and clicking the dimmed area or pressing Esc firesbackdrop-dismissso the page closes the top-most one. If the page keeps the backdrop on after the first click, the second click makes POS remove it.PosModal,PosDrawerandusePosBackdropfrom@pancake-pos/uicall it for you. It returnsfalsewhen the POS version does not support it yet. - URL sync: the SDK watches
history.pushState,replaceStateandpopstateinside the iframe and updates the POS URL. When a shared link is opened, the iframe loads the matching path. - Height: the iframe fills the POS content area; the page scrolls internally. In a
pos.ui.modalmodal, the modal follows the page height. - Modals and drawers: a page opened with
pos.ui.modal/drawergetspos.data.presentationand closes withpos.close(result). - Look and feel: use
@pancake-pos/ui: components with the names and properties of thepos-*elements, plus the POS theme, font and tokens.pos-app checkwarns about other UI libraries, colors outside the POS palette and hand-formatted money. - Storage: the iframe page's
localStoragebelongs to the app's sandbox domain only and is not shared with POS or other apps.
Self-hosted pages
Declare url instead of entry when the page already runs on your own server, such as an existing ERP web app. POS embeds url directly in the iframe; the bundle does not need a page/ folder.
{ "target": "app.page", "id": "home", "title": "ERP", "render": "iframe", "url": "https://erp.example.com/pos" }- Connecting: install
@pancake-pos/ui(<PosProvider>) or@pancake-pos/ui-extensions(connect()) as a bundled page does;pos.page,pos.api,pos.toastand the rest work the same way. - Opening it outside POS:
<PosProvider standalone>still renders the page when it is opened directly in a browser (no POS) andusePosOptional()returnsnull; without React,connect({ optional: true })returnsnullinstead of failing andisEmbedded()tells whether the page sits inside another window. - Paths: the path part of
urlis the app root./shop/<id>/apps/<handle>/orders/5in POS maps tohttps://erp.example.com/pos/orders/5. When the page leaves that root (for example/login), the POS URL stays as it is.pos.data.pathis the page's real path. - Allowing POS to embed it: send
Content-Security-Policy: frame-ancestors https://pos.pancake.vn https://pos.pages.fmso only POS can embed the page. Do not rely on the page's own sign-in cookies: browsers may block cookies in cross-site iframes (Safari does by default). - Calling the API from your server: send the app token (
pos.session.getToken()) with requests to your backend, and have the backend call the Open API with it (Authorization: Bearer). The token lasts 15 minutes and carries only the app's access; do not store it long term. - Review and changes: admins see
urlwhen they activate a version. Your server decides what the page shows and can change it at any time without a new version, so only use servers you control. - Trying it out:
pos-app dev --page-url http://localhost:3000/posreplacesurlwith a server on your machine; Vite or Next hot reload keeps working inside the iframe.
Worker environment
Extensions in the worker can only rely on:
- Standard JavaScript syntax and built-ins (ES2020).
fetch,Headers,Request,Response,AbortController,URL,URLSearchParams.setTimeout,clearTimeout,setInterval,clearInterval.console(only visible in development mode).- The minimal DOM provided by the POS runtime so Preact or plain JS can build
pos-*elements:document.createElement,document.createTextNode,append,appendChild,insertBefore,removeChild,remove,setAttribute,removeAttribute,textContent,addEventListener,removeEventListener,parentNode,childNodes,firstChild,nextSibling,CustomEvent.document.bodyis the root of the extension's UI.
Do not use window, document.querySelector, localStorage, sessionStorage, canvas, DOM measurement (getBoundingClientRect…), alert/confirm/prompt, or load scripts from CDNs. These may not exist or may be locked down at any time.
Error log
- Development mode: errors and
console.*show up in the browser DevTools; POS errors and warnings are available through theget_errorstool of the MCP. POS also checks the running screen against Standard screens and recordsstandard_screenwarnings (emoji in labels, sections holding only a number, tables with too many columns…), including dynamic data thatpos-app checkcannot see. - A property with the wrong type or an element in the wrong place does not stop the extension: POS drops that property (the default applies) or does not draw that element, and records an
invalid_prop,invalid_childorinvalid_slotwarning. Numbers are turned into strings where a string is expected (for exampleselectedofpos-tabs);nullor''count as not set. - Active version: uncaught errors, render errors and timeouts are recorded in the app's error log, visible in the error log on the custom apps page.
