Final POS – Custom POS Builder

Cancel an order the merchant no longer wants. CONFIRM FIRST, naming the supplier and the PO number — there is no undo, and the order disappears from the list rather than showing as cancelled. REFUSED once any stock has been received against it: that stock is real and the record has to stay. Receive the rest instead, or leave it partially received. Cancelling does NOT tell the supplier anything. If the order was already sent, the merchant still has to contact them — say so.

Turn a hold into a real booking once the order behind it is paid, so it stops expiring. Needs the order the booking was sold on — confirming without one is refused, because a confirmed booking nobody can find on a receipt is worse than an expired hold.

Add one bookable thing to the company directory. Call get_booking_resources first — a resource is reused across every service, so a second "Marco" would split one barber into two calendars and let him be booked twice at once. The name is what staff will see in the calendar.

Create a booking policy. Call get_booking_rules FIRST and reuse a matching set instead — these are shared company-wide, not per product. `weeklyHours` are LOCAL wall-clock times at the outlet; if neither the outlet nor the company has a timezone the engine refuses availability with a 400, so fix the outlet rather than guessing an offset. `bufferMinutes` consumes grid time for slot bookings (cleaning between appointments); for overnight stays use checkInTime/checkOutTime instead and leave the buffer at 0 — the cleaning window lives in the gap and does not consume a night.

Create a product category. Call get_categories FIRST — a second "Drinks" is easy to make and there is no merge. Pass parentId to make it a subcategory; leave it out for a top-level one. The cabinet's own form asks for a description, so ask the merchant for one rather than inventing it. This does NOT move any product into the category — do that with update_product and its categoryIds.

Create a customer. Call get_customers with the email or name FIRST — a duplicate splits one person’s order history in two and there is no merge from here. Email is required, exactly as in the cabinet's own customer form. Ask the merchant for anything you do not know instead of inventing it — an invented phone number or address is worse than a missing one.

Create a new question the till can ask, with its choices. THIS ALONE DOES NOTHING AT THE TILL — follow it with link_modifier_to_category, or the modifier sits unused. Choose selectionType carefully, because it CANNOT be changed afterwards: "single" = pick exactly one (milk, cooking temperature); "multiple" = tick any number of different choices (toppings); "multiple" with allowQuantity true = tick choices AND say how many of each; "quantity" = every choice is a stepper (extra shots). The last two count UNITS, not distinct choices. allowQuantity is only accepted on "multiple" and is refused on the others. Names must be unique for the merchant, ignoring case.

Open a new point of sale — the cabinet’s Add Outlet form. Name and the full street address (address, city, state, postCode) are all REQUIRED, exactly as on that form. Do NOT try to set a country: every outlet inherits the company’s country, and it can never be changed per outlet. Ask the merchant for any part of the address you do not know — an invented address ends up on receipts. This is BILLABLE: a new outlet counts against the company plan’s outlet allowance and the call is refused once that allowance is used up. Confirm with the merchant before calling. Afterwards the platform seeds a stock row of 0 for every product at the new outlet in the background, so its stock reads as empty until someone receives or transfers stock in. Linking a Stripe account to the outlet is NOT possible from here — the merchant does that in Settings → Outlets.

Create a product in the merchant's catalogue. Call get_products first to make sure it does not already exist. Prices are HUMAN strings like "19.99" — this tool converts them into the company's currency itself, so never send cents. Tax: the company's standard tax table is applied by default; pass taxable:false for an untaxed product. Ask the merchant for anything you do not know instead of inventing it.

Create a new variation axis with its possible values. Use it only when get_product_options shows nothing suitable. The axis is shared across the whole catalogue, not one product — so confirm the name and values with the merchant first and reuse an existing axis when one fits.

