Building on it
Catalog layout on devices
A merchant decides what appears where; the terminal (and the desk screen) just draw it.
| What | Where it's set | What the device receives |
|---|---|---|
| Category order (first = leftmost tab) | Console → Catalog → Categories (arrows), or PUT /v1/merchants/{id}/categories/order {ids} |
GET /v1/terminal/categories → [{id, name, sortOrder, color}], active and inactive (hide inactive ones) |
Category colour (#RRGGBB, optional) |
Same screen, or PUT .../categories/{id} {color} (empty string clears) |
color on the category |
| Product order | Console → Catalog → Device layout (Earlier / Later), or PUT .../products/order {ids} |
productSort on every catalog item (lowest first) |
| Favourites | "Pin as favourite" in the layout view, or PUT .../products/{id} {isFavourite} |
favourite: true on the item |
Drawing it#
- Sync the catalog as usual (
GET /v1/terminal/catalog, delta by cursor). Each item hascategoryId,productSortandfavourite. - Fetch
/v1/terminal/categorieson every sync. It is small, and category changes (rename, colour, order, hide) do not appear in the item feed. - Build the tabs: a Favourites tab first if any item is
favourite, then the active categories bysortOrder, then an Other tab if any item has no (or an inactive) category. - Inside a tab, sort items by
productSort, then name.
Reordering or pinning a product touches every variant of it, so terminals pick it up in their next delta. The console's Device layout preview (POS terminal and Desk) draws exactly these rules.
Positions are relative: reordering a few products reuses the positions they already held, so products you did not touch stay where they were.