Extension points

An extension point (target) is a place POS exposes for apps. Each target defines where it is shown, how it is presented, what context data the module receives and what it must return.

#Naming

Targets attached to a POS record are named <resource>.<location>, for example order.details.action or purchase.index.selection-action. Resources share the same location names, so an app written for orders works the same way for purchases or warehouse transfers. Some locations do not exist for every resource: products have no print templates (print-action), and customers only have boxes, actions and columns (see customer.*).

#Target list

<resource> is one of order, product, purchase, export, warehouse_transfer. Products have no print-action because they only print barcodes.

#Module convention

Every module is an ES module with a function as its export default. The function receives the context data (same as pos.data) and may be async.

// Extensions with UI (block, modal/fullscreen action, Worker UI page): render into document.body
export default async function (data) {
  render(<App data={data} />, document.body);
}

// Headless extensions and hooks: return the result expected by the target
export default async function (data) {
  return { message: 'Done' };
}

#Shared types

Context data has the same shape for every resource: data.resource names the resource, data.record is the saved record (data.records in the bulk action bar) and data.draft is what the detail form currently shows.

type Resource = 'order' | 'product' | 'purchase' | 'export' | 'warehouse_transfer';

type RefOf<R extends Resource> = {
  order: OrderRef;
  product: ProductRef;
  purchase: PurchaseRef;
  export: ExportRef;
  warehouse_transfer: WarehouseTransferRef;
}[R];

type DraftOf<R extends Resource> = {
  order: OrderDraft;
  product: ProductDraft;
  purchase: PurchaseDraft;
  export: ExportDraft;
  warehouse_transfer: WarehouseTransferDraft;
}[R];

// Detail form: *.details.action, *.details.block, *.before_submit
type DetailsData<R extends Resource> = {
  resource: R;
  mode: 'create' | 'edit';
  record: RefOf<R> | null;   // null while the record is unsaved
  draft: DraftOf<R>;         // includes unsaved changes
};

// One list row: *.index.action
type IndexData<R extends Resource> = {
  resource: R;
  record: RefOf<R>;
};

// Bulk action bar: *.index.selection-action
type SelectionData<R extends Resource> = {
  resource: R;
  records: RefOf<R>[];       // up to 500 records
};

Example pos.data in purchase.details.action:

{
  "resource": "purchase",
  "mode": "edit",
  "record": { "id": "7c1d…", "display_id": 318, "custom_id": null, "status": 0, "warehouse_id": "a52f…", "updated_at": "2026-10-06T02:45:00" },
  "draft": { "status": 0, "warehouse_id": "a52f…", "supplier_products_id": "e09b…", "tags": [], "note": null, "items": [{ "variation_id": "41aa…", "quantity": 20, "imported_price": 1850000 }], "total_price": 37000000 }
}

#Record id

#Types per resource

type OrderRef = {
  id: string | number;      // displayed order id (the custom id if the shop uses one, otherwise the system id)
  system_id: number;        // system order id, as the order's system_id field in the Open API: /shops/{shop_id}/orders/{system_id}
  status: number;
  updated_at: string;       // ISO 8601
};

type OrderDraft = {
  status: number;
  customer_id: string | null;
  bill_full_name: string | null;
  bill_phone_number: string | null;
  warehouse_id: string | null;
  tags: (number | string)[];
  note: string | null;
  items: {
    variation_id: string;
    product_id: string;
    quantity: number;
    price: number;          // unit price after line discount
  }[];
  total_price: number;
};

type ProductRef = {
  id: string;               // UUID: /shops/{shop_id}/products/{id}
  display_id: number;
  custom_id: string | null; // product code
  name: string;
  is_hide: boolean;
  updated_at: string;
};

type ProductDraft = {
  name: string;
  custom_id: string | null;
  category_ids: number[];
  brand_id: number | null;
  tags: (number | string)[];
  variations: {
    id: string | null;      // null for a variation not saved yet
    custom_id: string | null;
    barcode: string | null;
    retail_price: number;
  }[];
};

type PurchaseRef = {
  id: string;               // UUID: /shops/{shop_id}/purchases/{id}
  display_id: number;
  custom_id: string | null;
  status: number;
  warehouse_id: string;
  updated_at: string;
};

type PurchaseDraft = {
  status: number;
  warehouse_id: string | null;
  supplier_products_id: string | null;   // supplier
  tags: (number | string)[];
  note: string | null;
  items: {
    variation_id: string;
    quantity: number;
    imported_price: number;
  }[];
  total_price: number;
};

type ExportRef = {
  id: string;               // UUID: /shops/{shop_id}/export/{id}
  display_id: number;
  custom_id: string | null;
  status: number;
  type: number;             // export type as in the Open API (normal, defective goods…)
  warehouse_id: string;
  updated_at: string;
};

type ExportDraft = {
  status: number;
  type: number;
  warehouse_id: string | null;
  tags: (number | string)[];
  note: string | null;
  export_items: {
    variation_id: string;
    quantity: number;
  }[];
};

