15. Customer archetypes — worked examples by customer size

This chapter walks through typical customers, from one shop to a fifty-store chain, plus three specialist trades. For each one it shows where every need lands: configuration, our apps, or your own. It is for a builder, or the salesperson beside them, sizing a project before quoting it.

Each example names the samples it uses. More samples for the standard and enterprise examples are being built. The table What is live where in chapter 9 shows which extension points exist today, and which build carries them: none is in a customer release before iVendNext POS release 1.0.

When to use it

Use it at the blueprint step. Find the example closest to your customer. Then place each of the customer's own needs on the ladder (chapter 3), and give it one of these marks:

Mark	Meaning
✅	deliverable today
✅ᵇ	deliverable today, with a stated bound
🔶	after an extension point we are still building (chapter 9)
🔷	product work on our side — ask us

A customer's size describes it; it never decides the path. A large project's blueprint adds three things: a scale proof, a release gate in the customer's own CI and, where needed, joint work with us on an extension point.

15.1 Small — one to three stores

The shape. One to three stores; phones and a counter till; an online shop.

Steps.

Configure: prices, promotions and coupons; receipts with the shop's logo and tax number (the receipt pack sample); reason codes for voids, returns and discounts; blind till counts for cashiers; sale details captured at the till; permissions by role.
Our apps: the iVendNext POS on phones and on the counter; our WooCommerce connector for the online shop.
Your apps: usually none. Perhaps one outside app — a price checker, an accounting export.

Limits. Our WooCommerce connector does not reserve stock, and it takes percentage vouchers only. Card payments need a certified payment connector in the customer's country — ours, or one a builder has written and certified (chapter 11).

Effort. Days of configuration, not a build.

15.2 Mid — twenty terminals on our connectors

The shape. Six stores: 12 phones, 6 counter tills and 2 tablets, all running the iVendNext POS. Handheld does receiving and stock counts. WooCommerce runs the online shop. Acumatica is the ERP, with Sage X3 to follow.

Need	Where it goes	Mark
Prices, promotions, member tiers by customer group	configure	✅ᵇ — combined discounts follow the promotion rules
Reason codes, blind counts, sale details, permissions	configure	✅
Receipts with logo and tax number	the receipt pack (a manifest)	✅
Shelf and product labels from the till or Handheld	labels extension point	🔶
Online orders in; stock and prices out	our WooCommerce connector	✅ᵇ
Sales, stock moves and purchasing to the ERP	our Acumatica connector	✅ᵇ — limits below
Receiving and counts	Handheld	✅ᵇ — online only; a count has no in-app approval step
A warranty check at the till	a till key answered by your service (the warranty sample)	✅
Loyalty	ours, or the customer's own — your call with the customer	✅ ours · redeeming the customer's own at the till 🔶

Limits to plan for.

ERP throughput. Our Acumatica connector books about 2.75 complete sales a minute per connection — about 165 an hour. Size the customer's busiest hour against it before you promise.
One ERP per company. Acumatica now and Sage X3 later cannot both be one company's ERP. Our Sage X3 connector is not built yet.
Scale. No load test has been run yet, and the largest live customer runs 18 terminals. Run the customer's scale profile on a sandbox before go-live (the scale-profile kit).
Handheld books online only in its first release, so receiving needs a connection.
Counter printers are wired to counter tills. We have not yet tried that route on the customer's own hardware, so test it in the pilot store. A phone prints through the network printer or the device's own dialog.

15.3 Mid — with its own systems

The shape. Ten to thirty stores. The customer runs its own loyalty programme, CRM, online shop and ERP, and wants iVendNext as its store system.

System	How it connects	Mark
Its own ERP	your outside app on the API and the event feed, keeping its own map of record ids, its own place in the feed, and a nightly reconciliation (the enterprise sync sample)	✅ᵇ — the enterprise sync sample reads the shared feed, which the customer's administrator opens to your app; a feed scoped to your own app has shipped (chapter 9), but the kit has not run against it yet (chapter 5)
Its own online shop	your outside app: orders in, stock and prices out	✅ — an online order cannot be edited at the till
Its own CRM	your outside app reading customers and sales	✅ᵇ
Its own loyalty — earning	the customer's service on each booked sale	✅ᵇ
Its own loyalty — redeeming at the till	the wallet extension point	🔶
A member's status at the till	a till key answered by the customer's service	✅