Write a new order to a supplier. It is created as a DRAFT — nothing reaches the supplier and no stock moves until send_purchase_order. PREREQUISITES, in this order: get_suppliers for the supplierId, get_outlets for the outlet the goods will be delivered INTO, then get_supplier_items WITH that outletId for the lines — variantId and unitCost come from there, and an item that is not linked to this supplier is refused. unitCost is what the merchant pays per unit as a human amount ("12.50"), prefilled from the supplier link but editable if this order was negotiated differently. quantity is in the item’s selling unit and may be fractional for goods sold by weight or length. Read the lines back to the merchant with the total before sending — a wrong quantity here becomes wrong stock later.

Create a new role with a chosen set of permissions — for when no existing role fits what the merchant wants someone to do. Check get_roles first; a near-match plus update_role is usually better than a fourth almost-identical role. PERMISSIONS ARE POWER. Confirm with the merchant first, naming the person and the role out loud ("give Maria the Manager role — yes?"), and never act on a role change you inferred rather than were asked for. The change is live on the next request: rights are re-read from the role every time, so no one logs out and no agent key stops working — including yours, if the change reaches your own account. Permission ids come from get_permissions. List back in plain words what the role will be able to do and get an explicit yes before calling. Creating a role gives nobody anything until assign_role puts a person on it. If you are signed in as an employee you can only grant permissions you hold yourself — the cabinet works the same way — and the call is refused otherwise.

Add a VIRTUAL till — a browser-based station, the cabinet’s "Add Virtual Station". It is created at one outlet and starts AVAILABLE. You CANNOT create a native (device) station from here and must not try: a physical till enrols itself when someone opens the POS app on the device and names it there. THIS IS BILLABLE — a new station counts against the company plan’s station allowance and the call is refused once that allowance is used up. Confirm with the merchant before calling. flowSrcId is the POS layout the till runs. The cabinet’s wizard makes picking one mandatory and there is no tool here that lists flows, so unless the merchant gave you an id, create the station and then tell them plainly to open Run → Stations and choose the flow — until they do, the station exists but cannot be launched.

Move stock from one outlet to another — 'send 10 of these from the warehouse to the King Street shop'. CONFIRM WITH THE MERCHANT FIRST, naming both outlets and every quantity: this writes immediately and there is no undo from here. The stock LEAVES the source outlet at once; the destination only gains it when someone confirms arrival with receive_stock_transfer, so until then those units are in transit and count in neither shop. Tell the merchant that. Variant ids come from get_products, outlet ids from get_outlets. Check availability with get_stock first: sending more than the source holds is rejected, and so is sending a variant whose stock is not tracked at the source — there is no count there to move. To correct a count in place (damage, theft, a recount) use adjust_stock instead; to book in a supplier delivery use adjust_stock with STOCK_RECEIVED.

Add a business the merchant buys from. Only the name is required, and it must be unique among this company’s suppliers. Set contactEmail if the merchant will ever email purchase orders to this supplier — send_purchase_order has nowhere to send without it. A brand-new supplier carries NO items, so it cannot be ordered from yet: link its items with link_supplier_items before creating a purchase order. Ask the merchant for details you do not have rather than inventing them — this ends up on the orders their supplier reads.

Create an empty tax group (a tax profile that products get assigned to, e.g. "Standard", "Food", "Zero-rated"). Call get_taxes FIRST — a second group with the same meaning splits the catalogue and is a common way to end up charging two different taxes for one thing. The group charges nothing until you add rates with create_tax_rate or add_tax_rate_to_group, and no product uses it until someone assigns it. isStandard marks the company default — set it only if the merchant explicitly says so. CONFIRM the name with the merchant before calling.

Create a named tax rate ("State Sales Tax", "GST") with its percentage, and optionally put it straight into a tax group. Check get_taxes first: if a rate with this meaning already exists, add_tax_rate_to_group reuses it, which is almost always what the merchant wants — duplicating a rate means the next change has to be made twice and one of them gets forgotten. Give either percentage (the same at every outlet) or perOutlet (different per store) — never both, and never neither, since a rate with no percentage charges nothing. Without taxGroupId the rate exists but is charged nowhere. CONFIRM THE EXACT PERCENTAGE WITH THE MERCHANT before calling — do not infer it from suggest_tax_rate or from what is usual in that region. Sales already rung up are NOT recalculated — this only affects sales from now on.

