Customers

Customers is the business's customer list: a profile for each person, linked to their platform identity, with consent records, notes, tags, an activity history, a customer card, duplicate review and exports. Phone numbers and email addresses are kept on the platform identity, not in Customers' own tables. Booking, POS, Storefront, Queue and Membership add to a customer's page when they're on, and staff find anyone from one search box. Points and packages are Membership's. Customers doesn't merge people: it records possible duplicates for review, and the merge itself happens on the platform identity.

What it handlesCopy Anchor Link

• Two people editing one profile. Each change says which version it started from. Of two changes made from the same version, one lands and the other gets a conflict. Changes, archiving and restoring are written to the audit log, and a change to someone merged while it was being made lands on the record that survived. Tested: "Customers: profile lifecycle" Tested: "Customers: person facts on the identity"
• Adding someone who is already there. Adding a customer with a verified phone number that already belongs to someone opens that person instead of creating a second, and adding them again keeps the language they chose. Staff without customers:write can't add anyone. Tested: "Customers: person facts on the identity"
• One search for any identifier. A phone number in any spelling (081-234-5678 or +66 81 234 5678), an email in any case, a name, an account code or an id finds the same person, exact matches first, with phone and email masked. A merged person shows once. Archived customers, people only another app knows, and private details such as an ID number never come up. If the identity service is down, the search says so instead of showing "No customers found". Tested: "Customers: one search for every identifier"
• Customer cards. A person keeps one card (a code and a QR) for life, and after a merge it names the person who survived. Cards Membership issued before keep working in every link form. A payment QR, another site's link, an unknown card or an archived customer's card is refused. Tested: "Customers: card lookup"
• Activity and duplicates reported twice. The same activity delivered twice is stored once, and its key reused for another customer is refused without touching their totals. A possible duplicate pair opens one case whichever way round it's reported. The case can be dismissed and reopened, and it closes with one audit entry once the identities are merged. When consent is granted and withdrawn at the same moment, the withdrawal wins. Tested: "Customers: operational records"
• Exports that leak less. An export downloads only the chosen fields as CSV, with spreadsheet formulas made harmless, and the audit log records the export without its data. Staff who can view customers but not export are refused, and nothing is recorded. A marketing export includes only people with current consent on that channel and a verified address, and refuses to run when it can't check merged records. Tested: "Customers: governed exports"
• Extra profile fields. Settings can switch on gender, home address, birth date and ID number. Staff can fill a field only once it's switched on. The ID number shows on the customer's record but never in the list or its search. Changing the fields needs settings:write, and staff tied to one branch can't change them. Tested: "Customers: extra profile fields"

What you build on topCopy Anchor Link

• Modules alongside. Switch on Booking, POS, Storefront, Queue and Membership to see their activity and summaries on each customer's page.
• The customer's page. Booking, POS, Storefront and Membership each add a panel to a customer's page through the customers.detail.panels slot: the activity types it lists, a summary of points, packages or entitlements, and the actions it offers. The slot takes panels from those four Modules only.
• Who can use it. Manager and Staff start with customers:read and customers:write, and Viewer with customers:read. Grant them to other roles before staff use the app in production.
• Admin-only actions for now. Archiving and restoring a customer, notes, consent changes, exports and retrying activity that failed to reach a profile check customers:archive, customers:notes, customers:consent, customers:export and customers:recovery. The Module doesn't declare these keys, so they aren't in the table under Facts and no role starts with them: only Admin can do these things.
• Your words. A gym's business type calls customers "Members". Pick another name (clients, patients, guests) with an override.
• In code. Your coding agent imports Customers only through its public API: index.ts and server/index.ts in apps/web/src/modules/customers/. See Build on a Module.

LimitsCopy Anchor Link

• Customers doesn't merge people. It tracks possible duplicates; the merge happens on the platform identity and closes the case.
• Your app can't add its own panel to a customer's page yet. The slot accepts only Booking, POS, Storefront and Membership.
• Extra profile fields are a fixed set. Settings refuses a field outside it.

FactsCopy Anchor Link

• Kind: feature Module, can be switched on and off
• Needs: Audit log, Formatting, i18n, Identity, Infra, Standard UI
• Needed by: Nothing
• Adds to these when they're on: Tour
• Added to by: Account, Booking, Membership, POS, Queue, Storefront
• Off by default for these business types: none

Pages

Where	Path
Admin	/admin/customers

Permissions

Admin holds every key. The other roles listed hold it when the app first gets the Module; after that, roles are yours to change under Settings → Roles & Permissions.

Permission	What it allows	Organization roles that start with it
admin-panel:write	Full compatibility access to all module administration, including POS, catalog, storefront, and CRM staff tools.	Admin
customers:read	View customer lists, profiles, exports, and CRM insights.	Admin, Manager, Staff, Viewer
customers:write	Add and edit customer profiles and review possible duplicates.	Admin, Manager, Staff
settings:write	Configure resources, schedules, availability, fares, blocked periods, and queue setup.	Admin

Data

• Tables: customer_profile, customer_card, customer_identity_alias, customer_consent_event, customer_note, customer_tag, customer_tag_assignment, customer_activity, customer_stats, customer_duplicate_case, customer_export_manifest, customer_migration_run, customer_migration_result, customer_migration_checkpoint

Slots

Places other Modules and your app code can add to. See Extend a Module.

• customers.detail.panels

Tested workflows

• Customers: profile lifecycle
• Customers: generated composition
• Customers: operational records
• Customers: governed exports
• Customers: legacy CRM migration
• Customers: permission matrix
• Customers: endpoint congruence
• Customers: public boundary
• Customers: person facts on the identity
• Customers on the admin home and in search
• Customers: extra profile fields
• Customers: card lookup
• Customers: one search for every identifier