The pattern: the customer's logic, the records in iVendNext. The logic runs in the customer's service. Its records — the loyalty ledger, member plans — live in iVendNext as your manifest's record types, written through the API. Reports, audit and native screens stay in iVendNext. No code runs there.

15.4 Enterprise — fifty stores and more, distribution centres, its own order and warehouse systems

The shape. Fifty or more stores and distribution centres. The customer has its own order-management and warehouse systems. It has specialised processes: a barcode on every physical unit, approvals across stores, its own loyalty with a wallet, and quick-commerce marketplaces.

Five patterns that carry it.

The customer's logic, the records in iVendNext (15.3).
Check by workflow. Use this for a back-office check that must block, with no code in iVendNext. The document's workflow has a Verified step that only the customer's service can take, after its check passes. Submit is allowed only from Verified. The user waits a few seconds, and the service must be up for back-office submits. A manager-held Override step can sit beside it.
Member tier as a customer group. Each tier is a customer group with its own promotion. The service moves customers between groups. This works offline too.
Status from events, with reconciliation. The event feed sets a status (a unit sold or available). A nightly pass checks it against the booked documents.
Marketplace calls land at the customer's service, never at iVendNext. The service creates the orders through the API.

Steps.

Blueprint every process on the ladder. Most land on configuration, a manifest and the customer's service.
Name the extension points the project needs (often the wallet, a scan source for unit barcodes, and the check before payment). The scan source and the check have shipped; the wallet has not. Agree joint work on any that are not yet built.
Write the scale profile and run it on a sandbox.
Put the customer's release gate in its own CI from the first sprint.
Rehearse a full trading day, with offline replay, before cut-over. Move all stores together.

Limits to plan for. No load test has been run yet. Stock lookups grow with the number of warehouses, and promotions are evaluated for every store, so a 50-store chain must be measured on its own profile. One company is one country and one currency, so several countries mean several sites. There is no store server. The customer's distribution centres and warehouse system stay its own: you connect to them.

15.5 Vertical — pharmacy, optical, electronics

Vertical	Today, on our beta build	After an extension point	Product work on our side
Pharmacy	batches and expiry dates; reason codes; prescriptions as your own records; a prescription number required before payment (a check before payment); pharmacy 2D codes at scan, with an expired pack refused (a scan source)	other shelf-life rules	first-expiry-first-out at the till; insurance co-payment; the controlled-drug register — our pharmacy pack
Optical	lab orders as your own records, with a workflow; your outside app to the lab; a check before payment that needs a prescription	—	—
Electronics	a serial number or IMEI per unit (exactly one per unit, never sold twice); a unit's own code recognised at scan and refused once sold (a scan source); a warranty key at the till; extended warranties sold as items	—	buy-now-pay-later tenders (our payment connectors)

The extension points named in this table reach a customer's site with iVendNext POS release 1.0 (chapter 9, What is live where).

What is refused, and why

Every example keeps the four rules (chapter 3):

money enters the sale visibly, before payment;
no overrides or patches;
your code on your server;
your screens through our doors.

Where a need seems to break one, it needs an extension point instead. Request it (chapter 9).

When your service is down, and when the till is offline

Each example follows the rule of the rungs it uses. Configuration and promotions work offline. Outside apps catch up from the event feed. Till keys and wallets are not offered offline or when your service is down; the sale goes on with other tenders.

The tests

Every need in the customer's blueprint carries a mark and a rung.
The scale profile has been run on a sandbox (mid and above).
The customer's release gate runs in its CI before the first upgrade (chapter 14).

Technical notes

Scale bound. No load test has been run yet; the largest live estate is 18 terminals.
Counter printers. The route through a wired counter till has not yet been proven on the customer's own hardware.
Acumatica throughput. About 2.75 complete sales a minute per connection — about 165 an hour.
The scoped feed (15.3, its own ERP). Shipped: the event feed extension point is in the extension-point library at the POS app's development branch (commit 21c7512), and its code (api/feed.py, business_logic/feed.py) is in the bench's pin 8dc36aab8. Not proven: neither the kit's feed client nor the enterprise sync sample (S7) has been run against the shipped door (chapter 5, Technical notes; S7's README).

This page in the kit