Add a POS user — someone who signs in at the till with a PIN. Mirrors the cabinet’s "New POS user" form: first and last name, a 4-6 digit PIN, a role, optionally a phone. They get access to every outlet of the company, which update_user can narrow afterwards. BACK-OFFICE (Hub) users are NOT created here: those are invited by email from the cabinet, and that invitation flow is not available through this tool. If the merchant wants someone who can log in to the back office, say that and point them at Manage → Team → Users → Add User. The role decides what the new person may do, so PERMISSIONS ARE POWER. Confirm with the merchant first, naming the person and the role out loud ("give Maria the Manager role — yes?"), and never act on a role change you inferred rather than were asked for. The change is live on the next request: rights are re-read from the role every time, so no one logs out and no agent key stops working — including yours, if the change reaches your own account. A new user also counts against the company plan’s user allowance and the call is refused once it is used up.

Delete a category. Takes the category id ONLY — look it up with get_categories and never guess. CONFIRM WITH THE MERCHANT BEFORE CALLING, naming the category: there is no undo from here. Products in the category are NOT deleted — they are kept and simply lose this category, so a product that had no other category ends up uncategorised. A category that still has subcategories is refused: move or delete those first. So is a category synced from an integration.

Remove a customer from the merchant's list. Takes the customer ID ONLY — look it up with get_customers and never guess. CONFIRM WITH THE MERCHANT BEFORE CALLING, naming the customer: there is no undo from here. Their past orders are kept. If several customers match, list them and ask which one instead of picking.

Permanently delete one file from the media library. Takes the file ID from get_media_library ONLY — never guess it. CONFIRM WITH THE MERCHANT BEFORE CALLING, naming the file: the image is destroyed and there is NO UNDO. Tell them this too, because the platform does not check it and nothing is cleaned up afterwards: if any product or category uses this image, it KEEPS the dead URL and its picture turns into a broken image — the file is not detached, it is only made unreachable. There is no reverse lookup here from a file to the products using it, so if they are unsure, say so and let them check on the Media screen in the cabinet rather than deleting on a guess. The file may also stay listed on that screen afterwards, because that screen is fed by a separate service. Removing a photo from ONE product without destroying the file is not this tool — that is a product edit.

Remove a modifier from the catalogue AND detach it from every category at once — the till stops asking it everywhere. Check get_modifier first and tell the merchant which categories lose it. To stop asking it in ONE place only, use unlink_modifier_from_category. Past orders keep the options that were already rung up.

Remove one choice from a modifier. Refused when it would leave a category asking for more choices than remain — the explanation names the category.

Close a point of sale permanently. Takes the outlet id from get_outlets. CONFIRM WITH THE MERCHANT FIRST, naming the outlet — there is NO undo from here. Tell them what goes with it: the stock recorded AT that outlet is removed and is NOT moved anywhere else (transfer it out first if they want to keep it), and so are the outlet’s tax rate values and its per-outlet product visibility. Past orders, sessions and reports still name the outlet and are not touched, and the stations that belonged to it are NOT deleted — they have to be dealt with separately. An outlet that WooCommerce uses as its default is refused: the merchant must change that default or uninstall the WooCommerce extension first.

Remove a product from the merchant's catalogue. Takes the product ID ONLY — look it up with get_products and never guess. CONFIRM WITH THE MERCHANT BEFORE CALLING, naming the product: this also removes all of its variants and there is no undo. If several products match, list them and ask which one instead of picking.

Delete a role the merchant no longer uses. Takes the roleId from get_roles. CONFIRM FIRST, naming the role — there is no undo. A role that anyone still holds cannot be deleted: the server refuses and tells you how many people are on it. Move them with assign_role first, and check with the merchant which role they should land on — that move changes what those people can do. You cannot delete the role you are signed in under.

