Processing a sale at the POS

Quick reference

• Open /pos — add items by clicking tiles or scanning barcodes, optionally attach a customer, apply a discount, click Charge $X.XX to open the payment modal.
• Six payment paths: card, cash, store credit, split, voucher, layby. The selected tab's primary button completes the sale.
• On success: the page swaps to a confirmation screen with sale number, total, change due (for cash), and action buttons for receipt + invoice.
• Stock is decremented atomically — sold-out detection is whole-cart-or-nothing; no partial deductions if a piece slips out from under you mid-checkout.
• Every completed POS sale also creates an invoice automatically, linked back to the sale. Find both at /sales and /invoices.

Walkthrough

1. Open the POS and pick your location

Visit /pos. If you have more than one location and haven't selected one this session, the page prompts you to pick — the selection is held in a cookie and persists across page loads, so you only do this once per session per till.

The location matters because (a) the product grid only shows inventory at the picked location, (b) the completed sale stamps that location on the sale record so dashboard per-location numbers stay accurate, and (c) refunds initiated later through this sale are scoped to the original location for restock.

2. Build the cart

Click product tiles to add items. The first click adds at quantity 1; subsequent clicks of the same tile increment. Alternatively scan a barcode with a keyboard-wedge scanner (just scan; no special focus needed) or tap the camera-scan button on a tablet.

Adjust quantities on each cart line with the − / + buttons. The + button is capped at the item's on-hand quantity, so you can't oversell a piece you're holding 3 of by clicking + four times. Remove a line with the x on the right.

3. Attach a customer (optional — required for some payment types)

The customer field sits at the bottom of the cart, above the discount selector. Start typing — the dropdown surfaces matching customers; click to attach. The chosen customer appears in the field and the store-credit balance becomes available as a payment method.

You can skip this for a basic cash/card walk-in. You need a customer attached if you'll pay with Store credit or use the Layby flow, or if you want the receipt emailed.

If the customer isn't on file yet, open /customers/new in a separate tab, save them, return — they appear in the dropdown on the next keystroke.

4. Apply a discount (optional)

The discount control is two inputs: a selector for $ off or % off, and the numeric value. Type the value; the footer updates the running totals immediately. Discount applies to the subtotal; tax is calculated on the discounted amount.

A few guard rails: a percent discount is capped at 100%, a dollar discount is capped at the subtotal — so the total can't go negative no matter what you type. Negative values are clamped to zero — there's no way to add a surcharge through this field.

5. Open the payment modal and pick a method

Click the green Charge $X.XX button at the bottom of the cart. The payment modal opens with the total at the top and six tabs across — Card, Cash, Store credit, Split, Voucher, Layby.

For the standard motion, pick Card or Cash:

• Card — if Stripe is connected, click Record card payment after the customer's terminal-tap completes. If Stripe isn't connected, the tab shows a Connect Stripe prompt with a link to /settings/payments and a fallback Record as manual card payment button for sales taken on a stand-alone terminal.
• Cash — type the amount tendered; the modal shows the change in green. The button stays disabled until tendered ≥ total.

6. Or split the payment across two methods

Click the Split tab. Three modes are available along a pill toggle: Cash + Card, Voucher + Card, Voucher + Cash.

For cash + card: type both amounts; they must sum to the total (the modal shows the current shortfall live in amber until they match). Click Complete split payment.

For voucher + cash or voucher + card: type the voucher code, click Look up, the modal pulls the balance and pre-fills the remaining amount field with (total − min(voucher balance, total)). Voucher amount is auto-clamped to balance — a $500 voucher on a $300 sale covers the $300 and the remaining $200 is the leftover voucher balance, untouched.

7. Submit — the saga runs

Click the primary button on whichever tab you picked. A few things happen server-side in one atomic saga: stock is decremented for every cart line, store-credit and voucher amounts are debited if applicable, the sale row is written, sale-item rows are inserted, an invoice is auto-created and linked back.

If any step fails — most often, a sold-out detection on stock — the entire saga compensates: stock restores, debits reverse, the sale row never lands. The cashier sees the error message and the cart stays intact; no half-finished sale to clean up manually.

Submit is also protected by an idempotency key generated client-side: double-clicking the charge button doesn't create two sales — the second click sees an in-flight submission with the same key and returns the existing result.

8. Confirm + send the receipt

On success, the page swaps to a confirmation screen — sale number in monospace, total, change due (for cash), and a stack of action buttons.

Print receipt opens a thermal-receipt PDF in a new window, formatted for 80mm receipt printers. If your default browser printer is set to the receipt printer, this is a one-click motion.

Email to customer only shows if the attached customer has an email on file. It sends a PDF receipt via email; the button updates with a confirmation toast (✓ Receipt emailed to …) when the send completes.

View invoice jumps to the auto-created invoice page. The invoice and sale are linked both ways — the sale detail page shows a “Invoice auto-created” banner with a link, and the invoice page shows the originating sale reference.

Issue passport only appears if the cart included a finished piece (an item with item_type = 'finished_piece'); clicking it jumps to the verify-passport flow pre-filled with the inventory ID. Useful for jewellers who issue passports at the point of sale.

9. Back to an empty cart

Click New sale — the workspace resets to an empty cart, the customer detaches, the discount clears, and the product grid re-fetches its inventory in the background so subsequent sales see the freshly-decremented quantities. The next customer can be rung up immediately.

Common questions

Troubleshooting