type WarehouseTransferRef = {
  id: string;               // UUID: /shops/{shop_id}/transfers/{id}
  display_id: number;
  custom_id: string | null;
  status: number;
  from_warehouse_id: string;
  to_warehouse_id: string;
  updated_status_at: string;
};

type WarehouseTransferDraft = {
  status: number;
  from_warehouse_id: string | null;
  to_warehouse_id: string | null;
  note: string | null;
  items: {
    variation_id: string;
    quantity: number;
  }[];
};

• Field names and status codes follow the Open API. Fields the user may not see (for example the imported price without the matching permission) are left out, and fields listed in access.hidden_order_fields are removed from OrderDraft (their value becomes undefined).
• Context data only includes the minimum fields. Call the Open API with pos.api when you need more (see Runtime API).
• If a record does not satisfy the app's access limits (warehouse, product category, order source…), POS does not show the extension for that record.

#nav.item

Adds an item to the main menu that opens an app.page.

No module. The item is only shown to people who can see the app (every shop member by default, see App lifecycle).

#app.page

The app's own page.

Context data:

type PageData = {
  path: string;                     // the part after /apps/<handle>, for example "/returns"
  query: Record<string, string>;    // the POS URL query string
};

• Iframe pages: the URL is synced both ways; when the app changes its internal route the POS URL follows, so reloads, the back button and shared links all work. The page connects to POS through the SDK, see Runtime API › Iframe pages.
• Worker UI pages: the worker has no history. Change the path with pos.navigate({ page, path, query }); POS updates the URL and emits data-change with the new path and query without recreating the worker. The browser back button also emits data-change.
• Build Worker UI pages with pos-page, pos-tabs, pos-filter-bar, pos-chart and the other elements (see Components). Set the title and primary button on the POS title bar with pos.page, as on iframe pages (see Runtime API › Worker UI pages).

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

function Report() {
  const [tab, setTab] = useState(pos.data.query.tab || 'day');
  useEffect(() => pos.on('data-change', (data) => setTab(data.query.tab || 'day')), []);
  return (
    <pos-page heading="Revenue" width="full">
      <pos-tabs tabs={[{ id: 'day', label: 'By day' }, { id: 'source', label: 'By source' }]} selected={tab} onChange={(e) => pos.navigate({ page: 'report', query: { tab: e.detail } })}>
        <pos-chart type={tab == 'day' ? 'line' : 'pie'} xKey="label" data={[{ label: '01/10', revenue: 12500000 }]} series={[{ key: 'revenue', label: 'Revenue', format: 'money' }]} />
      </pos-tabs>
    </pos-page>
  );
}

export default function () {
  pos.page?.setTitle('Revenue report');
  render(<Report />, document.body);
}

#*.details.action

Adds an item to the action menu of a detail form. App items sit in an "Apps" group at the bottom of the menu, in declaration order.

Context data: DetailsData<R>.

For orders, app items are not shown when the menu is in print-only mode or actions are hidden.

#Action types

For headless:

• If it returns message, POS shows a success toast with that text.
• If it throws (throw new Error('...')), POS shows an error toast with error.message.
• refresh defaults to true: POS reloads the record when the module finishes.
• Maximum run time is 30 seconds; after that the worker is stopped and an error is reported.

The videos below use orders; other resources behave the same way.

#should_render

The should_render module receives the same context data and returns a boolean.

• POS evaluates it ahead of time when the record loads or changes, caching the result by record id and its update time (updated_status_at for warehouse transfers).
• Timeout is 300 ms; on timeout or error the item is hidden.
• Prefer conditions in the manifest; only use should_render for complex conditions.

#*.index.action

Like *.details.action, but on each row of the list.

Context data: IndexData<R>.

#*.index.selection-action

An item on the action bar shown when several records are selected in the list.

Context data: SelectionData<R>. With navigate, the query contains every id, for example purchase_ids=<id>,<id>,....

#*.details.block

A box inside the detail form.

• Context data: DetailsData<R> (same as *.details.action).
• When the user edits the form, POS updates pos.data and emits a data-change event (see Runtime API › Events).
• The box is as wide as its column; its height grows with its content.
• The box never blocks the form: POS shows a skeleton while the worker starts.

#*.after_save

Runs after a record is successfully created or updated on its detail form in POS web.

type AfterSaveInput<R extends Resource> = {
  resource: R;
  mode: 'create' | 'edit';
  record: RefOf<R>;
};

• Does not block the user; the return value is ignored.
• Errors only go to the app's error log and are not shown to the user.

#*.before_submit

Runs before a record is created or updated on its detail form in POS web.

type BeforeSubmitInput<R extends Resource> = DetailsData<R>;

type BeforeSubmitResult =
  | { ok: true; changes?: BeforeSubmitChanges }
  | { ok: false; message: string };   // message up to 200 characters, shown to the user

type BeforeSubmitChanges = {
  note?: string;                      // replaces the note, up to 2,000 characters
  add_tags?: (number | string)[];     // adds tags by the shop's tag ids, up to 20
};

• Hooks from several apps run in parallel. If any hook returns ok: false, the record is not saved; POS shows every message.
• When timeout_ms is exceeded or the module fails, on_error decides (allow saves, block stops the save).
• changes can only set the note and add tags. POS applies them to the form before saving and tells the user which app changed the record.