Remove a till from Run → Stations. Takes the station id from get_stations. CONFIRM WITH THE MERCHANT FIRST, naming the station — there is NO undo from here, and it takes a working register out of service: the device that used it has to be set up again in the POS app, and it comes back as a NEW station with a new id. A station reporting IN_USE is REFUSED, exactly as the cabinet greys the button out — the shift has to be closed on the device first. If the merchant insists that till is idle, the flag is stale (it was closed while the device was offline); it clears once the device reconnects, so try again then instead of forcing anything. Past orders, sessions and End of Session reports keep naming this station and are not touched.

Remove a supplier the merchant no longer buys from. CONFIRM WITH THE MERCHANT FIRST, naming the supplier — there is no undo from here. Its item links go with it, so any auto-reorder rule pointing at this supplier stops producing suggestions. REFUSED while the supplier still has an open purchase order (anything not fully received): receive or cancel those first — get_purchase_orders filtered by this supplier shows them. Purchase orders already placed are kept and still name the supplier.

Delete a tax group. Takes the tax group id from get_taxes. THIS MOVES PRODUCTS: every product assigned to this group is re-pointed at replacementTaxGroupId, or — if you omit it — left with NO tax group at all, meaning those products are sold UNTAXED from that moment. Always ask the merchant which of the two they want and pass a replacement unless they say otherwise. The rates inside it are NOT deleted; they stay available to the other groups (use delete_tax_rate if the merchant really wants a rate gone). CONFIRM WITH THE MERCHANT BEFORE CALLING, naming the group and how many products it affects. There is no undo. Sales already rung up are NOT recalculated — this only affects sales from now on.

Permanently delete a tax rate FROM THE WHOLE COMPANY. Takes the tax rate id from get_taxes. THIS CASCADES: the rate is stripped out of every tax group that lists it and all of its per-outlet percentages are deleted with it. Products in those groups immediately stop being charged this tax. This is almost never what a merchant means when they say "remove the tax from X" — that is remove_tax_rate_from_group. Use this one only when they say the rate should not exist at all any more. CONFIRM WITH THE MERCHANT BEFORE CALLING, naming the rate and listing every group it will disappear from. There is no undo and no way to recover the percentages. Sales already rung up are NOT recalculated — this only affects sales from now on.

Dump one resource in spreadsheet shape — every record flattened to the same columns the import tools accept, WITH its id. Answers 'export my catalogue / my customers', and it is the required first step before any import that changes existing records: the `updates` arrays all key on the ids this returns. For QUESTIONS about the data ("how many products", "find John") use get_products / get_customers / get_categories / get_outlets / get_options instead — they read better and filter server-side. LIMITATIONS: no filtering and no sorting; records come back in stored order, one window at a time. It also cannot produce a FILE — if the merchant wants a .csv/.xlsx download, send them to Settings → Import / Export → Export in the cabinet and do not page through thousands of rows to imitate it. Money is in minor units (cents), matching what the import tools read back.

The stock export file for ONE outlet, as CSV text: Variation ID, Product Name, Variation name, SKU, Stock Management, Cur Qty, New Qty. Use it when the merchant asks for the stock sheet itself — a stocktake worksheet, a hand-off to a supplier, 'give me my stock as CSV'. For stock QUESTIONS — how many of X are left, what is running out, history of a change — use get_stock, find_low_stock and get_stock_history: they filter on the server and explain when tracking is switched off. This dump includes untracked rows and cannot tell "zero" apart from "not counted here". It is READ-ONLY: to write counts back, edit the New Qty column and send the file to import_stock_csv. Large catalogues are truncated — the reply reports the true row count.

What is running out. Answers 'what is low', 'what do I need to reorder', 'what has run out at the warehouse'. Returns the stock-tracked (variant, outlet) lines at or below a threshold, lowest first. Threshold defaults to 5; pass threshold: 0 for "what has actually hit zero". Lines where stock is NOT tracked are excluded on purpose — they have no count, so they can never be low, and reporting them would invent a shortage that does not exist. This is per outlet: the same variant can be empty in one shop and full in another. For one specific product use get_stock instead.

