Decision: Own Loyalty Engine, Don’t Delegate to Square Loyalty
Date: 2026-04-02 Status: Decided Decision: Guild owns all loyalty logic. Square Loyalty is not used. Square remains the cash register only.
Context
Square Loyalty ($45/mo/location) provides points earning, reward redemption, VIP tiers, promotions, and an audit trail — covering the basics of any loyalty program out of the box. We evaluated whether to delegate loyalty to Square and use Guild as a thin orchestration layer on top, or continue owning the full engine.
Square Loyalty — What It Does Well
- Automatic points accrual on purchases (spend/visit/category/item rules)
- Native POS integration — staff and customers see points at checkout on the Square Register
- Reward redemption as order discounts
- VIP tiers (spend-threshold-based, earned not paid)
- Temporary promotions (up to 10 active)
- Full event audit trail via API
- Webhooks for balance changes
- Phone-number-based account lookup
Where Square Loyalty Falls Short for Us
| Constraint | Impact |
|---|---|
| Program config is Dashboard-only — API is read-only for program settings | Can’t programmatically manage rules, tiers, or rewards. Everything must be manually configured in Square Dashboard. |
| One program per seller | No multi-tenant support. Breaks our org > shop hierarchy if we ever onboard another shop. |
| Tiers are spend-threshold-based | Our tiers are paid subscriptions via Stripe. Square has no concept of a membership fee unlocking a tier. |
| Redemption = order discounts only | Our “universal currency” model (store credit, experiences, merch, digital perks) doesn’t fit. Points must convert to a Square order discount. |
| No XP/leveling | Our BECMI progression system, character classes, and achievements have no analog. |
| No event/check-in integration | Square tracks visits for accrual but doesn’t integrate with Hi.Events or NFC check-ins. |
| POS lock-in | If we move to another POS, Square Loyalty data is trapped. Our custom attributes approach is a push — we can push to any POS. |
| Split state problem | If Square owns base points but we also award for events/check-ins/promotions via AdjustPoints, and track XP separately, we’d have two sources of truth. Harder to reason about than owning it all. |
The POS Gap — and the Kiosk Solution
The one thing Square Loyalty gives us that we can’t replicate in software alone: native Register integration. Staff see points on the Square terminal at checkout, customers see their balance on the customer-facing display.
Our answer: the guild-kiosk. A Raspberry Pi + touchscreen + NFC reader at the counter, running alongside the Square Register. The kiosk handles:
- Check-in: tap guild card or enter phone number
- Points display: balance, tier, XP progress, dollar value
- Redemption: staff initiates redemption on the kiosk, applies as manual discount on Square
This won’t be invisible like a native POS integration — it’s a second screen. But it can be seamless if we design the flow right:
- Member taps card on kiosk when they walk in (check-in + identity established)
- Staff sees member info on kiosk screen while ringing up on Square
- If redeeming points, staff taps “Redeem” on kiosk, enters amount, applies discount on Square
- Purchase webhook fires, Guild awards points automatically
- Kiosk updates in real-time to show new balance
The kiosk is the bridge between our loyalty engine and the physical checkout experience. It’s also portable — if we switch POS systems, the kiosk stays the same. Only the webhook handler changes.
What We Keep Building
- Points engine: tier-aware earning, multi-source accrual (purchases, events, check-ins, promotions, manual)
- XP/leveling: BECMI progression, level-up detection, dashboard progress bar
- Paid tiers: Stripe subscription → tier assignment → earn multiplier
- Universal redemption: store credit, experiences, merch, digital perks
- Square sync: push tier/points/status to Square customer attributes (POS visibility)
- Event integration: Hi.Events webhook → attendance → points
- Kiosk: physical presence at the counter for check-in, display, and redemption
- Portability: designed to work with any POS, Square is just the first
What We Don’t Build
- We don’t replicate Square Loyalty’s native POS UI — the kiosk is our answer
- We don’t try to inject into the Square checkout flow — purchases fire webhooks, we react
- We don’t fight Square’s ecosystem — we complement it
Related
- membership-platform — full system architecture
- guild-kiosk — hardware + UX for physical loyalty experience
- guild-hi-events-integration — event attendance → points
- rpg-loyalty-system-design — XP, leveling, achievements design