Mobile POS¶
Badger Commerce includes a mobile point-of-sale capability that turns a phone into a card terminal using Stripe Tap to Pay. It lets staff and supporters take in-person card payments at events, pop-ups and counters — no dedicated hardware required.
It is driven by the companion badger-pos-app (a separate React Native application) talking to the platform's /v1/pos/* REST endpoints. This page covers what the platform side does and how to operate it; the full endpoint contract is in the API Reference under the POS tag.
What it does¶
- Quick payments — enter an amount and tap a card to collect, or take cash. No catalogue needed.
- Order building — search the catalogue, build a basket, and take payment against a real order.
- Agent management — administrators control who can take payments, build orders and scan tickets, and up to what value.
- Ticket check-in — door staff scan event tickets with the same app. See Event Tickets.
- Transaction history — every sale is a first-class order, so it flows through the same reporting, refunds and emails as web orders.
Sales are Orders, not a separate ledger¶
POS sales are recorded as ordinary Order documents, distinguished by a channel field (POS_QUICK_PAY or POS_ORDER) and a posMetadata sub-document (agent, location, device). This keeps one shape for every sale regardless of source, so checkout, refunds, reporting and order emails all work unchanged.
Quick payments — where there is no catalogue item — are booked against a per-site synthetic quick-pay product, provisioned automatically the first time POS is used on a site. This preserves the invariant that an order's total equals the sum of its line items. The product is switched off, like the till's miscellaneous item: it never appears on the storefront, in search, the sitemap or marketplace feeds, and no basket can add it (a switched-off product can never be added to a basket, from the storefront or the API). The till builds its line itself.
What identifies a store on a sale. Every till sale records its store's location code (posMetadata.locationCode) and, when the store has a card reader, its Stripe Terminal location (posMetadata.locationId). The code is what the Sales list, refunds, receipts, the unfinished-payments list and a cash submit's "is this basket this till's?" check all match on, so a store without a reader works exactly as one with.
Enabling POS for a site¶
POS is configured per site under System → Tenants → {site} → Configuration (category pos-config):
| Config key | Type | Default | Purpose |
|---|---|---|---|
pos-enabled |
boolean | false |
Master switch for the site. |
pos-stripe-location-id |
string | — | The shop-wide Stripe Terminal location id, from before stores. Still honoured; new set-ups give each store its own Stripe location on the location. |
pos-allow-quick-payments |
boolean | true |
Whether amount-only quick payments are permitted, by card or in cash. Off, canProcessQuickPayments is false on everyone's profile and both quick payment endpoints answer 403; baskets are unaffected. |
pos-max-transaction-amount |
integer (pence) | 100000 |
Per-transaction ceiling; requests above this are rejected. |
pos-collection-root-seo-name |
string | — | Root collection for the till's catalogue tree. Omit to use all top-level collections. |
pos-quick-pay-sku-id |
string | (auto) | Set by the platform when it provisions the synthetic quick-pay product. Not user-editable. |
pos-misc-sku-id |
string | (auto) | Set by the platform the first time a till adds a custom amount line: the hidden miscellaneous item those lines are sold as (see Prices set at the till). Not user-editable. |
pos-allow-substitutions |
boolean | false |
Whether staff may name a substitute when an item on a collection order can't be picked (see Items that can't be picked). |
Payments use the site's existing Stripe Connect account (StripeAccountDetails), so each tenant's takings settle to its own Stripe account.
Platform fees on in-person sales¶
In-person sales carry the same Badger application fee as web orders. The fee is
calculated from the site's badgerApplicationFeePercentage and
badgerApplicationFeeFixed settings when they are set, otherwise from the fees of the shop's
platform plan, otherwise 2.4% + 20p (see
Platform billing with Stripe), and taken from the
tenant's Connect payout, exactly as it is for a card-not-present order.
Both card-present routes are covered:
- Quick pay — there is no pricing pipeline on this path, so
PosServicecomputes the fee when it builds the order and stamps it on the order'sPrice. - Order build — the basket has already been through the
priceOrderpipeline, so the feeBasicApplicationFeeCalculatorcomputed is passed straight through.
Either way the fee is recorded on the order as well as sent to Stripe, so it appears in reporting and reconciliation rather than only in the Stripe dashboard.
A sale paid in cash carries no application fee: no card network or Stripe charge is involved, so there is nothing to take a fee from. Its order records a fee of 0.
A site paying through a direct (non-Connect) Stripe account has no platform to collect a fee, so none is applied — Stripe rejects the parameter outright on such accounts.
Granting agent access¶
Taking payments requires the POS_AGENT role, assigned in the admin user editor. A per-site agent profile governs capabilities. It is managed on the POS staff screen (Settings › Selling › POS staff):
enabled— may use the app at all (switch off to suspend someone without removing the role).canProcessQuickPayments— may take amount-only payments, by card or in cash. The profile the app gets says false when the shop has switched quick payments off (pos-allow-quick-payments), whatever the staff record says.canBuildOrders— may build a basket and take payment against it.canScanCustomerCards(on the profile only, worked out) — whether the user may look up a customer from their in-store card withPOST /v1/pos/customers/scan(see Customers with an in-store card). Today that is whoever hascanBuildOrdersat a till that is set up. The app shows "Add customer" only when it is true; a server too old to send it leaves it absent, which the app treats as false.canTakeCash— may record a sale paid in cash: a cash quick payment, or a basket submitted with cash (see Cash at the till). Off for every member of staff until the shop ticks it for them; an admin without a staff record may. It only takes effect alongsidecanProcessQuickPaymentsorcanBuildOrders, at a till that is set up. Cash needs no card reader.canTakeCard(on the profile only, worked out) — whether the till can take cards anywhere: it has a store and a Stripe Terminal location (its own, the shop's, or one of its stores'). Each store on the profile'slocationssays whether cards can be taken there (canTakeCard); the app hides the card button at a store that can't.canAddCustomLines— may add a custom amount line to a till basket, such as £5 for the raffle (see Prices set at the till). Off until the shop ticks it; an admin without a staff record may.canDiscountandmaxDiscountPercent— may give a discount with a reason on a till basket or one of its lines, up tomaxDiscountPercent(0 to 100) of what it comes off. With no limit (blank) a member of staff may take off up to the whole price; an admin without a staff record has no limit. Both are onGET /v1/pos/agents/me.canAdjustStock— may change its store's stock from the till (default off).canCheckInTickets— may scan event tickets at the door (/v1/tickets/**, tagTicketsin the API reference). It needs no payment capability. A scan shows the ticket type, order number and the buyer's abbreviated name (first name and surname initial, e.g. "Chris K."), never their full details. An agent with only this flag still gets their profile from/v1/pos/agents/me(with no Stripe location check, sostripeLocationIdmay be absent), but every payment endpoint, refunds included, answers them403.canAcceptOrders— may run a restaurant kitchen at its locations (/v1/kitchen/**, see Restaurant kitchen and drivers). Gets the new-order alerts.canDeliverOrders— may take restaurant delivery orders out and mark them delivered. Gets the "ready for delivery" alerts. Neither kitchen flag gives access to the till: a kitchen-only agent's profile has nostripeLocationIdand payment endpoints answer403.maxTransactionAmount— an optional per-agent ceiling on one sale, on top of the site-wide limit: cash or card, quick payment or basket. 0 is no limit of their own; an admin without a staff record has none. Over it, the till answers400with "That's more than you can take in one sale (£500.00)."locationCodes: the locations the agent may work at, besides its own legacy Stripe location (stripeLocationId): stores that sell in person, and kitchens (locations that take food orders), with or without a till.
Every /v1/pos/{locationId}/... call checks the agent may work at that location, and returns 403
otherwise: being a POS agent somewhere on the site isn't enough. The path may carry a location code
(what the app sends) or a Stripe Terminal location id. Either way the platform resolves it to the
store, and sales, refunds, receipts and the unfinished-payments list go by the store's code. A sale
from before stores' codes were recorded carries only the Stripe Terminal location, so at a store
with a card reader these also find a sale with no code whose Stripe location is the store's. Only the
card calls (connection token, card quick payment, capture, cancel, and a basket's card-present
intent) need the store's Stripe Terminal location, and answer 503 POS_NOT_CONFIGURED at a store
without one.
The shop-wide Stripe location is only a default. pos-stripe-location-id is the till's store for
someone with no stores of their own (an agent with none assigned, or an admin). An agent assigned
stores is bound to them: the profile's stripeLocationId is its own Stripe location if it has one,
otherwise the first of its stores with a card reader, never the shop-wide one. Every store the till
names, by code or by Stripe location, the agent's own included, must be one of its assigned stores
(403 otherwise).
Signing in to a shop¶
Every build of the app talks to the same two hosts, whichever shop it is used for: the API
(api.bdgr.co.uk) and Badger Auth (auth.bdgr.co.uk), or their staging and local equivalents. There
is no shop address to type in. The person signs in, and Badger Auth works out which shop the till is
for:
- One shop. Someone who can use the till on one shop only goes straight back to the app, signed in to that shop. There's no extra screen.
- Several shops. Badger Auth shows Choose a shop: the shops where the person can use the till, by name, each with its logo and web address. A search box appears above the list when there are more than eight.
- No shops. Badger Auth says the account doesn't have POS access on any shop and to ask the shop's owner to add them as a POS agent, with a Sign in with a different account link, which signs them out and starts the same sign-in again.
A shop is listed when the person has an account on it with POS_AGENT, POS_SUPERVISOR or an
admin role. These are the same rules the token itself is checked against, so a shop on the list is
one the sign-in will be allowed to use. The token the app gets back carries the shop (site_id), and
the API takes the shop from the token, not the host name. GET /v1/pos/agents/me returns the shop's
own web address (storefrontUrl) for the app's manual checkout fallback.
Switching shop. Switch shop in the app's account menu goes back to Badger Auth and always
shows the list, even with one shop ("This is the only shop you can use the till on"), with the
current shop first and marked Current. The app asks for this with two parameters on the
authorize request: shop_prompt=select (always show the list) and shop_hint=<site id> (the shop to
list first). If the person is still signed in to Badger Auth this is a single tap. A till that signs
in privately (a shared device) asks for the sign-in again, which is what a shared till should do.
The app won't switch while a payment is unfinished, and clears what it holds for the old shop.
Setup QR codes and named shops. An app that names its shop (a setup QR code carrying the shop's
id, an older app build, or the Use a shop URL option under Advanced, which reads the id from
the shop's /.well-known/badger-site-id) passes it as site_id on the authorize request, and the
list is skipped. Use a shop URL is also how the app is pointed at a self-hosted platform.
When the sign-in is refused. Whichever way the shop was chosen, Badger Auth only issues the
token if the person has an account on that shop with POS_AGENT or an admin role. Otherwise the
token request answers 400 with error: access_denied and a plain description the app can show,
such as "Your account does not have POS access on this shop." A refresh refused for the same reason
(say the person has been removed from the shop since signing in) answers 400 with
error: invalid_grant, so the app drops the refresh token and signs the person out rather than
retrying it. The same happens when the shop doesn't exist or isn't set up for sign-in. The app never
gets a token without a shop: a token request from the app that names no shop is refused with "Choose
a shop to sign in to.", since the API would otherwise have tried to resolve the shop from its own
host name, answering every call with no shop. The admin client (badger-web-admin) is refused in the
same way when it asks for a shop the user has no admin role on.
A deployment whose app client is fixed to one shop (POS_APP_SITE_ID) skips the list and issues
tokens for that shop without checking the user's role there at sign-in; the API checks what the user
may do on each call. Asking it for another shop is refused. A client fixed only to a site group
(POS_APP_SITE_GROUP_ID) also skips the list, accepts any shop in that group and binds the token to
it, and refuses a shop outside it.
Staying signed in¶
The app signs in once and stays signed in as long as it is used at least once every 14 days. The
sign-in gives it a 60-minute
access token and a refresh token; it swaps the refresh token for a fresh pair before the access
token runs out (POST /oauth2/token with grant_type=refresh_token, refresh_token and
client_id=badger-pos-app, no secret). Each refresh token works once and lasts 14 days from when
it was issued, so a till used at least once a fortnight never goes back to the browser. Every
refresh checks the person's POS role on the shop again, so someone removed from the shop is signed
out within the hour.
The app has no client secret (no app can keep one), and Spring Authorization Server gives no
refresh tokens to clients without one. Badger Auth makes an exception for its own apps, listed in
badger.auth.trusted-public-client-ids (by default just the POS app's client id), and only while
the client is registered without a secret, with the refresh grant and with refresh tokens that
rotate (TrustedPublicClients). A client that registered itself (an MCP connector) never
qualifies. A POS app client saved before the rotation flag was stored reads back as reusing its
refresh tokens and so got none; PosAppClientSeeder brings an existing one up to date at start-up
(refresh grant, offline_access, rotating), leaving its redirect URIs, lifetimes and shop binding
as they are. What makes this safe is the rotation:
- A replaced refresh token ends the sign-in. If a refresh token that has already been swapped
comes back, someone else has a copy of it, so Badger Auth deletes the whole sign-in: neither copy
works, and the till signs in again. The exception is a token replaced in the last 30 seconds,
which is the app sending two refreshes at once; that request is refused with
invalid_grantand the sign-in is kept. The app should still send one refresh at a time. - Signing out revokes the token. The app posts the refresh token to
POST /oauth2/revokewith itsclient_idwhen someone signs out.
Store the refresh token in the device's secure storage (Keychain / Keystore), not in plain app storage. When a refresh is refused, show the sign-in screen and wait for a tap, rather than opening the browser by itself.
Remembering who signed in. The app may pass the last person's email as a plain login_hint on
the authorize request. For the POS app only, Badger Auth uses it to fill in the email field and
nothing else: no name, no list of sign-in methods and no code sent, so the page says nothing about
whether the address has an account. Other clients' hints must be encrypted (LoginHintDecryptor).
Admin users get POS access implicitly for testing, with generous defaults, and may also check tickets in. At login the app calls GET /v1/pos/agents/me, which returns the agent's site name, role, capabilities (including canAdjustStock, canCheckInTickets, and canPrintLabels when the shop buys parcel labels), Stripe location, whether it can take cards (canTakeCard), the stores it may sell at (locations, each with its own canTakeCard) and the catalogue root — everything the till needs in one round-trip. A user with no POS capabilities receives 403. An agent with stores but no Stripe location of its own gets the first of its stores that has one.
A till without a card reader. A store that sells in person (an active location with Sells in person ticked) is a till whether or not it has a card reader: a market stall or a charity collection with no reader takes cash. At such a store the app gets canTakeCard: false for it and hides the card button; quick payments in cash, baskets paid in cash, cash refunds, receipts, the Sales list, the dashboard, promotion codes, custom amounts and discounts all work as at any other store. Only the card calls need a reader: the connection token, a card quick payment and its capture or cancel, and a basket's card-present intent answer 503 with X-Badger-Error-Code: POS_NOT_CONFIGURED there. Store tasks and stock never needed one.
A shop whose till isn't set up yet. The till needs a store to sell at: one of the agent's assigned stores that sells in person (an admin: any of the shop's), or a Stripe Terminal location of the agent's own or in pos-stripe-location-id. Until there is one, someone who would have the till (canProcessQuickPayments or canBuildOrders, or an admin) but also serves tables, runs a kitchen or the diary, or checks tickets in still gets their profile, with tillNotSetUp: true and both till flags false. The app hides Sell, Cart, Dashboard and Orders as it does for anyone without the till, and can say the till isn't set up rather than that they aren't allowed. Every other part of the app works as their other flags say; table service takes cash and other non-card tenders, and card payment on a tab needs a Stripe account. Till endpoints (/v1/pos/dashboard, /v1/pos/{locationId}/transactions, payments, refunds) answer them 503 with X-Badger-Error-Code: POS_NOT_CONFIGURED. Only a user who could do nothing but sell gets that 503 from /v1/pos/agents/me itself.
The profile also says why (tillNotSetUpReason), so the app can show one plain sentence on whichever screen the user lands on: NO_SELLING_STORE (no active location sells in person) or STAFF_NOT_ASSIGNED (the shop has stores that sell in person, but this person's POS staff record has none of them; never for an admin without one). For an admin, tillSetupPath is the admin page that fixes it (the locations list, or the person's POS staff page); staff get none and should be told to ask an admin. A 503 POS_NOT_CONFIGURED for a till that isn't set up carries the same value in X-Badger-Till-Reason; a card call at a store without a reader carries none. A store not linked to Stripe Terminal, or a shop without Stripe, isn't a reason: the till works for cash, with canTakeCard: false.
Error codes. A refusal that comes as plain text (Content-Type: text/plain) from the POS, basket, table-service, kitchen and appointments endpoints carries an X-Badger-Error-Code header when the app needs to act on which case it is. The body is a sentence for staff and may change: never match on it. JSON refusals carry their own fields instead (reason on BasketAlreadySubmittedError and BasketLockedError; reason and code on DiningTabError, below). A refusal with no code is one the call describes in its own words (a sale already refunded in full, say): show the sentence and don't retry it unchanged. On a refund or a payment, check the sale before trying again.
| Code | Status | Where | What it means | Retry with the same Idempotency-Key? |
|---|---|---|---|---|
POS_NOT_CONFIGURED |
503 | Till calls; a basket's card | The till isn't set up: no store that sells in person for this person (assign one on POS staff), or, on a card call, the store has no card reader (link it to Stripe Terminal in Settings › Locations, or take cash) | No |
STRIPE_NOT_CONFIGURED |
503 | Till, table service, dining refunds | No Stripe account connected (Payments) | No |
STRIPE_UNAVAILABLE |
503 | The store's card readers | Stripe couldn't be asked: down, slow, or refusing the shop's account for Terminal | Yes, after a moment; meanwhile show the readers the till can see |
IDEMPOTENCY_KEY_IN_FLIGHT |
409 | Every POS, basket, kitchen, table-service, dining and appointments call that takes an Idempotency-Key |
The first request with this key is still being processed. This request did nothing. A request that stopped part-way lets go of its key within 2 minutes | Yes, after a second or two (backing off). The retry answers what the first request did |
ORDER_BUSY |
409 | Cash refund; short pick and its undo | Another till is refunding the same sale in cash, or something else is changing the same order, at this moment. Nothing changed, and this request's own key isn't in flight. The guard is best effort, so a clash can also come back as a refusal with no code | Yes, after a moment |
REFUND_PART_DONE |
409 | Till refund | The refund stopped after some of its money had gone back to a card or been recorded as cash (the sentence says how much went back to cards, if any; recorded cash is never stated, since none is to be handed over yet): a later card failed at Stripe (an error, or a refund Stripe answered failed or cancelled), the order's hold was lost between cards or while recording them, or the cash part was refused or cut off part way. A failed or cancelled Stripe refund doesn't count as money gone back. Hand over no cash: the 200 that finishes the refund says all the cash to hand back |
Yes, and only with the same key: the retry counts what already went back and gives only the rest. If the same refund is refused again, check the sale. Never start a new refund for it: a new refund doesn't know what this one gave back, so asked for the same amount it gives it again from what is still refundable, and the customer can get back more than they are owed |
CASH_SALE_NOT_PLACED |
409 | Basket submit in cash | The submit failed, for any reason, after the cash was recorded, and the cash has been taken back off the basket. Hand the cash back to the customer | No: take the payment again (a new payment). If a later submit says the basket is already submitted (the order was left PAYMENT_FAILED), build the sale again in a new basket |
CARD_TAKEN |
409 | Basket submit in cash; a basket's card | A card has been authorised or taken on the reader for this sale. No cash and no new card payment was recorded (the taken card may now be recorded on the order) | No: finish the sale by card, or cancel that card payment first |
CARD_CANCEL_UNCONFIRMED |
409 | Basket submit in cash; a basket's card | A card on the reader couldn't be confirmed cancelled (Stripe didn't answer, or is still processing it). It isn't known to be taken, but nothing was recorded on top of it, so a card that is charged after all is never paid twice | Yes, after a moment, or finish the sale by card |
SUBSCRIPTION_NEEDS_CARD |
409 | Basket submit in cash | The basket has a subscription, which needs a card to renew | No: take it by card |
PAYMENTS_SHORT_OF_TOTAL |
409 | Basket submit by card | The cards and cash on the sale come to less than its total; nothing was captured | No: take the rest, then submit again |
CARDS_OVER_TOTAL |
409 | Basket submit by card | The cards on the sale come to more than its total; nothing was captured | No: cancel the card payment and take it again for the right amount |
PAYMENT_NOT_TAKEN |
409 | Basket submit | The payment couldn't be taken, so the order was left PAYMENT_FAILED: not a sale |
No: check the order in the admin |
ORDER_NOT_PLACED |
409 | Basket submit | The order wasn't placed (a product this customer may not buy, an item whose handover breaks its product's rule, or tax not worked out) | No: put the basket right first |
An in-flight answer carries no Retry-After: the only figure known is the 2 minutes after which a stalled key is let go, and the first request almost always finishes long before that.
Requests that can't be read. A till or basket request whose body can't be read, or whose body or parameters break the API's rules (a negative amount, a missing field, a parameter of the wrong type such as pageSize=abc, a required parameter or header left out), answers 400 in the shape that call documents: a plain-text sentence on the till and basket calls, the PosStockCountRejection JSON (no SKUs) on a stock count, and no body on a promotion code. The sentence may name the fields at fault but never repeats what was sent, so an email address typed wrongly isn't echoed back or logged.
The ticket scan endpoints (GET /v1/tickets/events, POST /v1/tickets/check-in, POST /v1/tickets/{ticketId}/check-in, POST /v1/tickets/{ticketId}/undo-check-in, GET /v1/tickets/lookup, POST /v1/tickets/search) answer every decoded scan with 200 and the outcome (ADMITTED, ALREADY_CHECKED_IN, VOID, WRONG_EVENT, NOT_YET_OPEN, EVENT_ENDED, NOT_FOUND), and 400 for a code that isn't a ticket code. Lookups never return a ticket's code, so a ticket found by lookup is checked in by its id (POST /v1/tickets/{ticketId}/check-in). GET /v1/tickets/lookup takes codes only (order number, the code's last four characters or a full code); finding a ticket by the buyer's name or email address is POST /v1/tickets/search, with the search in the JSON body so it never appears in a URL, and both answer Cache-Control: private, no-store. Check-in by id doesn't judge the check-in window: staff checking someone in by hand have decided to admit them. GET /v1/tickets/events with no parameters lists events whose check-in window falls between the start of today and the end of the day ticketing-app-lookahead-days days later (default 2), in the site's time zone, earliest start first. Each event carries checkInOpensAt and checkInStatus (UPCOMING, OPEN or ENDED), so the app can show a coming event as locked until its door opens; a scan before then is still NOT_YET_OPEN. Check-in and lookup are rate-limited per user (badger.tickets.rate-limit.check-in-per-minute, default 120, and badger.tickets.rate-limit.lookup-per-minute, default 20, with lookups that search buyers' names and emails also limited by badger.tickets.rate-limit.name-lookup-per-minute, default 8) and answer 429 past the limit.
Stores, devices and stock¶
Each till works at one store at a time.
- Store picker.
GET /v1/pos/locationslists the stores the user may sell at: active locations that sell in person, with a card reader or not (an agent's assigned ones plus the one its own Stripe location belongs to; for an admin, all of them). Each entry has thecodeto send as{locationId}, the name, the Stripe location id (absent without a reader), whether cards can be taken there (canTakeCard), address lines and whether stock is counted there (holdsStock). A shop still onpos-stripe-location-idalone gets one entry, its main location, codedefault. - Devices. After login and whenever it changes store, the app calls
PUT /v1/pos/{locationId}/devices/{deviceId}with the device's name, platform (ios,android,web), app version and Expo push token.deviceIdis the app's own id for the install (1-64 letters, digits,-or_). The push token is stored but never returned or logged, and device names are treated as personal data (never logged). Admins see each agent's devices on the POS staff screen and can rename them; a name given there is kept on later registrations. - Card readers and which till holds each.
GET /v1/pos/{locationId}/readerslists the store's card readers for the reader picker, Tap to Pay phones left out: each with Stripe's id, itslabel(its name on Stripe, which the shop can change on the store's page; the Terminal SDK gives a Bluetooth reader none),deviceTypeanddeviceName, the fullserialNumber(a Bluetooth reader found by scanning has no Stripe id, so the app matches on it),online(meaningless for Bluetooth, which Stripe always reports offline),connection(bluetoothfor the WisePad 3, M2 and Chipper 2X;internetfor the rest) andheldBy(the till connected to it:deviceId,name,since; absent when none is). Any user who may use the till at that store may call it. The list from Stripe is kept for 60 seconds per Stripe location (PosReaderService); holds are always current. A store with no Stripe Terminal location answers404, as an older server without the endpoint does; Stripe failing answers503withX-Badger-Error-Code: STRIPE_UNAVAILABLE.
A connected Bluetooth reader stops advertising, so the other tills can't see it. The till says
which reader it holds in reader on the device PUT (id, serialNumber, deviceType; never
Tap to Pay), sent when a reader connects or disconnects as well as on launch and on returning to
the foreground. Leaving reader out changes nothing (an older app); null or {} means the till
holds none. Only one till holds a reader, so naming one takes it from any other till on the shop.
Holds are matched on the id when both sides have one, else the serial, so a first connect sent
before Stripe has registered the reader still counts, and the id is kept once it is known. The
hold is stored on the device (readerId, readerSerial, readerDeviceType, readerSince, which
moves only when the reader changes). A till that dies or loses signal never lets go, so a hold
counts only while that till has registered within the last 12 hours
(PosDeviceService.READER_HOLD_CUTOFF). The store's admin page shows the same: "In use on Till 2
(since 10:02)".
- Basket sales at a store. On impersonated basket calls the app sends
X-Badger-Pos-Location: <code> beside X-Badger-Acting-As. The order records the store
(posMetadata.locationCode its code, posMetadata.locationId its Stripe id when it has a reader).
Without the header the agent's default store is used: the one its own Stripe location belongs to,
else the first it may sell at. With several stock locations on and a store that holds stock, the
sale takes its stock there; otherwise from the main location, exactly as before.
- Taken now. Every line added to a till basket is a take-now line (takenNow: true on the
line): the customer took it off the shelf and leaves with it, so it is a collection handed over
at the moment of sale. It is fulfilled when the sale is placed, goes to no fulfiller (no email,
Slack post or portal queue entry), and requiresShipment is false on it, so there is no dispatch
email either. The item is physically there, so the stock figure never refuses it: the add
ignores the store's figure, and when the sale is placed the figure is reduced by the units sold,
or set to 0 when it said fewer than that (the sale's activity shows TAKEN_NOW_STOCK_OVERRIDDEN,
and a cancellation puts back only what was taken off). takenNow is how a till sale of this kind
is told apart from a line sent or collected later.
- Sending an item from the till. Staff drive the till and ask the customer, so the flow is on
the same basket, paid for in store. PATCH /v1/basket/{basketId}/{lineItemId}/send
({"send": true}) turns a line from take-now into a sent line (takenNow: false,
requiresShipment: true); {"send": false} turns it back. It is refused with a 409 for a
digital item, a collect-only item (the product's handover rule), an amount, a donation or a booking, and when none is in stock to send. Each till line carries canBeSent: false for a collect-only item, an amount or a booking, so the app can hide the option; true still allows a 409 for stock or a digital item. The basket
then needs a delivery option (PATCH /v1/basket/{basketId}/handover) and a delivery address
(deliveryAddress on PATCH /v1/basket/{basketId}/personalDetails, stored as the order's
shipping address); a submit without both is a 409 with SEND_DETAILS_MISSING and nothing is
taken. A sent line is stocked and fulfilled as a web order's line is: its stock is sourced from
the warehouse or another store that has it (not forced to this store's shelf), and it goes to a
fulfiller, with dispatch email and tracking. Take-now lines on the same sale still take the
shelf's stock here and go to no fulfiller. Customers entering their own address on the till
(hand-off to the customer) isn't built.
- Stock lookup. GET /v1/pos/{locationId}/stock/{skuId} returns here (this store's
inStock and sellable, or null when it holds no stock) and elsewhere, the shop's other
stock-holding locations that can sell some, so staff can say "Leeds has 2". Until the shop uses
several stock locations only the main location counts as elsewhere. -1 means not counted.
- Stock adjust. POST /v1/pos/{locationId}/stock/{skuId}/adjust with
{ "adjustment": -1, "reason": "damaged" } (count, received, damaged, gap or other)
changes this store's figure and returns the lookup. It needs canAdjustStock (or an admin without an
agent record), returns 400 with a plain-text reason for a zero change, a store that holds no
stock, a store other than the main location while the shop uses one stock location, a SKU the
shop doesn't count there, or a change below zero, and accepts an Idempotency-Key so a retry
isn't applied twice (a repeat with the same key and body returns the figures as they stand).
Each change is logged with the agent, store, SKU, change and reason (ids only). gap is for a
gap check: the shelf was empty or short where the record said there was stock.
- Stock set (a count). PUT /v1/pos/{locationId}/stock/{skuId} with
{ "onHand": 0, "reason": "gap" } sets this store's figure to what staff counted, whatever was
recorded before, and returns the lookup. Use it for a shelf count or a gap check; use the adjust
call for a delivery or a breakage. The same rules as adjust apply (canAdjustStock, a store
that holds stock, the main location only until the shop uses several stock locations, the same
reasons), and 400 also covers a figure below 0. A SKU the shop doesn't count at the store
can't be counted from the till: set it up in the admin first. An Idempotency-Key makes a
retry safe in the same way. A sale that lands between the count and the call is overwritten by
the counted figure. Each count is logged with the agent, store, SKU, the figures before and
after, and the reason (ids only).
- The record of stock changes. Every adjust and set from a till, every line a stock count
applies, and every stock change a short pick makes, is kept as a stock movement: store, SKU, the
figure before and after, the change, the reason, how it was made (POS_ADJUST, POS_SET,
POS_COUNT with the count's id, or SHORT_PICK; see Items that can't be picked) and the
member of staff (by user id). A retry that isn't applied again records nothing. The figures are
changed first, so a movement that can't be saved is logged as an error and the change stands.
Movements, like counts, are the shop's own records: site transfer (System › Tenants › Move
data) never copies them, and deleting a site deletes them.
- The store's list, for a count or a gap walk. GET /v1/pos/{locationId}/stock returns the
shop's enabled products by name, a row per variant (or the product itself when it has none):
{rows: [{skuId, productSkuId, name, variantLabel, barcodes, onHand, tracked}], pageNumber,
pageSize, totalProducts, totalPages, hasMore}. collection (a seoName) narrows it to that
collection and every collection below it. maxOnHand keeps only rows the store counts with at
most that many: 0 lists what the record says has gone, which is a gap walk's starting point.
A page is pageSize products (default 50, at most 200), so it can hold more rows than that, or
fewer once maxOnHand has filtered it; keep paging while hasMore is true, even past an empty
page. Levels are read once per page, live. Reading it needs what reading one SKU's stock needs.
A store that holds no stock, or an unknown collection, is a plain-text 400.
- Stock counts. POST /v1/pos/{locationId}/stock/counts with {reason?: count|gap|...,
note?, entries: [{skuId, onHand}]} (1 to 500 entries, each SKU once) records a walk round the
shelves as one count and sets each SKU to what was counted. Idempotency-Key is required.
The whole count is checked first: no Idempotency-Key, no entries or more than 500, a line
without its skuId or onHand, a SKU twice, a figure below 0, a
SKU the shop doesn't have, or one this store doesn't count refuses it whole with 400 and
{message, skuIds} naming the SKUs at fault, and nothing is applied. Then each SKU is set in
turn. There is no transaction across SKUs, so if one can't be set the rest still are and the
answer says status: PARTIAL, with entries: [{skuId, counted, before, after, applied,
auditMissing, problem}] showing which (auditMissing: set, but its stock movement couldn't be
saved). Each SKU's outcome is written to the count as soon as it is applied, by the request that
holds the count's lease (renewed with every SKU, lost after 60 seconds without one). The answer
is kept with the count, so a retry with the same key gets it back (a partial one included) and
never applies the count twice; the same key with another body is 422, and a retry while the
first request still holds its lease is 409, however long the count takes. Only once the lease
has run out (the first request stopped) does a retry take the count over, in one atomic write
after which the first request can't write to it again, and settle it from the outcomes recorded:
SKUs not reached say they weren't applied, and the SKU it stopped on says to check its figure and
count it again, unless its movement shows it was set. Counting needs canAdjustStock and the same store rules as setting one SKU.
GET /v1/pos/{locationId}/stock/counts?pageNumber&pageSize lists the store's counts, newest
first, with who counted (agentId, agentName), why, how many SKUs and how many were applied,
so a manager can see a walk happened; it needs canAdjustStock too.
The payment flow¶
There are two payment flows depending on whether the sale has catalogue line items.
Quick pay (amount only, no basket)¶
- The app requests a Stripe Terminal connection token (
POST /v1/pos/{locationId}/connectionToken). - It creates a card-present payment intent (
POST /v1/pos/{locationId}/paymentIntents) with the amount. This creates aPOS_QUICK_PAYorder against the synthetic quick-pay product. The order belongs to a new walk-in guest (like a basket order's), not to the agent, who is recorded asposMetadata.agentId, so quick payments stay out of the agent's own order history. - The customer taps their card; the app captures (
.../capture) or cancels (.../cancel) the intent. On capture the quick-pay order completes directly — there is no separate submit step — and takes the next number from the shop's order-number series, as a web order does at submit, with a confirmation code for its receipt. The capture answer carriesorderId,orderNumberandreceiptUrl. A cancelled or declined tap is never numbered.
The create step takes no order to charge: a basket is paid through the basket endpoints below. The capture and cancel calls likewise act only on a quick payment taken at this store: the intent must belong to a POS_QUICK_PAY sale at the store in the path (404 otherwise, before Stripe is asked), and capture only for that sale's amount (409 if the intent is for another amount). Cancel doesn't check the amount, so a card asked for the wrong amount can always be cancelled. A basket's card is captured by the basket's submit and cancelled through the basket, never through these calls.
No tips at the till. Tips are taken only on a table's shares (see table service). The app collects quick payments and basket cards with the reader's own tip screen skipped. If a reader adds a tip anyway, it isn't part of the sale and isn't taken: a quick payment is captured for its total, and on a basket the tip isn't counted towards the balance (another card can take what is still owed) and is released when the basket is captured.
A card quick payment passes exactly the checks a cash one does, made by the same code:
canProcessQuickPaymentson the profile (403without it). That is the person's flag and the shop'spos-allow-quick-paymentstogether, so switching quick payments off for the shop stops card and cash alike, and the app, which reads the same flag, hides the button.- The shop's currency only.
currencymay be left out (the shop's is used); any other is a400. A card is never charged in pounds by default at a shop that sells in euros, and a cash sale is never recorded in pounds there either. Answers give the currency in lower case (eur). - The amount more than nothing and within both
pos-max-transaction-amountand the member of staff's ownmaxTransactionAmount(400over either, with the cashier's sentence). - The sale's total is the amount typed. A shop whose tax settings would make the total differ (tax added on top, or taken off an export) can't take a quick payment, by card or in cash:
400, and the order made for it is voided. Build a basket instead. - The store needs a card reader (a Stripe Terminal location): without one the answer is
503POS_NOT_CONFIGURED, and the sale can be taken in cash.
Known limitation: shops whose prices are entered without tax. On a shop whose prices exclude tax (Stripe Tax adds it on top at checkout), a quick payment at a store with an address records no tax at all: the amount typed is the sale's total, and no tax is worked out of it or added to it. (At a store with no address, Stripe Tax would add tax on top, so the quick payment is refused as above.) Such a shop should sell at the till by building baskets, whose items are priced and taxed as on the web, until in-person quick payments support tax-exclusive prices.
Order build (card-present against a basket)¶
When the sale has real catalogue items, payment is taken against the built basket so the order goes through the normal submit pipeline (inventory, order number, confirmation email):
- Build the basket (see impersonation below) and request a connection token as above.
- Create the card-present intent on the basket:
POST /v1/basket/{basketId}/paymentIntent?paymentType=card_present. The response carries the Stripeclient_secretinpaymentTokenand the intent id inthirdPartyId. (Onlycard_presentis supported here;card_not_present/giftcardreturn400.) - The reader collects and confirms the payment with that client secret.
- Reconcile the intent to authorised:
PATCH /v1/basket/{basketId}/paymentIntent/{intentId}. The backend re-reads the intent from Stripe (it never trusts the request body). Optional: submit does the same for any card-present intent still recorded as uncollected, so a client that goes straight from the reader to submit still has its payment captured. - Submit the basket:
PUT /v1/basket/{basketId}/submit. The order pipeline captures the authorised intent. A200always means the sale is recorded and paid. A till sale is always captured when it is placed, whatever the site's capture point (a site that otherwise captures at pack or dispatch included), since nothing later packs or dispatches it and a card-present authorisation lasts only days. A till sale set up for later collection is captured at the till too, and anything it then can't hand over is refunded. A sale placed before this rule whose card is still only authorised isn't counted as money taken: it shows as not paid in Sales and is left out of the dashboard.
Paid in full, or not placed. A till basket is only placed when the cards authorised or taken and any cash on it come to its total. Submitting one whose payments fall short (no card authorised yet, or a card asked for part of the balance with amount) is refused with a 409, X-Badger-Error-Code: PAYMENTS_SHORT_OF_TOTAL and a sentence for the cashier ("The payments on this sale come to £5.00 of £20.00. Take the rest by card before finishing the sale."), before anything is captured: the basket stays open, so take the rest and submit again. The submit pipeline holds the same rule for any other way a till basket could be submitted, failing it rather than capturing short. If the capture itself fails, the order is left PAYMENT_FAILED and submit answers 409 with X-Badger-Error-Code: PAYMENT_NOT_TAKEN, never 200; a later submit of that basket gets the 409 BasketAlreadySubmittedError with state: PAYMENT_FAILED, which is also not a sale.
Never more than the total. The submit, and the submit pipeline behind it, never capture more than the basket comes to. When the cards authorised on it come to more than its total, the excess is released at capture (on the newest card first), so the customer is charged the total and the rest of the hold is let go. Money already captured past the total is refused (409, "Cancel the card payment and take it again for the right amount."), and the order isn't placed. A capture is never taken in full as a fallback: if what is to be released isn't less than what the card authorised, the capture is refused, the payment record says why (failureCode: release_not_less_than_authorised) and the order is left PAYMENT_FAILED with the card still authorised. DELETE /v1/basket/{basketId}/paymentIntent from the till, or cancelling the order in the admin, releases the hold; left alone it lapses on its own.
Asking for a card again. POST /v1/basket/{basketId}/paymentIntent cancels any earlier card the reader hasn't taken, and confirms the cancel with Stripe, before asking for a new one. If an earlier card can't be confirmed cancelled, or the reader had in fact authorised it (it is then recorded on the basket), the new card is refused with a 409 and a sentence for the cashier, so the customer never carries two holds.
A card on the reader holds the basket. From the moment a card-present intent is started on a till basket (the reader is asking for the card), until it is cancelled or fails, the basket's lines, quantities, prices, discounts and promotion codes can't change: 409 BasketLockedError (reason: PAYMENT_IN_PROGRESS, messageKey: basket.msg.tillPaymentStarted, "A payment has been started or taken for this sale, so it can't be changed. Cancel the card payment first."). Otherwise a line could be taken off after the card was asked for the old total. The customer's details (name, email, Gift Aid) can still be set, as they don't change the amount.
To abandon a part-paid basket, DELETE /v1/basket/{basketId}/paymentIntent cancels every not-yet-captured intent on the gateway and clears the order's payment pointer. Each cancel is read back from Stripe: an intent Stripe reports as taken, or one it won't confirm as cancelled, stays on the basket and the call answers 409, with the cancelled ones removed. Only once every card is cancelled can the basket be changed again.
On a till basket, the card-present intent is held to the member of staff's own maxTransactionAmount on the amount it would charge (the balance, or the amount sent), the same limit and the same 400 sentence as cash. amount is for part of the balance (a sale split across two cards) and is never more than the balance: a larger amount charges the balance. At a store with no card reader the intent answers 503 POS_NOT_CONFIGURED; pay the basket in cash.
Promotion codes on a till basket¶
A code the customer gives is put on the basket with PUT /v1/basket/{basketId}/promotionCode {"code": "SAVE10"} (with X-Badger-Acting-As, as for the other basket calls), usually after the items are scanned, and taken off with DELETE /v1/basket/{basketId}/promotionCode?code=SAVE10. A code can also be sent as promotionCode on POST /v1/basket. Each answers the repriced basket with promotionCodeResult:
status: what happened.APPLIED,ALREADY_APPLIEDorREMOVED; or why the code wasn't applied:NOT_FOUND,EXPIRED,NOT_YET_ACTIVE,CONDITIONS_NOT_MET(the basket doesn't meet the promotion's conditions, such as a minimum spend),USED_UP,ALREADY_USED,NOT_ASSIGNED,EMPTY_BASKET,TOO_MANY_ATTEMPTS,BLANK,PAYMENT_IN_PROGRESSorMAKES_APPOINTMENT_FREE.applied: whether the basket is as asked;message: a sentence to show, in the shop's language;codes: every code on the basket with its name, what it takes off (discountInPence) and whether it currently applies.
A code that can't be used is still a 200 (on POST /v1/basket too: the basket is created without it). A placed basket's codes can't change (409, plain text), and nor can those of a basket that already carries a payment (a card authorised or taken, or cash recorded): 409 with a BasketLockedError body, reason: PAYMENT_IN_PROGRESS, the same answer its lines, custom amounts and discounts get. The customer's own limits (a code they've used before, one for particular customers) are checked against the customer the till acts for. The till then takes payment for the discounted total as usual, by card or in cash, and each promotion's use is recorded when the basket is submitted, as for a web order.
Guessing. The storefront's limits apply, counted against the member of staff rather than an address: 8 wrong codes on one basket, or 10 wrong codes from the same member of staff across baskets, within 15 minutes, and further codes answer TOO_MANY_ATTEMPTS without being looked at until the window ends. The till is never asked for a CAPTCHA. A signed-in API client that isn't a till is counted by its own user in the same way.
Prices set at the till¶
A till basket can carry three kinds of price the catalogue doesn't give it. Each is accepted only from POS staff acting for a customer (X-Badger-Acting-As) on a till basket (channel: POS_ORDER). A storefront or app shopper sending any of these, or staff calling without acting for a customer, gets a 403 and the basket is unchanged. The price is stored on the line by the platform after its checks; no request body can set it directly, and on any other order it is ignored when the basket is priced.
- Custom amount:
customLine: {"amountInPence": 500, "label": "Raffle tickets"}in an add-to-basket item (PUT /v1/basket, or an item ofPOST /v1/basket), with noskuId. NeedscanAddCustomLines. The line is quantity 1 of the shop's hidden miscellaneous item, created the first time and recorded inpos-misc-sku-id. The item is switched off, so it never appears on the storefront, in search, the sitemap or marketplace feeds, and adding it to a basket as a product is refused. It holds no stock and is taxed at the shop's default rate. The label (1 to 60 characters) names the line on the till (customLabelon the line), the receipt page, the confirmation email and the admin order view. Promotions treat it as any other product: an order-wide promotion discounts it, and the promotion exclusions work on it as on anything else. - Donation in pence:
{"skuId": "<donation sku>", "amountInPence": 550}for an open-amount product (a donation priced by the giver). No permission is needed beyond building orders. The line is quantity 1 at that amount, within the product's own minimum and maximum when it has them. A product with a set price answers400. The storefront still takes whole pounds. Gift Aid, the donation record and the sales reports use the line's exact price. An open-amount product's stock counts pounds (a £5 gift is 5 sold), so a donation in pence counts its whole pounds there (£5.50 counts 5): a fundraiser's "raised so far" figure read from stock, rather than from its donations, can be short by the pence. - Discounts:
PUT /v1/basket/{basketId}/lineItems/{lineItemId}/discounton a line orPUT /v1/basket/{basketId}/discounton the whole basket, with{"type": "PERCENT"|"AMOUNT", "value": 10, "reason": "STAFF"|"DAMAGED"|"PRICE_MATCH"|"GOODWILL"|"OTHER", "note": "..."}.DELETEon the same path takes it off. A note is needed forOTHER. NeedscanDiscount. A percentage over the member of staff'smaxDiscountPercent, or an amount over that share of what it comes off, is a403with a message for the till ("That's more than you can take off (up to 10%). Ask a manager."). A donation can't be discounted.
A line priced at the till stays at quantity 1 (changing its quantity is a 400): remove it and add another amount. It is never merged with another line of the same product (adding the same donation again makes a new line), and it isn't carried to another basket (signing in, saving for later, merging accounts) or added back by buy again: it was one amount, chosen at that till. Each change reprices the basket and answers it. If an addition would take the total over the largest sale the member of staff or the shop allows, it is undone and the till gets a 400. Once a card is authorised or taken, or cash recorded, the basket can't change at all: its lines, quantities, prices, discounts and promotion codes answer the one 409 BasketLockedError (reason: PAYMENT_IN_PROGRESS), from the same check every basket change goes through.
How discounts come off. A discount given at the till is kept on the line or the basket with who gave it, the reason and the note. Each time the basket is priced it becomes a discount on the line's price beside any promotion's, marked manual in price.discountSources (no code), so the total, the VAT, refunds, part-cancellation, the receipt and the admin all see it. The order is:
- a line's own discount, off the line's full price;
- the promotions, as without it (a percentage promotion takes its share of what is left);
- the basket discount, off what each line has left: a percentage off each line, or an amount shared across the lines by what each has left. Donations are left out.
Nothing takes a line below zero. A discount stays within its giver's limit. The limit the member of staff had when they gave it is kept with the discount (capPercent; a manager's discount on a colleague's basket keeps the manager's limit), and every repricing holds the discount to it. If the basket gets smaller afterwards (an item removed, a quantity lowered), an amount off is scaled down to the limit's share of what is left rather than becoming a bigger discount: £10 off a £20 basket by someone allowed 50% becomes £5 off when one £10 item is removed. The basket answer's manualDiscount.effectiveValue says what the discount comes to now; when it is less than value, the till can show that and, if the customer should still get the full amount, have someone with a high enough limit give it again. The change to the basket is never refused for this, so a customer handing an item back is never held up by a discount on the basket. The VAT is worked out on what each line is charged after all of them. Cash and card payments are taken for the discounted total, the refund of a discounted line gives back what was paid for it, and the Sales list shows discountInPence (promotions and till discounts together). The admin order view shows each till discount with its reason, note and who gave it.
A sale discounted to nothing. When discounts given at the till take the basket to £0.00, submit it with no body (PUT /v1/basket/{basketId}/submit, not tender: CASH). With nothing to pay and no card taken, it is placed as a paid sale of nothing: no reader, no capture, the payment recorded as taken at £0.00, and the discount and its reason on the order. Only a discount given by someone allowed to take off 100% can make a sale free this way. A basket that is free for any other reason (a promotion, or a promotion together with a smaller discount) still needs a payment.
Cash at the till¶
Staff with canTakeCash can record a sale the customer paid in cash. Cash is an ordinary payment on the order (a v2 payment intent with a cash payment method, recorded as already captured, holding what was handed over and the change), the same way a restaurant table's cash share is recorded. No reader or Stripe call is involved, so a store with no card reader takes cash like any other.
- Cash quick payment:
POST /v1/pos/{locationId}/cashPaymentswithamountInPenceand, optionally,amountTenderedInPence(what the customer handed over; omit it for exact money). The quick payment is created, taxed and numbered as a card one is, and placed at once. The answer (201) carries the order,changeInPenceto give and thereceiptUrl. It passes the card quick payment's checks (see Quick pay):canProcessQuickPayments(which is false when the shop has switched quick payments off), the shop's currency only, the amount within bothpos-max-transaction-amountand the staff member's ownmaxTransactionAmount, and the sale's total being the amount typed (build a basket at a shop whose tax settings change it; the limitation for tax-exclusive shops described there applies to cash too). Too little handed over is a400("That isn't enough."). - Cash for a basket:
PUT /v1/basket/{basketId}/submitwith{"tender": "CASH", "amountTenderedInPence": 2000}, sent withX-Badger-Acting-Asas for any till basket. The basket must be this till's store's, by the store's code (403otherwise). Any card payment still waiting on the reader is cancelled first and read back from Stripe; a card the reader has authorised refuses the cash with a409CARD_TAKEN, and a cancel Stripe won't confirm with a409CARD_CANCEL_UNCONFIRMED(retry in a moment), so a basket is never paid twice. If the submit then fails for any reason, the pipeline refusing the order or anything going wrong, the cash is taken back off the basket and the answer is a409withX-Badger-Error-Code: CASH_SALE_NOT_PLACED: hand the cash back, and the basket can be paid again by card or cash. Once cash is recorded on a till basket, its lines, quantities, promo codes and discounts can't change (409), and the customer's own web session can never pay for or place a till basket. A basket with a subscription line also answers409(SUBSCRIPTION_NEEDS_CARD: a subscription needs a card to renew). OnlyCASH_SALE_NOT_PLACEDmeans the cash must be handed back. In the rare case that the submit pipeline marks the order placed and then reports a failure, the cash stays recorded and the answer is a409with no code: don't hand the cash back, and check the order in the admin. The basket's balance is recorded as cash and the normal submit runs (stock, order number, confirmation email, events), and the answer'sposPaymentsays the change to give. A submit with no body is unchanged. - Retries: send an
Idempotency-Key. A retry with the same key answers the first sale and change rather than recording the cash again; reusing a key for a different amount is a422. Leavingcurrencyout and sending the shop's own currency are the same request. A cash quick payment keeps its key's hash on the sale (unique per shop), with what the request asked for (store, amount, currency, money handed over), so this holds even when the key store is unavailable: the same request answers the first sale, and the key reused for a different sale is still a422. A request without a key is not safe to retry. A quick payment that fails part way leaves no sale: the half-made order is voided. Without the key store, a basket already submitted still answers the already-placed409.
The order pipeline's capture step leaves a till sale alone only when the cash recorded on it is exactly its total and no card on it is authorised or taken; a basket with a card on it always has the card captured, and any other order without a card payment still fails capture as before.
Refunding a cash sale. POST /v1/pos/{locationId}/transactions/{orderId}/refund refunds a cash sale too (it needs canRefund, as for a card). No gateway is involved: the platform records the refund on the sale's cash payment and the order (partly or fully refunded, Gift Aid reconciled as for a card refund), adds an order activity entry POS_CASH_REFUND:<refundId>:<amount>, and answers cashToReturnInPence, the total cash this refund hands back over the counter (cardInPence is 0; a card refund answers the other way round). The refundId is made by the platform (cashrf_...). A refund can't exceed what was paid less what was already refunded, and is written only if nothing has refunded the sale since it was read: two tills refunding the same sale at once can't both pay out. Usually the second gets a 409 with X-Badger-Error-Code: ORDER_BUSY, refunds nothing, and can be retried with the same key once the first has finished. That guard is best effort (it is skipped while the key store is down), so the second can instead be refused by the sale's own records with a 409 and no code: treat any uncoded refusal as "check the sale before trying again". A retry with the same Idempotency-Key answers the refund already recorded, even when the key store has lost it, so the cash is never recorded twice.
Cash is handed over once per key. cashToReturnInPence on a 200 is the total cash this refund (this Idempotency-Key) hands back, not the cash to hand over now. The same key can answer 200 more than once (a replay of a lost answer, a retry after IDEMPOTENCY_KEY_IN_FLIGHT, or a retry once the stored answer has expired) and always with the same total. The app hands the cash over once per key: it remembers, per key, how much it has already told staff to hand over, and shows only any difference. No refusal ever asks for cash to be handed over. A replayed answer is the first answer, field for field, so its refundedAmountInPence and refundableAmountInPence are the sale's totals as they were at the first answer, not now: to show the sale's current figures, read the sale. These guarantees hold only when every retry sends the identical request: see Retrying a refund. Never reuse a key for a different refund.
Refunding a sale paid more than one way. A basket can be paid on two cards, and a sale can carry cash beside a card. A refund goes back to the cards first, newest card first, each up to what is left on it, then in cash for the rest. Each card gets its own Stripe refund, keyed on the till's Idempotency-Key and that card, so a retried refund can't refund any card twice. If one card's refund fails after another's went through, the order records what went back, and a retry with the same key finishes the original request: what was already refunded for it is taken off first, so it never refunds more than was asked. The answer says how it was split: cardInPence went back to cards, cashToReturnInPence is to hand back over the counter (tender is CASH when any of it is cash). The sale's refunded total and its partly or fully refunded state count every card and the cash together. If a refund stops after some of its money has gone back or been recorded (a card refunded and the next one failing, the order's hold lost between cards or while recording them, or the cash part refused or cut off part way), the answer is a 409 with X-Badger-Error-Code: REFUND_PART_DONE. Its sentence says how much has gone back to cards. Hand over no cash on a 409, or on any other refusal of a refund. Cash is handed over only on the 200 that finishes the refund, and that answer's cashToReturnInPence is all the cash for the refund, including any part the platform recorded during a refused attempt: the platform can't know whether cash left the drawer, so a refused attempt never asks for any. Send the same request again with the same Idempotency-Key: what already went back under it is counted, not repeated, and only the rest is given back or recorded. If it is refused again (another refund may have used up what was left), check the sale. Never start a new refund for it: it doesn't know what this one gave back, so the customer could get back more than they are owed. This covers a cash refund spread over two cash payments on the sale and cut off between them too: each part written is recorded under the refund's key (an activity entry POS_CASH_REFUND_PART:<refundId>:<amount> before the final POS_CASH_REFUND one), so the retry counts the parts already recorded and records only the rest; its answer's cashToReturnInPence is still the whole cash amount. A refund that is refused on a retry before it has counted what earlier attempts gave (the order held by another change, or Stripe or the database failing) can answer another 409 or a 5xx instead of REFUND_PART_DONE: treat any refusal of a refund the same way, hand over no cash, and send the same request again with the same key or check the sale. Every refund needs an Idempotency-Key (400 without one) for this reason.
An answer for less than was asked. A 200's amountInPence is what the refund gave back (cardInPence plus cashToReturnInPence), never more than was asked or than the platform recorded for it. It is less than was asked only when a refund that had already recorded some cash under its key is retried and less can be given than the rest of it:
- the cash part was cut off part way (
REFUND_PART_DONE) and, before the retry, another refund of the sale gave back some of the cash that was left: the retry gives what is left and finishes; - a card refund of this refund answered
pendingand later failed, and before the retry some of that card's money went back another way (another refund, or the Stripe Dashboard): the card can now take less than before, and the cash recorded earlier stays what it was.
The refund is then finished, for what it says; check the sale before giving anything more back.
A card refund Stripe turns down. Stripe can answer a card refund failed or canceled (an expired or closed card, say). That refund gave nothing back, so it is never counted: not in the answer, not on the order, and its share is never handed back in cash instead. The request stops at that card. If nothing has gone back, the answer is a 409 with no code and a sentence saying the card refund didn't go through; if an earlier card had already gone back, it is REFUND_PART_DONE. Either way the request isn't recorded as done, so sending the same request again with the same key tries that card again, with a new Stripe refund (a refund that went back, or is still pending, is never made again). The turned-down refund is recorded in the sale's activity (POS_CARD_REFUND_FAILED:<refundId>:<amount>:<status>). A refund Stripe answers pending counts as going back, as status: pending in the answer says. If a pending refund later fails at the card network, the platform doesn't yet act on it: the sale still shows it as refunded. To give that money back, make a new till refund (a new key) for the amount that didn't go back. A card's refundable amount is read from Stripe, which doesn't count the failed refund, and refunds go to the cards first, so the new refund sends that amount back to the card (or, on a sale paid on two cards, the cards whose refunds failed) and no cash; cash already recorded on the sale stays recorded. Don't send the original refund again as well. This is the opposite of REFUND_PART_DONE: there the refund never finished, so the same key finishes it and a new refund must not be started; here the refund finished (200) and only the card network turned it down later, so a new refund gives back what didn't arrive.
Retrying a refund. A retry of any refund with the same Idempotency-Key and the same body answers the first refund, or finishes one that stopped part way. A reason left out, empty or only spaces counts as no reason, and spaces round a reason are ignored.
A retry must send the identical request (the same amountInPence, or none, and the same reason) with its key. The server does not reliably detect a changed request:
- The same key with a different
amountInPenceorreasonis a422only while the key store holds that key's completed answer (kept for 24 hours) or its in-flight marker. - Every refusal of a refund,
REFUND_PART_DONEincluded, frees the key, and an answer that has expired or been lost (or a key store that is down) is no guard either. A different request sent then under the same key is not refused by the key store. It is worked out from what the key already did, and the answer is not safe to act on. On a card sale, a larger amount refunds the difference, up to what is still refundable (Stripe refuses it only while it still holds that card's key with other parameters). A smaller amount on a sale paid by card, or by card and cash, can answer figures that don't add up: a £25 refund of a sale paid £20 by card and £5 in cash, stopped after the card went back and resent as £15, answersamountInPence1500 withcardInPence2000 andcashToReturnInPence0, and records no cash. - One case is refused with
422even then: a sale paid only in cash, sent with anamountInPencesmaller than the cash already recorded under that key (the key was used for a larger refund). This is not a general guard: a card, or card and cash, sale, or the same or a larger amount, is not caught.
The guarantees about a key's answers (the same cash total on every 200, amountInPence equal to cardInPence plus cashToReturnInPence, never more than was asked) hold only for identical retries. Never reuse a key for a different refund, and never change a request you are retrying.
Taking part of a sale in cash and the rest by card, cash floats, drawers and cashing up are not supported yet.
Sales of either kind appear in GET /v1/pos/{locationId}/transactions and feed the GET /v1/pos/dashboard summary used on the app's home tab. Each sale row says how it was paid (tender: CARD or CASH; a sale from before tenders were recorded reads CARD), with amountTenderedInPence and changeInPence for cash, and the sale's currency (the sale's own, in lower case). A row has a receiptUrl only when the sale took money (saleStatus PAID, PART_REFUNDED or REFUNDED); a sale that was never paid, or whose payment failed or was voided, has no receipt.
Sales list. The store's sales, matched by the store's code (a store without a card reader lists its cash sales the same way). Rows come newest first (by when the sale was started, then by id), paged with pageNumber and pageSize; totalElements and totalPages count what matches. By default only sales that took money are listed, by the dashboard's rule: placed, and not failed or voided (saleStatus PAID, PART_REFUNDED or REFUNDED). Send includeUnpaid=true to see the rest too (a basket still being built, a card waiting on the reader, a payment declined or cancelled, saleStatus NOT_PAID or PAYMENT_FAILED), for looking into a problem. tender=CARD|CASH narrows to one way of paying (for cashing up). q searches what the cashier types: a sale number (exact, or the start of one), an amount (12.50, 12,50 or £12.50 in pounds and pence; digits alone, such as 1250, in pence), the last four digits of a card, or text in a line's note (as typed, ignoring case). A sale has no note of its own, only its lines.
Dashboard. GET /v1/pos/dashboard counts the stores the caller may sell at: an agent sees only its own stores' takings, never another store's. An admin without a staff record, and an agent with no stores of its own on a shop with at most one store that sells in person, see the whole shop. locationId (a store's code or Stripe location) narrows it to that store, if the caller may work there (403 otherwise). The totals count till sales placed in the window that took money: a sale whose card payment failed or was voided is left out of the totals, the cash and card split, the active staff and the top products. The totals are gross (what the sales were for); todayRefundedInPence and weekRefundedInPence say what has been given back so far on those same sales, so the net takings are one less the other. todayCashInPence / todayCardInPence and weekCashInPence / weekCardInPence split the totals by tender. An order payment from an order that is partly collected and partly delivered has splitHandover: true with collectItemCount and deliverItemCount (units each way, cancelled lines left out), so the app's Orders list can show Split: 1 to collect · 3 delivered without loading each order; other rows have splitHandover: false and no counts.
If the site has never finished Stripe Connect onboarding, POST /v1/pos/{locationId}/connectionToken (and the other Terminal endpoints) return 503 Service Unavailable with a body naming the site and X-Badger-Error-Code: STRIPE_NOT_CONFIGURED — the app should surface "Stripe is not set up on this site — contact your admin" rather than retrying or treating it as an authorisation failure.
Building a basket on behalf of a customer (impersonation)¶
For the order-build flow the agent needs to make basket calls — PUT /v1/basket, PATCH /v1/basket/{id}/{lineItemId}, POST /v1/basket/{id}/paymentIntent, PUT /v1/basket/{id}/submit — that operate on a customer's basket, not the agent's own. The platform supports this via an impersonation header rather than a separate impersonation login.
Header: X-Badger-Acting-As: <userId>
When present, the request runs as that user. The platform validates the request first:
- the authenticated principal must hold
POS_AGENTwithcanBuildOrderson the current site; - the target user must exist and belong to the same site (
siteGroupId).
Anything else — a non-POS principal trying to impersonate, an agent without canBuildOrders, an unknown/foreign userId — is rejected with 403/404 and an audit log line: POS impersonation: agent=… acting-as=… site=… path=….
The header is only accepted on the basket calls a till sells through: /v1/basket and the paths below it. On any other path it answers 403 and the request isn't run, because there it would give the till the customer's own account (their profile, their tickets).
When the customer has an account (registered, rather than a walk-in guest), the till can only start new sales for them:
- their own basket is refused with
403:GET,PUTorDELETE /v1/basket, and aPOST /v1/basketwithassociateWithUser=true, which would make the new basket theirs; - by id, the till sees only till sales (
POS_ORDER,POS_QUICK_PAY). Their web orders and baskets answer404, as an order of someone else's does.
A walk-in guest exists only for the sale, so its calls are unchanged. Orders created during an impersonated request automatically record createdByAgentId (the principal) and default their channel to POS_ORDER, so they show up in POS dashboards.
The header is stateless — there is no impersonation session, no cookie, no "exit impersonation" endpoint. Closing one customer and opening another is simply a matter of changing what the app sends on the next request, the same way a fresh browser tab gives a new session.
At the start of each sale the app should call POST /v1/basket to mint a fresh basket rather than relying on PUT /v1/basket to find-or-create. The platform stamps createdByAgentId and channel = POS_ORDER at order creation; calling POST guarantees that stamp happens on the basket you're about to build, even when impersonating a returning customer who already has a stale basket from a previous web session.
Walk-in customers¶
In-store walk-ins typically have no User record. The app mints a fresh guest User on demand:
Returns { "userId": "..." } — a freshly-created anonymous User scoped to the site. The agent uses that id as X-Badger-Acting-As for every subsequent basket call in this sale. The guest is a real User document with registered=false, so the resulting Order has a proper owner and the agent's own order history stays uncluttered.
Customers with an in-store card¶
A customer with an account on a shop with the till on (pos-enabled) has an in-store card on their account overview: a QR code they show at the till, so the sale joins their order history and its receipt goes to their own email address. The card identifies the customer, like a loyalty card or a charity shop's Gift Aid card; it doesn't sign them in, and acting for them a till can only start new sales (above).
The QR code's text is bdgr-card: and a random 16-character code (Crockford base32, 80 bits), not the customer's id. The code is given to them the first time they open their account page, is stored on their user (tillCardCode), and can be replaced from the card (Get a new code); the old code then stops working at every till.
The card can also go into the customer's Apple Wallet or Google Wallet, from the buttons under the code (TillCardWalletService). It uses the platform's wallet credentials, the same as ticket passes, so the buttons appear wherever those are set up. The pass shows the shop's name, colour and logo (chosen as for ticket passes: the design brief, a set email colour, then the theme's colour; SVG logos are drawn as images), the customer's full name and the day they registered ("Member since", in the shop's time zone), each under its label, and the same QR code with the code beneath it. The full name is only on the pass, on the customer's own phone: a till still shows staff the first name and surname initial. The pass never shows their email. On Apple it's a store card. On Google it's a generic pass, with one class per shop (<issuer>.<siteId>-tillcard). Each pass is named by a hash of the shop and the code (tillcard-<hash>), so the code itself never appears in an id.
Getting a new code makes a new pass. The old Google pass is marked inactive in the background (TillCardWalletReplacedListener). An old Apple pass stays in Wallet, because Apple passes aren't updated (there's no pass web service), but a till no longer recognises it. Its back says so, and the account page asks the customer to add the card again.
Takes what the till scanned (or the code typed in, with or without the prefix, in either case) and answers { "userId", "displayName", "emailHint", "giftAid": { "onFile" } }: the id to send as X-Badger-Acting-As, and "Jane D." and "j•••@example.com" so staff can check it's the person in front of them. Nothing else from the account is returned.
giftAid.onFile is true when the customer has a Gift Aid declaration on their account for this shop with their whole name, house name or number and a valid postcode. Declarations don't lapse, so an old one counts. A donation on a sale built acting as them is then claimed under that declaration, with its name and address, and the till asks the donor for nothing: it sends no billing address (an address on the order would be claimed instead), and the line's giftAidAcceptance can be sent or left off. When it is false, the till asks for the declaration and sends the donor's name and billing address with PATCH /v1/basket/{basketId}/personalDetails, as for a walk-in; that declaration is then saved on the customer's account, so their next scan answers onFile: true. The flag carries no part of the declaration. A card no customer of this shop has (or one that was replaced) answers 404; staff whose profile has canScanCustomerCards false get 403. Each scan is logged by agent and customer id only.
A basket built for a scanned customer starts with their own name, email address and mobile number, never their address (Customer details and receipts).
Customer details and receipts¶
POS orders skip the web checkout's personal-details step, so the platform seeds the order's contact details at creation: a named (impersonated) customer's own saved name/email are copied onto the order, and a true walk-in (every quick payment included) falls back to an "In-store customer" placeholder. Because a walk-in placeholder carries no email, the confirmation and dispatch email steps skip silently for it (recording a CONFIRMATION_EMAIL_SKIPPED_NO_RECIPIENT activity entry) rather than failing the submit — so a receipt only goes out when there is actually somebody to send it to. To email a walk-in their receipt, capture an address on the basket (PATCH the personal details) before submit, or send it afterwards as below.
Every paid till sale has a receipt page on the shop's storefront, /o/{orderId}/{confirmationCode}: the receiptUrl the capture, cash payment, cash submit and Sales rows answer (absent when the shop has no domain, and on a Sales row whose sale didn't take money). It reads as a receipt, without addresses; a quick payment's one line shows as In-store payment, and a cash sale's payment as Cash.
POST /v1/pos/{locationId}/transactions/{orderId}/receipt emails the shop's standard order confirmation for a paid sale at that location (202). A sale with a customer's own email address goes to that address only: send no body to use it, and any other address is refused (409), since the confirmation carries the customer's name, address and what they bought. A walk-in sale (the placeholder) needs {"email": "..."}, and the address is then saved on the order as the customer's. A sale's receipt can be sent at most 3 times an hour, and a member of staff can send at most 30 receipts an hour across all sales (429 beyond either); the address is never logged, and the order's activity records a POS_RECEIPT_SENT entry without it. The email is queued for the worker like every other order email, so it works from the API.
Card details captured at capture¶
When a card-present capture succeeds, the platform reads the Stripe Charge that backs the intent and writes the following onto the order's StripePaymentMethod:
- card identity — brand, last 4, expiry (month/year), network, issuer country, funding type, Stripe fingerprint;
- cardholder name — the ISO 7813 name printed on the card, available for contact/contactless EMV but not for Apple Pay / Google Pay;
- EMV receipt fields — authorization code, application preferred name, dedicated file name, terminal verification results.
All of these are PCI-safe to persist long-term — none are PAN or sensitive authentication data. They are critical for the no-receipt order lookup workflow: when a customer returns asking about a recent in-store purchase, the operator can identify the order from card last 4 + amount + timestamp without having issued a paper receipt.
The enrichment happens synchronously at POST /v1/pos/{locationId}/paymentIntents/{intentId}/capture via PosService.recordCapturedPaymentIntent. The charge.succeeded Stripe webhook handler (ChargeSucceededHandler in the worker) backstops missed enrichments idempotently — for example after a server crash between Stripe capture and the DB write, or for captures performed directly on the Stripe dashboard.
Admin visibility¶
In-store sales are flagged throughout the admin:
- the order list shows a
POSbadge next to the order number for any non-web channel; - the order detail page shows an In-store (POS) badge by the heading;
- the Payment Intents (V2) panel tags a card-present intent as In-store, and the panel now reflects the capture (status
CAPTUREDwith the captured amount) even when the legacy Stripe Terminal capture path is used.
Example flow¶
POST /v1/pos/walkin-customers
→ 201 { "userId": "65f1c2d3e4b7a2a5c8d9e3f4" }
PUT /v1/basket
X-Badger-Acting-As: 65f1c2d3e4b7a2a5c8d9e3f4
{ "skuId": "sku123", "quantity": 1 }
→ 200 (basket with line item, owner = 65f1c2d3…)
POST /v1/basket/{basketId}/paymentIntent?paymentType=card_present
X-Badger-Acting-As: 65f1c2d3e4b7a2a5c8d9e3f4
→ 200 { "thirdPartyId": "pi_…", "paymentToken": "pi_…_secret_…", "status": "READY_FOR_AUTH" }
(reader collects + confirms with paymentToken)
PATCH /v1/basket/{basketId}/paymentIntent/pi_…
X-Badger-Acting-As: 65f1c2d3e4b7a2a5c8d9e3f4
→ 200 { "status": "AUTHORISED" }
PUT /v1/basket/{basketId}/submit
X-Badger-Acting-As: 65f1c2d3e4b7a2a5c8d9e3f4
→ 200 (order submitted + payment captured; createdByAgentId = the agent, channel = POS_ORDER)
Barcode scanning¶
Products and variants carry a barcodes list (EAN/UPC/GTIN/ITF-14 etc.). A single endpoint resolves a scanned code to the right product — and to the right variant when the code lives on one.
Why a list, not a single code¶
A single SKU routinely carries more than one valid barcode in the wild:
- inner vs outer pack — EAN-13 on the unit, ITF-14 on the case;
- legacy vs current — older supplier codes still circulating alongside newer GS1 GTINs after a re-sleeve;
- manufacturer GTIN revisions where both codes are valid in the channel for a period;
- promo packs with a temporary code that maps to the same underlying SKU.
Modelling barcodes as a list means a cashier can scan whichever code happens to be on the unit in front of them without the POS app having to handle a "no match, ask the cashier to pick" fallback for every legacy case.
Editing barcodes¶
Admin → product Data tab carries a Barcodes editor. Add one row per valid code. Variants have their own editor on the variant Data tab — when a variant carries its own GTIN (typical for size/colour variants), a POS scan of that code resolves directly to the variant's SKU.
The legacy Product.upc field is still populated and writable for back-compat with existing integrations; the lookup unions it with barcodes automatically so existing data resolves without migration.
REST: resolving a scan¶
GET /v1/pos/products/by-barcode/5012345678900
→ 200 {
"product": { "id": "…", "skuId": "TSHIRT-CLASSIC", "name": "Classic Tee", … },
"matchedVariantSkuId": "TSHIRT-CLASSIC-L" // present only if the code lived on a variant
}
When matchedVariantSkuId is set, the POS app should add that SKU to the basket. Otherwise, fall back to product.skuId. A variant match wins over a parent-product match: it's the more specific signal about what the cashier actually scanned.
Returns 404 if no product in the current site carries the code, 403 if the user is not a POS agent, 503 if POS is not configured on the site.
Reference¶
For the authentication design, the app architecture and the original implementation plan, see the in-repo deep dive: Mobile POS feature plan.
Stripe Terminal locations per store¶
Each location that sells in person can be linked to its own Stripe Terminal
location, which its card readers belong to. From the location's admin page a merchant creates the
Stripe location from the store's name and address (or enters an existing tml_... id), pushes
later name and address changes to Stripe, sees the readers registered there (with the till holding
each Bluetooth reader) and renames them. The calls go through StripeTerminalService
(createLocation, updateLocation, retrieveLocation, listReaders, updateReaderLabel) on the
site's own Stripe account, connected account included,
in its current test or live mode, orchestrated by TerminalLocationSyncService. None of it is
automatic: saving or importing a location never creates or changes anything on Stripe. See
Card readers and Stripe Terminal.
Collection tasks¶
A store's orders to collect show in the app as tasks, under /v1/pos/{locationId} (the store's
code or Stripe Terminal location id; the agent must be allowed to work there, 403 otherwise). See
Collecting an order for the lifecycle behind them.
| Call | Does |
|---|---|
GET /tasks?status=open\|ready\|done&type=COLLECTION\|SHIP\|ALL |
{tasks: [PosTask], counts: {toPrepare, ready, arrived, shipToPrepare, shipReady}}. type defaults to COLLECTION (see Ship tasks). open (default): not ready yet, oldest first. ready: waiting for the customer, oldest first. done: handed over today in the store's time zone (else the site's), newest first. arrived counts customers who said in the last three hours they're outside. A store with no collections gets an empty list and zero counts |
GET /tasks/{orderId} |
One PosTask, a collection or a ship task |
POST /tasks/{orderId}/lines/scan {code} |
Adds one to pickedQuantity of the first line the code matches that isn't fully picked: a barcode on the product or variant, or the line's SKU (the app's "+1" sends the SKU when a line has no barcode). 404 if nothing on the order matches, 409 if every match is already picked |
POST /tasks/{orderId}/lines/unscan {code} |
Undoes a wrong scan: takes one off pickedQuantity of a line the code matches, matched as for a scan. Where the code matches several lines, the last of them with something picked (the line a scan would have filled last). Allowed whenever a scan is; the quantity never goes below 0. 404 if nothing on the order matches, 409 (plain text) if nothing matching has been picked or the order is no longer being prepared. Each call takes one more off |
POST /tasks/{orderId}/lines/{lineId}/short {quantity?, reason: OUT_OF_STOCK\|DAMAGED\|OTHER, note?, substituteSkuId?, substituteQuantity?} |
"Can't find it": marks units of a line short (default: everything on it still to pick). See Items that can't be picked. Allowed whenever a scan is. Optional Idempotency-Key. 409 ORDER_BUSY while another short pick on the order is under way: retry with the same key |
DELETE /tasks/{orderId}/lines/{lineId}/short |
Undoes the shorts on a line while the order is still being prepared and nothing has been refunded or told to the customer; 409 otherwise (409 ORDER_BUSY while another short pick on the order is under way: retry) |
POST /tasks/{orderId}/ready |
Marks it ready and emails the customer (once), whether or not every line was scanned. Optional Idempotency-Key |
POST /tasks/{orderId}/collect {check: CODE\|NAME, code?} |
Hands it over. With CODE the code must match the order's, ignoring case, spaces and hyphens (422 otherwise). An order not yet ready is packed on the way. Optional Idempotency-Key |
GET /arrivals |
{arrivals: [PosTask]}: customers who said in the last three hours they're coming or here, newest first |
POST /tasks/{orderId}/arrival/claim {message?} |
"I've got this one": the signed-in member of staff is bringing a waiting customer's order out. Only while the order is ready and the customer has said they're coming or here, and only one person: a colleague who tries afterwards gets 409 ("A colleague is already bringing this order out"). Claiming again as the same person keeps the claim and its time and replaces the message, so a retry is harmless (no Idempotency-Key). message (at most 140 characters, plain text) is shown on the customer's arrival page |
DELETE /tasks/{orderId}/arrival/claim |
Lets go of your own claim (called away), so a colleague can take it and the customer's page stops saying someone is coming. Only the claimant can (409 otherwise); releasing a claim nobody holds changes nothing |
A PosTask is {orderId, orderNumber, type: COLLECTION|SHIP, status:
TO_PREPARE|READY|COLLECTED|DISPATCHED|CANCELLED, customerName, placedAt, readyBy, holdUntil,
collectionCode, lines: [{lineId, skuId, name, variantLabel, quantity, pickedQuantity, barcode,
imageUrl, handover: COLLECT|SHIP, orderedQuantity, shortQuantity, shortReason, location: {aisle, bay,
shelf}, substituteFor: {skuId, name}}], arrival: {state: ON_THE_WAY|ARRIVED, eta, bay, vehicle, at,
claimedBy: {agentId, displayName}, claimedAt, claimedByMe, claimMessage} | null, kerbside,
shipping, slot, readyFrom, deliveredItemCount, deliveredLines, shortLines, cashToHandBack}; shipping is set on ship tasks only (see below). slot is {type:
CLICK_AND_COLLECT|STORE_DELIVERY, date: YYYY-MM-DD, start: HH:mm, end: HH:mm, locationCode} when
the customer chose a collection or own-van delivery slot (dates
and times the store's own, in its timeZone), absent otherwise; group or sort the day's work by
it. readyFrom (collection) is the earliest the customer was told to come, a later "ready from"
day's opening or the slot's start; readyBy is the same time then. Absent when it's ready as soon
as it's prepared. It carries the customer's name and code for the member of
staff; the app shouldn't show it to anyone else.
Each line's handover says how it reaches the customer: COLLECT for every line of a collection
task's lines (handed over at the counter), SHIP for a ship task's lines.
Part collected, part delivered. When the customer collects only some of an order and the rest
is delivered, the collection task's lines are only the items to collect, and
deliveredItemCount says how many units are being delivered instead (the delivered lines'
quantities, cancelled ones left out). deliveredLines lists those lines, with handover: SHIP
and pickedQuantity 0, for context only: nothing in them is picked, scanned or handed over at the
counter, and a scan of one of them is refused like any item not on the task. Its status is the
collection's own: ready and collect move only the collected items, and the order stays open until
the delivery has gone too. deliveredItemCount is 0 and deliveredLines empty on any other task.
In the Badger POS app, the task screen of such an order shows only the items to hand over, with a note underneath: 1 more item is being delivered (or 3 more items are being delivered), the delivered items by name, and Not collected here: nothing to pick or hand over. At handover the note reminds staff to tell the customer the rest is being delivered. Task rows add +1 being delivered, so nobody goes looking for the pallet.
Bringing it out. On an arrival, claimedBy is the member of staff who said they're bringing
the order out (displayName is their POS staff name, else their account name), claimedAt when,
and claimedByMe whether it's the person looking. Absent while nobody has. A colleague's claim is
not pushed to the other tills: the app sees it on its next look at /arrivals or the task (every
30 seconds is enough), and the claim itself stops a second person, who is refused. The customer's
next "I'm here" keeps the claim.
An order collected from another store, or not collected at all, is 404 ("That order isn't one for
this store to hand over"). Refusals (400, 404, 409, 422) are short plain-text sentences the
app shows the cashier as they are. Ready and collect can be retried safely with the same
Idempotency-Key: a repeat returns the task as it stands.
Where things are: pick lists in walk order¶
A store can record where it keeps each item: an aisle, a bay and a shelf (each up to 20
characters), and optionally a walk sequence. Each task line then carries location: {aisle, bay,
shelf} (absent when the item hasn't been placed; a variant with no place of its own is shown where
its product is), and the lines come in walk order: by walk sequence where one is set, otherwise
aisle, then bay, then shelf, read the way people read them (aisle 2 before aisle 10); lines with no
place come last, in their usual order. A store that hasn't placed anything sees its lists exactly as
before.
Places are set on the admin product screen's stock grid, from a CSV on the location's admin page
(see Locations), or from the till by a picker who has found
an item: PUT /v1/pos/{locationId}/stock/{skuId}/placement {aisle?, bay?, shelf?} (needs
canAdjustStock; all blank removes it; the walk sequence is kept). The stock list
(GET /v1/pos/{locationId}/stock) gives each row its placement too, and takes aisle (only what
is kept in that aisle) and sort=walk (that aisle in walk order; walk needs an aisle).
Items that can't be picked¶
When a picker can't find an item, or finds it damaged, they mark it short:
POST /tasks/{orderId}/lines/{lineId}/short {quantity?, reason, note?}. quantity is at most
what is still to pick on the line (400 otherwise; 409 when everything on it is already picked,
so take a unit back off first); left out, it is everything still to pick. The note is for staff and
never reaches the customer.
- The units are cancelled. A line always carries a whole quantity, so units short from part of
a line are split off into a cancelled line of their own carrying their share of the line's price
(after any promotion or discount). The task line keeps the rest:
quantityis what is left to pick,orderedQuantitywhat the customer ordered,shortQuantityandshortReasonwhat is short. A line short in full leaveslinesforshortLines. - The customer doesn't pay for them. A payment already taken is refunded their price. A payment
only authorised (taken when the order is collected or sent) is captured that much less later:
the customer is never charged and then refunded. If part of an authorised payment is on a gift
card and the card authorisation can't absorb the reduction, the short is refused (
409) and the items are cancelled from the admin once the payment has been taken. An order paid in cash at the till records the refund against the cash, andcashToHandBacksays what to give back when the customer collects. - If nothing is left, the whole order is cancelled (refunded, or its authorisation released), so it never reads as sent.
- Stock. Nothing is put back: the goods aren't there.
OUT_OF_STOCKsets the store's figure for the item to 0, as a gap check would; the order's units came off that figure when the order was paid for, so nothing is taken off twice.DAMAGEDleaves the figure (the damaged units were the order's) and records the write-off.OTHERleaves stock alone. Only when the order's stock was taken from this store. Each change is in the stock history, from sourceSHORT_PICK. - The customer is told once, when the order is made ready or packed (or handed over or sent without that), however that is done: on the till, in the admin, in the fulfiller portal or through MCP. One email covers every item that couldn't be picked, with the refund, the amount they won't be charged or the cash to collect, any substitutes, and what is still coming. An item found short after that is emailed straight away, as is a short that cancels the whole order.
- Undo.
DELETE /tasks/{orderId}/lines/{lineId}/shortputs the units back on the line, gives back a reduced authorisation and restores the stock figure the short changed, while the order is still being prepared, before anything has been refunded or is owed in cash, before the order's payment has been taken and before the customer has been emailed. Otherwise409, saying why ("The payment for this order has been taken, so a short can't be undone now"). - One change at a time. While a short (or an undo) changes the order, other changes to it are
held off for a moment: a scan or un-pick is refused with
409("Someone is changing this order. Scan it again in a moment."), so it is never lost, and so is a cash refund at the till, so a refund recorded at the same moment is never overwritten. A short that finds the order already being changed is refused the same way ("Someone is changing this order. Try again in a moment."). The hold belongs to whoever took it: only they can let it go, and a change whose hold was lost (it ran past its time and someone else took the order) is refused rather than written over theirs. It lasts ten minutes, longer than the slowest change made under it; if a till dies mid-change, the order's scans wait until then.
Substitutes. Where the shop allows it (Allow substitutes when an item can't be found,
pos-allow-substitutions, off by default; allowSubstitutions on GET /v1/pos/agents/me tells
the app), a short can name something to pick instead: substituteSkuId, and substituteQuantity
(default: all the short units; any left over are cancelled as above). The substitute must be on
sale, not an open-amount, gift card, donation, subscription or till system item, taxed with the
same tax code as what was ordered, and this store must hold enough of it; otherwise 409.
- Its units become a line of their own, already picked, with the substitute's SKU at the price of
what was ordered: the customer never pays more, and the order's lines still add up to its price.
The task line carries
substituteFor: {skuId, name}(what was ordered). - When the substitute's own price is lower, the difference is given back as a short's money is:
refunded, captured that much less, or added to
cashToHandBack, and the swapped line's price (and the order's, with its tax) comes down by the same amount, shown as a discount on the line. A later cancellation or return of that line gives back what was paid for it, not the ordered price again; undo puts the price back. A dearer substitute costs the customer nothing more. - Its stock is taken from this store (and recorded, so a later cancellation or return puts it back); the ordered item's stock is corrected as for any short.
- The email lists it as picked in place of what was ordered. Undo puts the ordered item back and the substitute's stock back on the shelf figure, under the same rules as any short.
Each short is recorded in the order's activity (line, quantity and reason, and for a substitute
the SKU and the difference; no names). A retry with the same Idempotency-Key changes nothing.
Push. Devices registered at the store with an Expo push token are sent new-store-task,
customer-on-the-way and customer-arrived notifications (with channelId: "default" for
Android), each linking to badgerpos://tasks/<orderId>. data.taskType says whether a
new-store-task is a COLLECTION or a SHIP task. Push is off unless the global
pos-push-enabled is on; see Push notifications.
Restaurant kitchen and drivers¶
A restaurant's orders for collection or local delivery go to its kitchen in the app, under
/v1/kitchen/{locationId} (a location code; tag Kitchen in the API reference). The agent needs
canAcceptOrders (kitchen staff) or canDeliverOrders (drivers) and the location among its
locationCodes; an admin without an agent record may work in any kitchen. /v1/pos/agents/me
carries both flags, the user's userId (to compare with an order's driverAgentId) and kitchens,
the kitchens the user may work in. A kitchen needs no Stripe location. An agent assigned the kitchen gets
its pushes on every device it registered, wherever that is (a manager whose till is another store still
hears the kitchen); an admin without an agent record registers the device at the kitchen
(PUT /v1/pos/{code}/devices/{deviceId}).
| Call | Who | Does |
|---|---|---|
GET /orders?status=new\|active\|done |
either | Orders and counts for the three lists |
GET /orders/{orderId} |
either | The ticket: lines with choices, notes and allergens. The customer's first name always; their phone once accepted; the delivery address once accepted, and only for a delivery. Neither after a rejection |
POST /orders/{orderId}/accept {prepMinutes} |
kitchen | Takes the payment and sets the promised time (502 if the payment fails; the order stays waiting) |
POST .../reject {reason?} |
kitchen | Cancels and refunds; the reason is shown to the customer |
POST .../ready, .../collected |
kitchen | Ready; handed over at the counter |
POST .../undo |
kitchen | Takes a mis-tap back one step: ready → preparing, or a collection's collected → ready, within the shop's undo window (kitchen-undo-window-minutes, 5 by default; 0 turns undo off). Nothing else can be undone (409). Only the order's place on the board goes back, with an undo: true entry in its history: its packing, the payment and any email the customer was sent stay as they were, and marking it ready or collected again doesn't repeat them. A driver is told again when a delivery is marked ready again. The customer's tracking page drops the undone step. A retry of the earlier ready or collected with its old Idempotency-Key answers the order as it now is without moving it: mark it again with a new key |
POST .../outForDelivery |
driver | The caller becomes the driver |
POST .../delivered |
the order's driver | 403 for anyone else; the driver's position is dropped |
PUT .../driverPosition {lat,lng} |
the order's driver | About every 30 s per order; more than 6 a minute for one order (badger.kitchen.rate-limit.driver-position-per-minute), or 60 a minute from the driver across orders (...-per-minute-all-orders), answer 429 |
GET /status, PUT /pause {paused?, minutes?} |
either; kitchen | Open, closed or paused, next opening, and the current preparation estimate |
GET /stock |
kitchen | What the kitchen has run out of: the items counted at none where its tables take their stock, by name (at most 200), so they can be put back on during service. Empty when the shop's stock system can't list low stock |
GET, PUT /stock/{skuId} {onHand} |
kitchen | How many of a dish or drink are left where the kitchen's tables take their stock, and the kitchen's own count: 0 marks it gone (sold out on the menu straight away), a number puts it back on with that many, null stops counting it (only where the stock is the main location's). A restaurant that keeps its own stock always counts, and can't count an item the main location doesn't |
Moves take an optional Idempotency-Key, as the POS calls do (409 while the first is running,
422 for the same key with a different body). Refusals are short plain-text sentences.
Push. With pos-push-enabled on, these go to the devices registered at the kitchen whose agent has the
matching flag (or that an admin registered), and to every device of an enabled agent assigned the kitchen
with that flag, wherever it registered. Each device gets one copy:
data.type |
To | When | Sound / category |
|---|---|---|---|
kitchen-new-order |
kitchen | a new order is waiting | kitchen_alert.wav, kitchen-new-order |
kitchen-order-reminder |
kitchen | still waiting at half the accept timeout | kitchen_alert.wav, kitchen-new-order |
kitchen-auto-rejected |
kitchen | nobody accepted in time | default |
kitchen-ready-for-delivery |
drivers | a delivery order is ready | default, kitchen-delivery |
All use the Android channel kitchen-orders, priority high, and (except the rejection)
interruptionLevel: "time-sensitive". data is {type, orderId, orderNumber, locationCode, state,
method: COLLECT|DELIVERY, url: "badgerpos://kitchen/<locationCode>/orders/<orderId>"}. Titles and
bodies are in the shop's language and carry the order number, total and time at most ("New order
1042", "£23.50, delivery for 18:45"), never the customer's name or address.¶
Tables on the kitchen board (table service). GET /v1/kitchen/{locationId}/tickets?station=
returns the merged board (a dining room with the DINE_IN capability is a kitchen here too): takeaway
orders (kind ORDER), tables' courses being made or at the pass (FIRE: tableLabel, covers,
course, fireNumber, away when the server called it, lines with seat, course, fireState) and
held courses (HELD, greyed), plus the dining room's stations for a picker. With a station, a table's
tickets keep only that station's lines and a FIRE is READY once those are; the bar sees no takeaway; a
pass sees whole courses. POST /v1/kitchen/{locationId}/fires/{fireId}/ready|served|recall?station=
with an optional {lineIds} bumps (or brings back) single lines; the course is READY when all its
lines are; served takes the whole course. Both need canAcceptOrders and take an Idempotency-Key.
data.type |
To | When | Sound / category |
|---|---|---|---|
dining-fire |
kitchen (canAcceptOrders at the location, or assigned it) |
a table's course is sent or called away | kitchen_alert.wav, dining-fire |
dining-food-ready |
the table's server (every device of serverUserId) |
a course is ready at the pass, once per course | default, dining |
A fire's data is {type, orderId (the tab), fireId, fireNumber, locationCode, tableLabel, covers,
course, stations, away, itemCount, url} with url badgerpos://kitchen/<code>/fires/<fireId>; food
ready is a floor push (below). Titles say the table and course ("Table 12:
Mains away"), bodies the item and cover counts; never a guest's name or an amount. A phone working
one station can stay quiet for fires whose stations don't include it. Both respect
pos-push-enabled.
The customer follows the order on /order/{token}/track (linked from the confirmation page and
email), which polls GET /api/public/v1/order-tracking/{token} every 20 seconds. It shows roughly
how far away the driver is, never their position, and only when the delivery address has a map
position.
Front of house: the diary¶
A restaurant's table bookings are run from the app under /v1/dining/{locationId} (a location code
with the DINE_IN capability; tag Dining in the API reference). The agent needs
canManageReservations and the location among its locationCodes; an admin without an agent record
may run any dining room. /v1/pos/agents/me carries the flag and diningRooms, the rooms the user
may run. Responses carry the guest's name, phone, email, notes and allergies for the host stand, so
they are sent Cache-Control: private, no-store; the app keeps them in memory only.
| Call | Does |
|---|---|
GET /room |
Areas, tables, combinations, services, courses and the policy, and the restaurant's timeZone (servers with canServeTables may read it too, for the floor) |
GET /diary?date=&service= |
The service date's bookings in every state, by time; each interval's arrivals against its pacing caps; the day's services; the timeZone. Today's (the location's, a late service's past midnight) without a date |
GET /enquiries |
Every enquiry still waiting for an answer, from today's service date on, across days, by time |
GET /availability?date=&partySize= |
The staff view of a date's times: no pacing, caps or cut-off, held-back tables count |
GET /tables?partySize=&reservationId= |
Every table: free now, freeUntil its next booking, enough (free for the booking's stay, or 30 minutes for a walk-in), fits the party alone, heldBy |
POST /reservations |
A phone booking (source PHONE or STAFF), past pacing, at chosen tables or the best fit; the guest is emailed when an address is given |
GET, PATCH /reservations/{id} |
One booking with its messages and history; change its time, party, tables (moving tables), notes |
POST /reservations/{id}/arrive\|seat\|finish\|noShow\|cancel\|approve\|decline |
The evening's moves; seat and approve take {tableIds}, cancel and decline {reason} |
POST /walkIns {partySize, tableIds, contact?} |
Seats a party now until the tables' next booking (409 when that is under 30 minutes away) |
Times are sent in UTC. The room, diary and enquiries carry the restaurant's timeZone (the
location's, else the shop's), and the app shows every time in it rather than in the phone's zone.
Every move takes an optional Idempotency-Key (409 while the first is running, 422 for the same
key with a different body); a repeat answers with the booking as it now is. A booking at another
location is a 404. When the tables have gone, the 409 is ReservationUnavailable JSON with
nearest times; other refusals (a no-show before the grace period, a move from the wrong state) are
short plain-text sentences.
Push. With pos-push-enabled on, the devices registered at the restaurant whose user may run
its bookings, and every device of an enabled agent with canManageReservations assigned it, get
one copy of:
data.type |
When |
|---|---|
reservation-new |
a guest booked online for today's service |
reservation-cancelled |
a guest cancelled a booking for today's service |
reservation-enquiry |
a large party asked for a table, any day |
Changes staff make themselves, and bookings for other days, aren't pushed: the diary shows them.
All use sound default, channel default, priority high and category reservation. data is
{type, reservationId, reference, locationCode, date, startsAt, partySize, status, source, url:
"badgerpos://diary/<locationCode>/reservations/<reservationId>"}. The title and body carry the
party size, the time and the reference ("New booking for 4", "19:30 today, ref K7Q2MX"), never the
guest's name.
Appointments. The same people are pushed about appointments (appointment-new,
appointment-cancelled, appointment-link-paid, appointment-link-expired, category reservation, url
badgerpos://diary/<locationCode>/appointments/<bookingId>); see Appointments.
Front of house: table service¶
Servers run their tables from the app's Floor under /v1/dining/{locationId} (tag Table
Service in the API reference), once table-service-enabled is on for the shop. The agent needs
canServeTables (or canApproveVoids, a manager) and the location among its locationCodes; an
admin without an agent record acts as a manager anywhere. /v1/pos/agents/me carries both flags and
lists these rooms in diningRooms (for a server without the diary too). A table's tab is an open basket order
(channel DINE_IN) owned by the location, not a customer.
| Call | Does |
|---|---|
GET /floor |
Every table's state (free, seated, ordered, waiting to fire, food ready, bill requested, paying, needs clearing), its tab, covers, server and their name, when it was seated, the course being eaten (course) and when it went out (courseSince), when drinks last went out (lastDrinksAt), the total and its next booking |
GET, POST /tabs |
Open tabs; open one at free tables, from a seated booking (reservationId, its party is the covers) or for a walk-in (covers). A new tab belongs to a walk-in guest of its own; the server who opened it is its serverUserId, so tabs stay out of the server's own order history |
GET /tabs/{tabId} |
The tab by seat and course: each line's name, choices, note, allergens, fire state, price (frozen when fired) and takeBackAs (DELETE, VOID or COMP, what taking it back would be now) |
POST /tabs/{tabId}/lines, PATCH .../lines/{lineId}, POST .../separate |
Add a dish with its seat, course, modifiers, note and hold; change a line's seat (or its course, note and quantity, 1 to 99, before it is sent: a held line counts as sent, and a sent one answers 409 WRONG_STATE asking for a new line instead, with code SENT_COURSE_FIXED, SENT_NOTE_FIXED or SENT_QUANTITY_FIXED; a paid line answers 409 LOCKED, code LINE_PAID); separate some of a line. A new quantity reprices the bill and drops any unpaid split; more of a dish is checked against the stock on hand here, as adding it is (400 INVALID when there isn't enough). A change, or a take-back, that would bring the bill below what paid shares have already covered is refused with 409 WRONG_STATE, code BELOW_PAID, and nothing changes |
GET /menu?q= |
Find a dish on the table menu by name or SKU (2 to 64 characters, matched literally, ignoring case): at most 30, by name, each with its price, available (as the item reads it), hasVariants, hasChoices and the menu section it was found in. Only the menu the Floor browses is searched (see below), and never gift cards and the like |
GET /menu/{skuId} |
A menu item's modifier groups in order, with each option's price change and whether it's available, and its variants (sizes, flavours: price, sold out or not, switched-off ones left out), and whether the item can be had at all (available: false when every variant is sold out, or the item itself is when it has none), for the choice sheet; send the chosen variant as variantSkuId. Sold out means none on hand at this restaurant (safety stock isn't kept back; untracked never sells out), not what a shopper could have sent or collected, so a dine-in-only restaurant isn't sold out of everything. A tab takes its stock from the same place: the restaurant when the shop uses several stock locations and it holds stock, otherwise the main location, as a till sale does. Each line's stock is taken when it goes to the kitchen (sent or called away), not when the bill is paid, so the menu and the next course are checked against what is really left. Voiding or comping a line after that never puts it back, as the kitchen has used it, and cancelling the order later doesn't either. Lines still on the tab when it's paid that never went to the kitchen take theirs then |
POST /tabs/{tabId}/send, /fire, /hold |
Send the order (drinks and the course being eaten fire, the rest wait on the board); "Away" a course or fire lines early; hold lines |
POST .../lines/{lineId}/takeBack |
Delete, void or comp, as the line's state decides. A void or comp needs a reason and a manager: their own request approves itself, anyone else sends approvalToken |
POST /approvalRequests |
Ask the managers on shift to come over: pushes approval-requested to them |
GET /approvers, POST /approvals |
The managers with a PIN; a manager types their PIN on the server's phone and gets a one-use token (5 minutes, exactly that action and line). Five wrong PINs lock it for 15 minutes |
PUT /v1/dining/approvalPin |
A manager sets their own 4-6 digit PIN |
POST /tabs/{tabId}/transfer\|moveLines\|splitTable\|merge\|handOver |
Move the tab to other tables, lines to another tab, some lines to a new tab, merge another tab in (not once either has a payment), or give the table to another server. The server or a manager |
POST /tabs/{tabId}/void |
Void the whole tab before anything is paid (a manager) |
GET, POST /tabs/{tabId}/bill |
The bill; POST shows or prints it and the table turns "bill requested" |
PUT .../serviceCharge {removed, reason} |
Take the optional service charge off at the guest's request (who, when and why are recorded), or put it back. Not once a share is paid |
PUT .../split {mode, parts, lineGroups, amounts} |
Split what is left into shares: FULL, EQUAL, BY_SEAT, BY_ITEM, AMOUNT. Paid shares stay |
POST, PATCH .../shares/{shareId}/paymentIntent |
Start a share's card-present payment (next for the first unpaid share), collect it on the reader with on-reader tipping, then capture it at once. The tip is kept outside the order total |
POST .../shares/{shareId}/paymentIntent/cancel |
After a declined card, or when the guest would rather pay another way: cancels that share's card payment only (other guests' payments carry on) and puts the share back to open with its amount, so it can be paid in cash or by card again without splitting the bill again. Stripe is asked first: if the card has in fact been taken, nothing is cancelled and the answer is 409 (finish that payment). If the reader authorises the card at the very moment of the cancel, Stripe releases the hold, so the guest is never charged for a share that is open again. A share already open answers the bill unchanged. A 409 about the share or the tab names its case in code: CARD_TAKEN, CARD_BEING_READ (retry in a moment), SHARE_PAID, SHARE_REPLACED or TAB_CLOSED; BUSY (someone else is changing the tab: retry) has no code. 502 when Stripe can't be reached: the share stays as it was |
POST .../shares/{shareId}/cash {tipMinor, tenderedMinor} |
Take a share in cash, with a cash tip |
POST /tabs/{tabId}/close |
Clear a paid table: the tab closes, its booking finishes and the table is free |
GET /v1/dining/tipPolicy |
The tip policy in force, for staff to read |
Errors are DiningTabError JSON {reason, code, message}, worded for the phone. reason is the broad case: INVALID 400,
FORBIDDEN and APPROVAL_REQUIRED 403 (show the approval sheet), NOT_FOUND and NOT_ENABLED
404, WRONG_STATE, LOCKED (a paid line, or a PIN locked) and BUSY (someone else is changing the
tab: retry) 409, PAYMENT_FAILED 502, NOT_FOR_TABLES 400 (a gift card, top-up, ticket,
appointment, subscription or donation: "That can't go on a table's bill. Sell it at the till
instead."; GET /menu/{skuId} already answers available: false for these).
Where one reason covers several cases, code names the exact one, so the app never has to read
message. Branch on reason first and treat code as optional: it is left out of the JSON where
the case isn't named. Only the cases in the table below are named, wherever they arise; other
refusals carry no code, among them BUSY (someone else is changing the tab: retry), holding a line
that has already gone to the kitchen, and a card payment that couldn't be cancelled during a
re-split, merge or void. A key still in flight on any table-service call is plain text, not DiningTabError, with
X-Badger-Error-Code: IDEMPOTENCY_KEY_IN_FLIGHT (see Error codes in the till section above).
code |
reason |
Where | What it means | Retry the same request? |
|---|---|---|---|---|
TAB_CLOSED |
WRONG_STATE | Any change to a tab, including a share's card cancel and a line change | The table has paid or closed | No |
SHARE_PAID |
WRONG_STATE | A share's card cancel; paying a share | The share has been paid | No |
SHARE_REPLACED |
WRONG_STATE | A share's card cancel; paying a share | The share was replaced by a new split: split the bill again | No |
CARD_BEING_READ |
WRONG_STATE | A share's card cancel | The card is still being read on the reader | Yes, after a moment |
CARD_TAKEN |
WRONG_STATE | A share's card cancel; a re-split, merge or void | A card has been taken for the share: finish that payment | No |
LINE_PAID |
LOCKED | A line change, separate or take-back | The line has been paid for (refund it instead) | No |
SENT_COURSE_FIXED |
WRONG_STATE | A line change | The line has gone to the kitchen (sent or held), so its course can't change | No |
SENT_NOTE_FIXED |
WRONG_STATE | A line change | The line has gone to the kitchen, so its note can't change: add a new line | No |
SENT_QUANTITY_FIXED |
WRONG_STATE | A line change | The line has gone to the kitchen, so its quantity can't change: add a new line for more, or take some back | No |
BELOW_PAID |
WRONG_STATE | A line change; a take-back | The change would bring the bill below what paid shares have already covered: refund the difference instead. Nothing changed | No |
GET /room's menuRootSeoName (the collection whose children are its sections; set on the dining |
||||
room in admin or through MCP), falling back to the agent's posCollectionRootSeoName. `GET |
||||
| /menu?q=` searches the same menu: those sections and everything below them, or, with neither root | ||||
set, every top-level collection except the home page's (home) and everything below them, leaving |
||||
| out switched-off collections. |
Meal stage on the floor. course is the course being eaten: the latest food course served,
else the one the kitchen is making (fired or at the pass), never the drinks once food has gone out;
before any food has, it's the next course coming. courseSince is when that course went out to the
table (served, else fired; the latest line of it, so an extra side fired later restarts it), and
lastDrinksAt when a line of the drinks course last went out (served, else fired). Both are absent
until something has gone out, and on a free table. The app shows "25m" by the course, "Ask about
dessert" once it has been out 20 minutes with nothing else ordered, and a drinks timer that turns
amber after 15 minutes. Every move takes an optional Idempotency-Key and a repeat
answers with the tab or bill as it now is; repeating "start a card payment" starts it again for the
same share, because the client secret is never stored. Responses are Cache-Control: private,
no-store.
Push. With pos-push-enabled on, the floor hears (category dining, time-sensitive, url:
"badgerpos://floor/<locationCode>/tabs/<tabId>", data {type, tabId, orderId (the same tab), locationCode,
tableLabel, covers, course, fireId, fireNumber, action, lineId}):
data.type |
To | When |
|---|---|---|
dining-food-ready |
the table's server | the kitchen bumps a fire to the pass |
dining-bill-requested |
the table's server | someone else asked for the table's bill |
approval-requested |
the location's managers, not whoever asked | a server asked for a void, comp or tab void |
Titles and bodies name the table and the course ("Table 12: Mains ready", "At the pass, ready to take out."), never amounts or guests.
One push per event per phone. Every dining push (fires, food ready, the bill, approvals, bookings) reaches each push token once, however many device records or roles lead to it, and the worker remembers what it sent in Redis (token hashed): a redelivered event sends nothing, a course's "ready" is sent once until the kitchen brings it back, and asking for the same approval or bill again within two minutes doesn't push again. If Redis is down the pushes still go, once per token per event.
Front of house: the Manager section¶
A dining room's managers see how the day is going and the bills after they've closed, under
/v1/dining/{locationId} (tag Dining Manager in the API reference). Reading needs
canApproveVoids or the refund role (POS_SUPERVISOR), with the location among the agent's
locationCodes; refunding needs the refund role. An admin without an agent record may do both
anywhere. An agent with the refund role is also given their rooms in diningRooms.
| Call | Does |
|---|---|
GET /summary?date= |
The day so far: covers, sales against the same weekday last week up to the same time, the tables sat longest, the kitchen, voids, comps and refunds, and each server. Every block is optional |
GET /tabs/closed?date=&q= |
The day's paid, cleared and voided bills, newest first; q matches the table, order number or an amount ("42.50"). Carries the guest's name for a booked table, so it is sent no-store |
GET /tabs/{tabId}/bill |
Also answers for a closed bill, with refundedMinor, refundableMinor and refunds, and for a manager who doesn't serve tables |
POST /tabs/{tabId}/refund |
{amountMinor?, reason, note?} with an Idempotency-Key: card shares first through Stripe, then cash (cashToReturnMinor, recorded as paid out); tips only past the bill. 409 when less is refundable than asked |
Bookings also carry the guest's history (guest on StaffReservation: visits before this one,
no-shows, late cancellations, tags, complaints, usual dishes, and spend for managers only); the
diary and enquiry rows carry the short version. See table bookings.
Store status¶
GET /v1/pos/{locationId}/status (PosStoreStatus) gives the store's state now: open or
temporarily closed, today's hours, today's load per kind of work (capacity), and its timeZone;
see Store operations for closing it and changing
today's limit. For a store with collection or delivery slots
it also lists today's windows as slots: [{type, start, end, capacity, used}]: type
CLICK_AND_COLLECT or STORE_DELIVERY (collection first, then each earliest first), start and
end as HH:mm in the store's own time, capacity the orders the window takes and used the
orders booked into it (more than capacity when staff booked over the limit). slots is absent
when the shop doesn't manage capacity or the store has no slot templates.
Ship tasks¶
Web orders a store has to send show in the app as tasks of type SHIP, beside its collections,
so staff can find, pack, label and dispatch them from the till. They are only listed when the app
asks for them (GET /tasks?type=SHIP or type=ALL): the default stays COLLECTION, because app
versions from before ship tasks expect only collections.
Which orders. An order that is sent (not collected), placed and not cancelled, with items this
store sends. On an order partly collected and partly delivered, only the delivered items count:
the collected ones are the collection task's, never parcelled or labelled. An item is sent from the location its stock was allocated at
(LineItem.sourceLocationCode, set by multi-location sourcing);
an item with no allocation from the active location its fulfiller is bound to
(Location.fulfillerId); anything else from the main location. This is the same rule that picks a
parcel label's sender address, so a store's tasks and its labels always cover the same items. A
task shows and moves only this store's items: an order split with York appears at both stores,
each with its own lines.
Statuses. TO_PREPARE while any of the store's items is still to pack, READY once they are
all packed, DISPATCHED once they have all gone, CANCELLED when the order (or every item here)
is cancelled. status=open lists TO_PREPARE, ready lists READY, and done lists those whose
items all went today (store time zone), most recently sent first. With type=ALL both kinds are
merged by when they were placed (done: newest first), and toPrepare and ready add the
kinds together; shipToPrepare and shipReady break out the ship tasks.
What a ship task carries. The order number, when it was placed, the store's lines (SKU, name,
variant, quantity, picked so far, barcode, image) and shipping: the delivery service the
customer chose, the town and the postcode area (DE23, the outward code), and the store's latest
parcel label that isn't cancelled (shipmentId, status, live, carrier, service, tracking
number and link, and where the carrier says it is: trackingStatus and lastEvent, see
Parcel Tracking), and the
delivery promise made at checkout as promise: {earliest, latest,
dispatchDate, late} (dates in the sending location's time zone; late is true once the end of
latest has passed and the order isn't delivered, the rule the ops inbox's late deliveries use).
promise is absent for an order that made none. No customer name, street or full postcode: the fulfilment portal's queue shows
packers the same, and the label carries the address.
| Call | Does |
|---|---|
POST /tasks/{orderId}/lines/scan {code} |
As for collections: ticks one unit of the first matching line still to send (Order.shipPicked). A checklist only |
POST /tasks/{orderId}/lines/unscan {code} |
As for collections: takes one unit back out of the parcel, from the last matching line still to send that has something picked. 409 once the order has been sent |
POST /tasks/{orderId}/lines/{lineId}/short |
As for collections (Items that can't be picked), for the store's lines still to send; undo with DELETE while still packing |
POST /tasks/{orderId}/pack |
Marks the store's items still to pack as packed (READY), and emails the customer about any items found short. Optional Idempotency-Key |
POST /tasks/{orderId}/dispatch {carrier?, trackingNumber?, trackingUrl?} |
Dispatches the store's items still to go. Without tracking, a live label for them supplies it; the customer gets the dispatch email and the store's labels are marked sent. 400 for tracking that won't do. Optional Idempotency-Key |
Labels for a ship task are bought with the POS parcel label endpoints,
and GET /v1/pos/{locationId}/shipments/presets gives the shop's box sizes and label format, so the
app needn't hard-code boxes. Pack and dispatch make the same moves as the
fulfilment portal's Pack and Mark dispatched (through
FulfilmentService), so the order, the customer's emails, payment capture and the portal's queue
stay in step whichever was used. Packing or dispatching an order whose items here have all gone,
or that was cancelled, is 409; ready and collect on a ship task, and pack and dispatch on
a collection, are 404.
A new web order is pushed to the tills of every store that sends some of it, as a
new-store-task with data.taskType: "SHIP" ("New order to send: order #1002 is to be sent from
Leeds"), behind the same pos-push-enabled switch. The worker hears the portal's new-work event
(NewFulfilmentWorkEvent) and works out the stores with PosShipTaskService.sendingLocations.
An app version that predates ship tasks gets these pushes too once push is on; tapping one opens
GET /tasks/{orderId}, which returns a SHIP task.
Code: PosShipTaskService (commerce-core/.../pos/), routed from PosTaskService; the candidate
query is OrderService.findShipFromLocation.
Customer messages¶
The app's Messages area answers customers from the shop's customer service inbox:
GET /v1/pos/agents/me says canAnswerMessages when the person has an inbox role (Customer service, admin or
superadmin), and the app then reads /v1/admin/messaging/contact-requests with its own token. Replies and notes take
an Idempotency-Key, so a reply whose answer was lost on the shop's Wi-Fi can be sent again without emailing the
customer twice. Someone with only the Customer service role can sign in to the app too: agents/me answers
them with role CUSTOMER_SERVICE, no till, no locations and every other flag false, so the app opens on Messages;
the role gives them nothing else in the app. With no store they register their device at PUT /v1/pos/devices/{deviceId}
(same body as the till's device registration, no locationCode in the answer, 403 without an inbox role), so the
pushes sent to them as a person reach it. A device already registered at a store keeps its store.
Store staff. With canReplyToOrderMessages (anyone who works at a store, unless the shop turns off
pos-order-messages-enabled), staff see what customers wrote about an order their store collects or sends, on the
task, and can reply: GET /v1/pos/{loc}/tasks/{orderId}/messages (each request as the inbox shows it, notes
included, spam left out) and POST /v1/pos/{loc}/messages/{requestId}/reply. Nothing else of the inbox: no list of
it, no assignment, no closing. Refusals are plain text with X-Badger-Error-Code: ORDER_MESSAGES_OFF (403),
INVALID_REPLY (422; a 422 with no code is a key reused for another text), REQUEST_IS_SPAM, NO_EMAIL_ADDRESS,
IDEMPOTENCY_KEY_IN_FLIGHT (409); a request about anything else is a 404.
Push. With pos-push-enabled on, the person who owns a request hears on every device they registered
(category customer-message, url: badgerpos://messages/<requestId>, data: {type, requestId, about?: {type, id,
label}}): customer-message-assigned when someone else gave it to them, customer-message-reply when its customer
wrote again (not an auto-reply, nor a message from another address or one that failed sender checks). The words say
what it's about at most ("A customer has written about Order #10452"), never the customer's name, address or
message. A new request nobody owns isn't pushed: routing emails it to the shop.