The bookable windows for a product over a date range, per resource, with what is already taken. Quote times from THIS — never compute a grid yourself: the engine applies the hours, the buffer, notice and advance limits, and the outlet timezone, and a hold whose start is not exactly a slot start is refused. Ask for a few days at a time; a year-wide range is slow and pointless.

The trail of what happened to bookings — held, confirmed, cancelled, expired — newest first, with who did it. Use it to answer "what happened to this booking"; an actor of `system` is the server freeing an expired hold, not a person. Each row is immutable, so this is the record even when the booking itself is gone.

List what can be booked — the staff, rooms, tables or assets in the company directory. A resource is whatever can only be in one place at a time, and it is shared across services: the same barber is one resource whether he cuts hair or trims a beard, which is why booking him for one closes the other. Read this before creating anything and reuse what is there.

List the reusable booking policies the merchant already has — opening hours, slot length, buffer, how far ahead people may book. A rule set is shared by every product pointing at it, exactly like a tax table, so ALWAYS read this before creating one and offer an existing set when it fits. Editing a set changes every product that uses it.

The merchant's product categories, as the tree they see in the cabinet: every category with its subcategories nested inside it, sorted by sortOrder. Answers "what categories do I have", "is there a Drinks category", "where does Beer sit". Use it to get the category id any other tool needs. It returns categories ONLY — never products, and never a product count. There is no way to list the products of a category from this server today: get_products searches by name or SKU and cannot filter by category, so say that plainly instead of guessing. To put a product INTO a category, go to the product side: create_product / update_product take categoryIds. The whole tree comes back at once — there is no paging and no search argument, so filter by name yourself.

Where modifiers are actually asked: one row per category↔modifier link, with that category’s own rules (required, min, max, order). This is what makes a modifier reach the till, so use it to answer "what options does this category ask" or "where is this modifier used". Narrow to one category with categoryId. Remember products also inherit their ancestors’ links, so a subcategory asks more than its own rows show. The id on each row is the LINK id — that is what update_category_modifier and unlink_modifier_from_category take.

Everything known about ONE customer: addresses, notes, how many orders they placed, what they spent and what was refunded. Takes the customer ID from get_customers, never a name. Use it before answering a question about a specific person — the list leaves notes and refunds out.

ONE customer's history as a single timeline, newest first: their orders AND the refunds taken against them, each row marked type "order" or "refund" — the same list the customer screen shows. Answers 'what has this person bought', 'did we refund them', 'when were they last in'. Takes the customer ID from get_customers, never a name. get_orders with customerIds returns the orders alone and a total count; use this tool when the refunds belong in the answer. No total count comes back here — keep paging until a page returns fewer rows than asked for.

List the merchant's customers. Answers 'who are my customers', 'find John's email', 'has this person bought from us'. Search matches email, first name, last name and full name — NOT phone numbers, addresses or notes. LIMITATION — there is no sorting: results come back in stored order and cannot be ordered by spend, name or last visit. So 'my best customers' or 'who spent the most' CANNOT be answered from this tool, and you must NOT page through everyone trying. Say plainly that sorting is not supported yet, then offer what does work: search by a name or email, or ask the merchant to narrow it down.

The orders ONE staff member rang up in a date range. Takes the employee id from get_employee_sales, never a name. Use it to back up a claim about a person — 'show me the sales behind Maria's number', 'which orders did he refund'.

Sales per staff member for a date range — Reports → Employee Sales. Answers 'who is my best seller', 'how much did Maria sell', 'who took the most refunds', 'average ticket per employee'. One row per employee with orders, gross sales, refunds, tips and average transaction. Staff lists are short, so ranking is safe: pull the rows and sort them yourself rather than asking the merchant to narrow down. Pass employeeId to get a single person. For the actual orders one person rang up, use get_employee_orders.

