Somebody has chosen a loyalty scheme and the till supplier has been asked whether it can be connected. The honest answer is usually yes, and the useful answer is what it involves.
This is the work, in the order it has to happen, and the parts that get underestimated.
Identify the customer at the till
Before a sale can earn anything, the till has to know whose it is. In practice that means scanning something: a barcode on a printed card, a code in a phone, a wallet pass.
The two things that make this harder than it looks:
Which symbol. A one dimensional barcode is read by every scanner including old laser ones. A QR code needs a 2D scanner or a camera, and an older laser scanner cannot read it at all. Choosing QR because it looks modern strands every shop with a scanner bought before about 2015.
Where the code goes. Most tills have a single input that a scanner types into. If the loyalty code has to go somewhere else, staff will not use it at a queue, and the scheme quietly does nothing.
Send the sale
One call, after the sale is complete, saying what was bought and by whom.
Three properties matter more than the shape of the payload:
Idempotency. Tills lose connections mid-call. The same sale will be sent twice, and the second one must not earn again. That means a key the till generates and the platform remembers, not a timestamp.
The till's own time. A sale rung offline and synced two hours later must be priced at the moment it happened, not the moment it arrived. Otherwise a promotion that ended at four o'clock pays out on a sale from three.
Which shop and which lane. Sent on every sale, or the figures can never be split by branch and nobody will trust them.
Refunds
Usually the last thing anybody thinks about and the first thing a finance director asks.
A refund has to take points back in proportion to the money returned, and it must cope with a partial refund. Where the customer has already spent the points, somebody has to decide what happens, and it is better for that decision to be a stated rule than an accident.
Spending a reward
This is a different problem from earning, and treating it as the same one is the commonest design mistake.
Earning can be matched on an email address after the fact, because the worst case is somebody gets points they should not have. Spending cannot: a card number or an address is not proof that the person is standing there. Spending needs something that expires, shown by the customer at the moment of the sale, which usually means a rotating code in their app.
If a scheme lets a reward be spent on a card number alone, that is worth raising before integration rather than after.
Offline
Most tills keep trading when the network goes. Decide in advance what loyalty does when that happens:
- Sales queue and sync later, earning the right points at the right rate.
- Identification may still work from the scanned code alone.
- Spending a reward offline is the one to be careful with, because nothing can check the reward has not already been used somewhere else.
Being explicit about that third one is better than discovering the answer in a shop.
The parts usually underestimated
Staff behaviour, not software. The commonest failure in a connected loyalty scheme is that staff do not attach the customer before taking payment. The integration is perfect and most sales earn nothing. Whatever is built should make that visible, because nobody will report it.
Clock differences. Tills, servers and the platform rarely agree. Anything that depends on a time window has to say whose clock it means.
Testing with real scanners. A barcode that renders correctly on a screen is not a barcode that scans on the counter hardware. That test belongs early.
What to ask the loyalty provider
- Is there a published contract, an OpenAPI file, and can the supplier build against it without involving either of us?
- What does identification look like, and what is the difference between identifying and authorising a spend?
- How are duplicate sends handled?
- What happens on a refund, including a partial one?
- What happens when the till is offline?
If those five have clear answers, the integration is a few days of work. If they do not, the time goes on finding out rather than on building.
This is the shape [Valence Easy Loyalty](https://easyloyalty.co.uk) was built to, and its contract is published so a till supplier can build against it without involving us.
This is part of what we do under Software development. See the services, or tell us what is not working.