• Fields the resource does not have are ignored. Tag ids the shop does not have, or that are already set, are ignored. Get tag ids from the Open API or the MCP list_shop_meta tool.
• If two apps return different note values, POS stops the save and reports the conflict. Tags from several apps are combined.
• An invalid changes value is handled like a failing module (by on_error).

export default defineExtension('order.before_submit', async (data) => {
  if (data.draft.total_price < 20_000_000) return { ok: true };
  return { ok: true, changes: { add_tags: [12], note: `${data.draft.note ?? ''}\nLarge order: check before shipping`.trim() } };
});

#When hooks run

*.before_submit and *.after_save only run when the user saves on the detail form in POS web. They do not run for changes made elsewhere: the status menu on list rows, bulk updates, Excel import, the Open API, the mobile app or marketplace sync. Rules that must always hold belong on the server.

#customer.*

Customers have boxes, actions and columns like the other resources, but no before_submit, after_save (the profile saves each field as soon as it changes; there is no shared Save button) and no print templates.

The profile has the box and the actions wherever it opens: the Customers page, the order form and other screens. When the customer list is filtered to deleted customers, app actions and columns are hidden.

type CustomerRef = {
  id: string;                       // use with the Open API: /shops/{shop_id}/customers/{id}
  name: string;
  phone_numbers: string[];
  tags: (number | string)[];
  level_id: string | null;
  assigned_user_id: string | null;
  updated_at: string | null;
};

type CustomerData = { resource: 'customer'; record: CustomerRef };   // same shape as IndexData<'customer'>

• Manifest: the same fields as the target at the same location for other resources (*.details.action, *.details.block, *.index.column…). Customer targets have no conditions; use should_render to hide by data.
• refresh of a headless action and pos.refresh() reload the customer list page being viewed; a profile opened from the list gets the new data. A profile opened from the order form or other screens does not reload yet.
• navigate adds customer_id or customer_ids to the query.
• When the customer is edited in the profile, the box receives data-change with the new data.
• As with *.details.block, the box's worker starts when the box scrolls into view; POS shows a placeholder meanwhile.

#*.print-action

The app's print template in the "Print template" picker; users pick it like any other template. The module returns HTML, POS cleans it and opens the browser's print dialog.

Products only print barcodes, so they have no such target.

type PrintResource = 'order' | 'purchase' | 'export' | 'warehouse_transfer';
type PrintData<R extends PrintResource> = { resource: R; records: RefOf<R>[] };   // 1–500 records
type PrintResult = { html: string; title?: string };                             // html up to 2 MB

• Runs like a headless action: up to 30 seconds, may use pos.api and pos.toast. On errors or an invalid result POS reports that printing failed and writes the app's error log.
• Records outside the app's access limits are not sent to the module. Printing with an app template does not increase the order's print count.
• The context data only has ids and summary fields (RefOf<R>); fetch lines, customers or amounts from the Open API by record id.
• The HTML is cleaned before printing: script, event attributes (onclick…), iframe, form, link and meta are removed, and the print runs in an iframe without scripts. Use <style> or style="…" for layout, @page for the paper size and break-after: page for page breaks.
• Images follow the pos-image rules: data:image/…;base64,…, public/<file name> in the bundle, or an https:// URL in network.allowed_origins. Other images, fonts and external CSS are blocked. Draw barcodes and QR codes as SVG or data: images.

export default defineExtension('purchase.print-action', async ({ records }) => {
  const details = await Promise.all(records.map((purchase) => pos.api.get(`/shops/${pos.shop.id}/purchases/${purchase.id}`)));
  const pages = details.map(({ data }) => `<section class="slip"><h1>Purchase ${data.display_id}</h1><p>${data.items.length} lines</p></section>`);
  return {
    title: 'ERP purchase slips',
    html: `<style>@page { size: A5; margin: 8mm } .slip { break-after: page }</style>${pages.join('')}`,
  };
});

#*.index.column

The app's column in a list, placed before the fixed right column (Status) or at the end of the table. Available for all 5 resources and for customers. POS calls the module once for the records shown on the page, not once per row.

type ColumnData<R extends Resource> = { resource: R; records: RefOf<R>[] };       // records on the page, up to 500
type ColumnResult = { values: Record<string, string | number | null> };         // keyed by record id

values is keyed by the id used with the Open API (see Record id): system_id for orders, id for the other resources.

• Runs like a hook: 5-second timeout, only pos.api is available. Batch Open API calls with Promise.all or use list endpoints.
• Results are remembered per record and update time: when the list reloads (page change, socket updates) the module only runs for new or changed records.
• Records missing from values, records outside the access limits and failed runs leave the cell empty. Strings longer than 200 characters are cut.
• App columns are always shown; they are not part of the list's column settings yet.

export default defineExtension('order.index.column', async ({ records }) => {
  const ids = records.map((order) => order.system_id).join(',');
  const response = await fetch(`https://erp.example.com/pos-orders?ids=${ids}`);
  const erp: Record<string, string> = await response.json();
  return { values: erp };
});