The extension STORE: every built-in extension the platform offers, the same list for every merchant. Answers 'what can I add', 'do you have a WooCommerce integration', 'can I get X'. For 'what do I already have', use get_installed_extensions instead — this tool only flags each entry with `installed`. `availableOnYourPlan: false` means the subscription plan excludes it: the store hides it in the cabinet and install_extension will refuse — say so instead of trying. LIMITATIONS, do not paper over them: the platform stores only a name, a category, a price and an id per built-in extension — there is NO stored description, so do not invent what an extension does; say what the name and category say and offer to open its page in the cabinet. `price` is a bare stored string with no currency attached — quote it verbatim, never as a formatted amount. Custom extensions built by an organisation are NOT in this list (they need an organisation scope this agent key does not carry); they do show up in get_installed_extensions once installed.

What the installed extensions ADD to the apps — the answer to "where did this new menu item come from", "what is this extra block on the product page", "what did installing X actually change". Every entry belongs to an installed extension; nothing here is part of the base product. Read `platform` to know where it shows up: `hub` = this admin cabinet, `builder` = the POS flow builder, `render` = the station screen. Within `hub`, type `merchant-hub-page` is a navigation entry of its own and `merchant-hub-widget` is a block embedded in a detail page — `attachedTo` says which one (products / orders / customers / users). LIMITATION: this tells you which extension-provided screens EXIST, not what they contain — each one is an embedded page owned by its extension, and this agent cannot open or read it. It also cannot say which extension contributed a given entry. To go the other way — what is installed at all — use get_installed_extensions.

THE headline money report for a date range — the same numbers as Reports → Financial Summary. Answers 'how much did we make last week', 'what were sales this month', 'how much tax do I owe', 'what lands in my bank'. Returns gross sales, discounts, refunds, fees, tax, tips, net sales, and the settlement split (card / cash / custom) down to what the merchant actually receives. Start here for any "how did the business do" question, and only reach for get_sales_breakdown when the merchant wants the individual orders behind these totals.

What THIS company actually has installed — built-in and organisation-built (custom) extensions alike. This is the answer to 'which extensions do I have', 'is WooCommerce turned on for me', 'what am I paying for'. Not to be confused with get_extension_catalog, which lists what exists on the platform whether or not this merchant has it. Each row carries `extensionId` (pass this to install_extension / uninstall_extension) and `companyExtensionId` (the install record itself — you never need to pass that one). `description` is filled in only for custom extensions; built-in ones store no prose, so do not guess what they do. LIMITATION: the install date is not stored — you cannot say when an extension was added or who added it. To answer what an installed extension CHANGED in the cabinet — a new menu entry, a block on a detail page — use get_extension_surfaces.

Catalogue items this supplier does NOT carry yet but could — the picker behind "add items to supplier". Feed what you choose to link_supplier_items. Only stock-managed items appear: something the merchant does not track stock for cannot be purchase-ordered at all, so if an expected item is missing here and missing from get_supplier_items too, the reason is almost always that stock tracking is off for it — say that instead of guessing. Omit supplierId to search the whole linkable catalogue, e.g. while deciding which supplier to create. Returns everything matching, unpaged, so pass a search.

List the image files stored on the merchant's account. Answers 'what images do I have', 'do I already have a photo of X', 'what did I upload recently', and it is where you get a file id before deleting one, or a URL to reuse on a product or category. Newest first; search is a case-insensitive match on the FILE NAME only. LIMITATIONS, state them rather than working around them: there is no other sorting, and no title, alt text, description, folder, file size or image dimensions here — the Media screen in the cabinet shows those, but they are stored by a different service that this tool cannot read, so it may list files this tool does not and vice versa. There is also NO WAY TO RENAME a file from here: if the merchant asks to rename one, or to change its alt text, title or folder, say that has to be done on the Media screen in the cabinet. Do not delete and re-upload to fake a rename.