Part A · Concepts¶
Contacts, groups, entitlements, offers and reporting: what the pieces are, how to use them, and how to work out why something is not showing.
What the pieces are and how they fit together. Read this once; it should stay true even as the screens change.
A1 · The shape of the system¶
Offers are not created in the CRM.
They are created in the POS, on the till, and imported. If an offer is missing, your first question should almost always be about the deal in the POS — not about the CRM.
This is the one idea the rest of this guide leans on, so it is worth stating plainly before anything else. If you go looking for where an offer gets created, you will not find it in the CRM. A deal is set up in the POS, used at the till. Nothing in the CRM writes a deal into existence. The CRM's job starts after that: it imports what the POS already has, decides who is allowed to see it, and reports on what happened when customers used it.
Deals are imported every five minutes. For every venue, the import reads that venue's current list of deals from the POS and turns each one into an offer in the loyalty database. There is no button in the CRM that triggers this. If you have just set a deal live in the POS, expect it to appear as an offer within about five minutes, once the next run comes round — not instantly, and not something you need to chase by hand.
The one thing to understand first¶
Every deal the POS returns is imported.
The import used to keep only the deals marked loyalty-only in the POS and discard the rest. That filter has been removed: every deal the POS returns for a venue becomes an offer. Whether a customer ever sees it, and which list it appears on, is decided afterwards — not by whether it made it into the CRM at all.
That change matters because it moves the interesting decisions downstream of import. Two things decided later, from data already sitting on the deal in the POS, are what actually control a customer's experience:
- Whether anyone can see it at all. A deal without Publish to App ticked in the POS is imported but held in preview. No ordinary customer sees a preview offer; only a preview reviewer can, so that someone can check it over and sign it off before it goes live to customers. If you are wondering why a deal that is clearly live at the bar is still not showing to customers, that is expected: till visibility and Publish to App are two separate settings in the POS, and only Publish to App decides whether customers can see it. A deal can be selling at the till and still be awaiting its app sign-off at the same time.
- Where it lands once it is visible. A deal that carries one or more loyalty groups in the POS becomes a VIP offer, restricted to members of those groups. A deal with no loyalty groups at all becomes an ordinary Offers entry, open to everyone. So if you are trying to work out whether a deal will land in VIP or Offers, look at its loyalty groups in the POS — not at the old loyalty-only setting, which no longer has any effect on where a deal ends up.
One more downstream detail worth knowing early: a deal imported with no app copy in the POS — no name written for it yet — is stored under the placeholder name Untitled deal followed by its POS deal id. That is deliberate. Rather than fail the whole venue's import over one deal nobody has finished writing up, the import gives it a name you can search for, so you can find the deal that still needs copy rather than losing it entirely.
POS loyalty database customer app
───────────── ──────────────── ────────────
deals defined ──▶ the import creates ──▶ offers the
by the venue an offer for customer
EVERY deal qualifies for
│
├─ "Publish to App" ticked in the POS?
│ no ─▶ preview reviewers only
│
└─ carries loyalty groups?
yes ─▶ VIP no ─▶ Offers
An offer is never typed into the CRM. It arrives from the POS, and two settings in the POS decide who can see it.
Keep this shape in mind through the rest of Part A: contacts, groups and entitlements are all about who qualifies for an offer once it exists; none of them are about where the offer itself came from. If something looks wrong with an offer's name, its timing, or which deals exist at all, look in the POS first — not in the CRM screens covered later in this guide.
A2 · Contacts¶
A contact is one person: a name, a mobile number and/or email address, a date of birth, and the groups they belong to. Every offer, entitlement and report in this guide ultimately comes back to one person's contact record — A3 onward is about how a contact gets sorted into the groups that decide what they see, so it is worth being precise here about what a contact actually is and where it comes from.
A contact usually comes into existence the moment someone signs in to the app for the first time. If their email already matches an existing, unclaimed contact — one nobody has linked a sign-in to yet — that record is claimed and reused rather than duplicated; only when there is no unambiguous match is a new contact created. That first sign-in also backfills whatever the app already knows — name, email, mobile, date of birth — into whatever fields on the contact are still blank. It never overwrites a value that is already there, so a name you have corrected in the CRM will not be replaced by a stale claim from a later sign-in.
Two other routes matter enough to name:
- A registration source. A campaign link or QR code a contact arrives through. Applying one can add a contact to one or more groups at the moment they sign up — a way a contact ends up in a group without you adding them by hand in the CRM. You will meet registration sources again in Part B.
- The till. A physical loyalty card is created ahead of time as a blank placeholder — no name, no mobile, just a long unique code printed on the card — and only becomes a real, identified contact when someone claims it at the till with their name and mobile number. Claiming fills in who they are; it does not by itself put them in any group.
Whichever route creates it, what actually identifies a contact day to day is their mobile number or email address — both are searchable fields in the CRM's contact search, alongside name.
A3 · Groups and the tree¶
Groups form a tree, and membership is read upward.
A contact's groups are not just the ones they were directly added to. Every group above those, all the way up the tree, counts too. This one fact is behind most "why can this person see that offer" questions, so read this chapter slowly even if you skip the rest of Part A.
Every group can have a parent, and a parent can have its own parent, and so on — that is the tree. When the system works out which groups a contact belongs to, it does not stop at the groups you put them in directly. It walks up the tree from there, collecting every ancestor along the way, and treats the contact as a member of all of them. A member of a child group already receives everything the parent group offers, with nothing extra to set up.
Students ─────────────── offers here reach EVERYONE below
│
├── Freshers 2026 ────── and everyone in here
│
└── Societies ────────── and everyone in here
│
└── Chess Soc 25/26
│
└── a member here receives offers from
Chess Soc, Societies AND Students
Membership is read upward, never downward. A member of the deepest group inherits every ancestor’s offers.
Two consequences follow directly from this, and both matter for how you use the CRM:
- Putting an offer on a parent group reaches every descendant's members. Restrict an offer to Students in the diagram above and a member of Chess Soc 25/26 sees it, even though nobody ever added them to Students directly. If you want an offer to reach the whole tree, restrict it to the root, not to every leaf.
- Nesting a group under the wrong parent silently widens who gets an offer. Move Chess Soc under Students by mistake and every one of its members instantly inherits every Students-restricted offer — with no warning, and nothing on the offer itself changes to tell you. The mistake lives in the tree, not in the offer.
When you are trying to work out why someone can or cannot see an offer, always ask the same question: what does this contact's branch of the tree look like, read upward from wherever they were actually added? A4 covers the different kinds of group you will find in that tree, and A6 puts groups back together with the other two ways an offer can reach someone.
A4 · The three kinds of group¶
Not every group in the tree behaves the same way. There are three kinds, and the CRM enforces the difference rather than just documenting it — an edit that would break one of these rules is refused before it can be saved.
| Kind | Has members | Can have children | Shape editable |
|---|---|---|---|
| Ordinary | Yes | Yes | Yes |
| Society year-managed | Yes | Yes | No — name and parent are set by the academic-year clone |
| Entitlement pool | No | No | Yes |
Society year-managed groups¶
A society's tree — the society itself, and the year groups underneath it — is built and rolled over automatically by the academic-year clone. You cannot rename one of these groups or move it to a different parent. That is not an arbitrary restriction: a group hand-added inside a year subtree is either left behind when the clone rolls the tree over to the next year, or, through the same upward walk covered in A3, drags its members into the wrong year's offers. Neither failure shows up when you make the change — only later, when an offer misfires for people who should not have had it, or fails to reach people who should. The rule exists because that mistake is invisible until it is already a problem.
Only the shape of a managed group is locked. Its stop date, whether it requires photo ID, and its entitlement terms if it is also a pool, all stay editable — an admin fixing a photo-ID setting mid-year is an operational change, not a structural one, and is never blocked by this rule.
Entitlement pools¶
A pool is a group with nobody in it. Its offers exist and are restricted to it exactly like any other group's offers — but because it has no members, the only way a person gets one of those offers is an individual grant (A5). Two edits are refused because of that: you cannot turn a group into a pool while it still has children, and you cannot parent anything — pool or ordinary group, at any depth — beneath one. Both come from the same leak: the upward walk in A3 does not know or care that a group is a pool, so a group sitting beneath one would hand every one of its members the pool's offers automatically, with no grant, no record of who was granted what, and no way to see it happened. The CRM refuses both edits outright rather than let it happen silently.
A pool itself can still sit under an ordinary parent, though — that is not the restriction. Nothing walks down from a group to its members, so a pool having an ordinary group above it creates no leak in either direction: the parent's members do not inherit the pool's offers, and the pool still hands out nothing except by grant.
A5 · Entitlements¶
An entitlement pool (A4) has no members, so its offers cannot reach anyone through the tree the way an ordinary group's can. The only way a person gets one of a pool's offers is a grant: an individual record that says this one contact may use this one offer.
A grant carries three things:
- Uses allowed. How many times the grant can be redeemed.
- A validity period. Its own start and end dates. Leave these blank and the offer's own visibility dates apply instead — the grant only needs its own window when it should run on a different schedule from the offer itself.
- A display reason. The offer card always starts with "Just for you"; a display reason is appended to it, not shown in its place. Leave it blank and the card reads exactly "Just for you". Type Happy Birthday! into it and the card does not read "Happy Birthday!" — it reads "Just for you · Happy Birthday!". Write the reason with that prefix in mind, not as a standalone line.
Think of the pool as the shelf of offers and the grant as the individual person's ticket to one of them: the shelf decides what exists to be granted at all, and the grant decides who gets a copy, how many times they can use it, and for how long.
A6 · How an offer reaches a customer¶
A1 covered where an offer comes from: a deal in the POS, imported automatically. This chapter covers the other end, and it is the one you will reach for most often: once that offer exists in the CRM, there are exactly three ways it can reach a customer, and when someone asks you why a customer cannot see one, you are really asking which of these three was supposed to apply.
An offer reaches someone in exactly one of three ways:
1. PUBLIC the offer is public and in its visibility window
→ everyone sees it
2. BY GROUP the offer is restricted to a group
→ members of that group, AND of any group beneath it,
see it (the upward walk again)
3. BY GRANT the offer belongs to an entitlement pool
→ only someone individually granted it sees it,
for as many uses and as long as the pool allows
If a customer cannot see an offer, it is because none of these three applies. Part D walks the causes in order.
The first route needs nothing extra: an offer with no restriction group at all is open to anyone, as soon as it is published and inside its visibility window. If you are checking a public offer, that window and whether it has been published (A1) are the only two things worth looking at. The second is the group tree from A3 — restrict an offer to a group and it reaches every member of that group and of everything beneath it, never just the group named on the offer, so when you are chasing this one, check the customer's whole branch of the tree, not just the group the offer names. The third is A5's entitlement pools: an offer restricted to a pool reaches nobody by membership, because a pool has none, so a grant is the only door in — if you are looking at this route, what you need to find is the grant itself, not a group membership that will never exist.
Those three routes are the whole answer to "who can see this offer." There is no fourth path around them for an ordinary customer — if one cannot see an offer, the cause is always that none of the three applies, and working out which one was expected to apply is where D4 starts. The one person this does not describe is a preview reviewer, who by design sees preview offers regardless of group or grant, so they can sign a deal off before it reaches anyone else; that exception is covered on its own in Part D.