More extension points
Part 2 of 5 · 9. The extension points, and how to ask for a new one
Back: The extension pointsNext: Asking for a new extension point, or for more from one
| Extension point | What it lets you do | Where in the kit |
|---|---|---|
| Capture on an event | Your service is asked when an item your filter names is scanned (a beep and a yes or no, a refusal, or values for the line) and when a new customer is added (a one-time code the server checks before the customer is made). It is also asked when the cashier puts an existing customer on a sale (customer_select): allow, challenge with a one-time code, or refuse (the customer is taken off the sale). The server holds every door that charges or books the sale until it has recorded your pass for that cashier, customer, POS Profile and service (a payment on something the customer already holds, such as a layaway's later payment or an order's balance, is not held); the booking spends the pass; the store's walk-in customer is never asked. It is also asked when the quantity of a line your filter names changes (qty_change: the ＋ / − buttons, a typed quantity, a repeat scan; sent the line's last allowed quantity and the new one, keyed by line.line_ref): allow, confirm, refuse (the last allowed quantity comes back) or put values on the line; never asked for a return's quantities, an offer's companion item, a weighed or scale-label line, a set, a gift card, a serial- or lot-tracked line, or an order's change. And any capture may answer notice: the item, customer or quantity goes on with no tap and the cashier reads "⟨label⟩: your sentence" for 8 seconds, a warning that never stops the sale (never a down answer, never sent offline). A scan or customer-select capture whose settings name a placed partner page (page, set by the retailer after the install) gets a button on its notice, Open ⟨the key's caption⟩, on the counter and the tablet. |
Chapter 7 (an extension_subscriptions row of point capture) · A value captured at the scan, and a code before a new customer · S20 · S23 (a beep and a yes or no on a ticked item) · the library page Partner capture |
| Field rules | Per till theme, the till hides a field, calls it by the retailer's own word, requires it on a new customer, or shows up to three more item fields and three more customer fields, offline too, and item fields on the receipt (on screen, on paper and on the offline slip). It also calls a line's money figures (price, discount, line total) and the basket's totals by the retailer's own words, and shows a line's list price; a figure is never moved, hidden or made an input, and a money label may not carry a digit, a % or a currency sign. The receipt keeps its own words: a retailer that wants its word on paper names its own print format. show on customer_create asks for up to three of the retailer's own Customer fields (an ID number, a date of birth) on the new-customer sheet and the till's customer edit, offline too; a save rule makes one required. It is data: no code runs and nothing leaves the retailer's iVendNext. |
Chapter 7 (the field_rules kind) · The retailer's own fields on the till · S21 · the library page Field rules |
| Label layout | The retailer declares a label stock and its layout (HTML, or Zebra printer commands for a counter's label printer) with placeholders from a closed list; the cashier prints shelf labels from an item or a basket line. It is data: no code runs and nothing leaves the retailer's iVendNext. | Chapter 7 (the label_layouts kind) · the library page Label layout |
Fulfil at sale (fulfil/1) |
Your service makes a code for a paid sale line (a digital voucher, a top-up PIN, a game card): after the sale is paid and booked the retailer's server asks you once per line of the items you name, and your code's lines print under the item on the receipt, its reprints and the gift receipt (not on a receipt sent by text message, and on a retailer's own print format only if it reads the code). Before that line is refunded, at any door, its code must be cancelled with your service. One code per line; sold and paid at the till only, never offline. You make no call to iVendNext: it calls you. | Chapter 7 (an extension_subscriptions row of point fulfil) · the library page Partner fulfil, with a stand-in voucher service |
Payer (payer/1) |
Your service pays part of a sale for someone else: an insurer for a pharmacy, an optical plan, a company paying for its staff. When the cashier presses Payer on a named customer's sale, the till asks your service which covers the customer holds (covers), then what you pay line by line (coverage); your share is booked as owed by your own customer record on the retailer's books, never taken as a payment, and the customer pays the rest with the till's other tenders. A return gives your share back, never the customer. One payer service per POS Profile, outside the three check slots. Two ivendnext_mpos.api.v1 names: payer_coverage (asks the payer on a draft Sales Invoice in Desk) and payer_bill_back (bills a rejected claim back to the customer). Every charge is a line's: a sale whose total carries a charge on the whole sale (a service mode's charge) is never asked about, and the cashier is told to take the charge off. Online only. |
Chapter 7 (an extension_subscriptions row of point payer) · An insurance co-payment at the till · Third-party payer · S43 · the library page Payer |
| Register books | The books of a regulated-stock register (a controlled-drug register, a liquor or duty-free book), declared as data in your manifest: which items each book takes, which movements enter it, its numbering, corrections and printed columns. Every document that moves a declared item, on the till or in Desk, then writes one line per book in the same save, numbered with no gap, never edited; a submit from Desk or through the API (never the till's own sale, a sale drained from offline or a background job) that leaves a required column empty or takes a balance below zero is refused, and the till checks the balance before the tender. A book counts, keeps periods and prints for an inspector. | Chapter 7 (the register_books kind) · The controlled-drug register · S41 · the library page Register books |
Open check (open_check/1) |
Your front-of-house app (reservations, a waiting list) or guest-ordering app (a QR menu, a kiosk) opens a table's, a tab's or a pre-order's running order and adds lines to it; every till of the store sees it at once, and the till prices the lines and takes the payment when the table pays. A check holds what was ordered, never a price. The retailer turns it on with the Table Service switch on the POS Profile (off by default), sets up the floor in iVendNext Desk (Floor Sections and their Floor Places), and gives your app's user the store, one register there and its rights in a Retail Permission. Ask only for open a check and see the checks (front of house), and add to a check (guest ordering): moving, merging, closing, changing, sending to the kitchen, voiding and comping are a person's decisions at the till, so staff send each round to the kitchen. Every write carries a fresh random key (a retry re-sends the same key and the same request); a line carrying a price, a discount or a server's note is refused; your app reads no staff identity, no register and no payment token. Paying, claiming and printing a check are a till's only and refuse your app whatever it is granted. The 23 calls: the API page. A weighed article carries its scale reading on the line (weighed; your app's reading counts as a typed weight, so it needs the manual-weight right), and each line the check returns says sold_by_weight; a weighed article added with no reading is refused at Pay until a till weighs it. Bounds: a check needs a connection; which guest may see which check is your app's job (one app user per app). |
An outside app opens a table's order · Open a table's order from your app · the library page Open check |
Station ticket (station_ticket/1) |
Your kitchen screen (a screen per station, an expo screen, a Now serving board) reads the tickets a till's Send gives each kitchen station, from a counter sale or a table's check (the dishes, their choices and notes, the guest and course, the allergen line, the place or call number), and moves each one started, ready and bumped, one step at a time (the same step twice answers already; a skip or a step back is refused). The retailer sets up the kitchens in iVendNext Desk (Kitchen Stations) and gives your app's user the right May Work a Kitchen Screen in a Retail Permission (group Open Checks), with its store set up as for the open check; your user is fenced to its stores. One integration user for each kit app: a user that ever enrolled a till device is refused (DeviceRequiredError). Four ivendnext_mpos.api.v1 names: station_tickets (a station's board), station_ticket_move, and for an item the kitchen runs out of, set_item_availability and item_availability (the API page). Told within a second: after a send, a void or a move commits, the store's users whose Retail Permission ticks the right are told (one who holds it only through write on Kitchen Stations is not) {store, station} on the live notice mpos_station_ticket, a notice and never the ticket, reached only from a long-running server of yours on the site's own Socket.IO socket at /socket.io (namespace /<site name>, Authorization: token <key>:<secret>, Origin the site's own address, a Cookie header that carries no sid). No cursor: every read is the whole board (the last 12 hours not bumped, and 30 minutes of bumped tickets to recall), so read it on every notice and every few seconds. Bounds: a station your screen serves still needs a printer that takes its ticket; a ticket can leave the board with no notice, and tickets printed while the store was offline never reach it; no price on a ticket, and your screen never voids, comps or changes a line; ⚠ the sold-out calls are not fenced to your user's stores: they answer to read, write and create on Retail Item Availability for every store, so ask for them only where your app may mark every store's items. |
A kitchen screen reads a station's tickets · the library page Station ticket |
| List mark | A coloured label on a row of a retailer's Desk list when the row's values say so (On promotion on the product list), declared in your manifest. Display only: it saves and refuses nothing, and no script of yours runs. Desk only. | Chapter 7 (the list_marks kind) · the library page List mark |
| Print template readers | Not a door of its own: two readers, ivn_rows and ivn_value, that your manifest's print formats call to show other records with the rights of the person viewing the print (a price list with each item's price and photo). |
Chapter 7 (Print formats that read other records) · the library page Print template readers |
| Receipt | Store settings, not a declaration: the retailer's own header and footer lines on the shipped receipt without copying it, WhatsApp on the Print sheet where the store has the WhatsApp app, and a register's receipt layout checked before it is set. No manifest kind. | Chapter 4 · the library page Receipt |
One more way in is not an extension point: the manifest install screen (chapter 7) installs your declared data, and the declarations of the extension points, except the wallet (registered on the retailer's payment screens) and the receipt (store settings). Pricing's module is added by the retailer's administrator in Desk or carried by your package. A field rule has no switch: it reaches every till on its theme at the till's next start.
A lot that may not leave the store is not an extension point, but an app that writes stock documents meets it. A lot that is recalled, expired (while the retailer sells no expired lot) or held in a quarantine store (a warehouse marked Is Rejected Warehouse) is refused on every outgoing stock document (a Delivery Note, a Sales Invoice that moves stock, a Stock Entry, a POS Invoice submitted outside the till), whether it comes from Desk, an import or the API: "⟨row⟩: lot ⟨lot⟩ is recalled. It can leave only by a Material Issue, a move into a quarantine store (Is Rejected Warehouse) or a return to the supplier." ("… expired on ⟨date⟩ …"; for a quarantine store, "… is in ⟨store⟩, a quarantine store (Is Rejected Warehouse). Move it out of that store first, issue it for disposal, or return it to the supplier."). Let through: a Material Issue, a move into a quarantine store, a move out of one for a lot neither recalled nor expired, a return to the supplier, a Stock Reconciliation and a Pick List. The till's own sale and a sale drained from offline are never refused: the row is flagged for review. A till write that takes no money (a deliver-later hand-over, a layaway pickup) is refused like any other. Treat the refusal as the retailer's rule and show it to your user.
Back: The extension pointsNext: Asking for a new extension point, or for more from one