Customer history
The customer detail page is the bidirectional hub — twelve tabs (Overview, Repairs, Bespoke, Quotes, Invoices, Sales, Passports, Wishlist, Loyalty, Store Credit, Communications, Notes) stitch every linked record into one view. Open a customer and see every piece they ever touched.
Quick reference
- Customer detail lives at /customers/[id] — open any row in the customer list and the detail page opens with the hero card up top and the tabbed history beneath.
- The hero card carries the customer's name, VIP and tag pills, contact line, customer-since date, jewellery preference chips (preferred metal, ring size, allergies as a red warning chip if set), and a three-card stats column on the right — Store Credit, Lifetime Spend, Last Visit.
- Twelve tabs sit beneath the hero — Overview, Repairs, Bespoke, Quotes, Invoices, Sales, Passports, Wishlist, Loyalty, Store Credit, Communications, Notes. Tabs with content show a count badge (e.g. Repairs · 3).
- Every tab's rows link to the canonical detail page for the underlying record — Repairs to /repairs/[id], Bespoke to /bespoke/[id], Sales to /sales/[id], Passports to /passports/[id], and so on. The customer page is the orientation surface; you walk into a record from here.
- Most tabs carry a + New affordance in the header — start a new repair / bespoke job / quote / invoice / sale / passport pre-scoped to this customer. The affordance is hidden in review mode and gated by the relevant create-permission on the operator's role.
- This is the transactional history view. The audit-log history of edits to the customer record itself lives separately at /customers/[id]/history — see Adding and editing customers for that surface.
Walkthrough
1. Read the hero card
The hero is the at-a-glance card. Left side: avatar with initials, full name, VIP pill and any additional tag pills, the contact line (email + a small Send email button for operators with the permission, mobile / landline phone, customer-since month/year), then the preferences pill row (preferred metal, gold preference, ring size, wrist size, allergies — the allergies pill renders red so it's impossible to miss when discussing a new piece).
Right side: three stat cards — Store Credit (live balance), Lifetime Spend (sum of paid-status invoices), Last Visit (most-recent invoice payment date). The Store Credit card carries a darker border than the other two — operationally, available credit is the field staff most often need to read fast before ringing through a sale.
![/customers/[id] detail page header — back link 'Back to Customers' top-left, Archive + Edit Profile buttons top-right, hero card with circular avatar with initials, full name + VIP pill + tag pills, email + Send email button + mobile + Customer since date, then preferred-metal + ring-size + allergies pills, then Store Credit + Lifetime Spend + Last Visit stat cards on the right. Tab bar beneath.](/_next/image?url=%2Fdocs%2Fscreenshots%2Fcustomers-and-clienteling%2Fcustomer-history%2F01-customer-detail.png&w=3840&q=75&dpl=dpl_9SjgBTS4akDRKHonU4Xh1ruTDZoS)
2. Overview tab
The Overview tab is the metadata view — Personal & Dates card (birthday, anniversary, spouse name, spouse birthday — all rendered as “dd MMMM” without the year so the upcoming-date use case reads cleanly), Preferences card (preferred metal, gold preference, ring size, wrist size, allergies, comm preference), and a Contact card (email, mobile, phone, full address, customer source). It's the read view of every field the customer record carries that isn't already in the hero. Edit goes through the edit-profile button at the top, not from here.
3. Repairs tab
Every repair on this customer, newest first. Each row shows the item description, the repair number, the creation date, the quoted price, and a stage badge (intake / in-workshop / ready / collected / etc.). Click through to /repairs/[id] for the full repair detail. The + New Repair link in the tab header opens the new-repair form pre-scoped to this customer.
See Repair pipeline for the workshop-side view of the same records (the repair pipeline is the stage-grouped workshop board; this tab is the customer-grouped slice of it).
4. Bespoke tab
Bespoke jobs on this customer — title, job number, creation date, quoted price, stage badge. Rows link to /bespoke/[id]; + New Job opens the bespoke intake pre-scoped to this customer. See Bespoke pipeline for the workshop-side board.
5. Quotes / Invoices / Sales tabs
Three financial tabs, same shape. Quotes — quotes sent to this customer with expiry and status. Invoices — invoices issued, with balance-due rendered in red when there's an outstanding amount. Sales — POS transactions, with the layby pill on rows where status = layby and the remaining-balance number rendered in amber for the operator chasing the collection.
Rows link to the canonical detail page for each record: /quotes/[id], /invoices/[id], /sales/[id]. The + New affordances pre-scope each form to the current customer so quoting / invoicing / ringing through a sale from the customer page never asks who the customer is.
Cross-reference into the sales detail at Processing a sale.
6. Passports tab
Every Verify Passport whose current_owner_email matches this customer's email. Each row carries the passport title, UID, jewellery type, and current status (Active / Archived / Reported Stolen). Rows link to /passports/[id] for the full jeweller-side detail page documented under Passport management.
Important: the link between customer and passport is the email address, not a direct foreign key. If a customer's email is empty, this tab will be empty regardless of how many passports they own — the join can't resolve. If a customer has multiple email addresses across their relationship history, only passports recorded against the currently-stored email surface. When a piece changes hands and you log the ownership transfer through Transferring passport ownership, the passport moves out of the previous owner's tab and into the new owner's.
7. Wishlist tab
Inventory items the customer (or a staff member acting on their behalf) has saved as wishlist items. Each row shows the item name, SKU, retail price, the date it was added, and a notified-on date if a previous Notify customer action fired. Two operator affordances per row: Notify customer sends a message (via the channel configured on your tenant) telling them the piece is in / back in stock and stamps the notification date; ✕ removes the item from the wishlist after a confirm. Both gate on the edit_customer permission.
Soft-deleted inventory rows are filtered out of the wishlist render — if a piece on a customer's wishlist is archived in inventory, it stops surfacing here so staff don't accidentally quote retail against a piece that's no longer for sale.
8. Loyalty tab
The loyalty surface — current points balance, current tier (Bronze / Silver / Gold / Platinum), a progress bar showing distance to the next tier, a four-card tier breakdown highlighting the customer's current tier, and the Points History list. Every loyalty transaction (earn on purchase, redemption on a discount, manual adjustment) appears chronologically with the points delta in green for credits and red for debits. Tier thresholds: Bronze 0–499 / Silver 500–1499 / Gold 1500–2999 / Platinum 3000+.
9. Store Credit tab
The available-balance card up top (large, single number), then a transaction history table beneath — date, reason, amount delta, running balance after. Reasons include refund-as-credit, gesture-of-goodwill add, voucher reversal, POS redemption, manual adjustment. Reference type and ID surface on each row so the auditor reading the history can pivot from “the $200 credit on 14 March” into the actual refund or sale record that created it.
10. Communications tab
Every outbound message the system has sent to this customer on your tenant's behalf — email receipts, invoices, quotes, repair-ready notifications, stage updates, manually-sent 1:1 emails, and notification- channel messages. Each row carries an icon for the message type, a label, the status (sent / delivered / bounced / failed), the subject, and the date / time. Tapping a row opens a modal with the full message body rendered.
The 1:1 email send modal — the Send email button next to the email in the hero card — composes a personal email to this customer and records it in this tab on send. Subject and body are both required; send recording is contractual (the UI only shows “Sent” when the provider confirmed the send), so a stuck spinner or an explicit error message is always preferred over silent failure.
11. Notes tab
The polymorphic notes timeline — every note recorded against this customer by any staff member, with author, timestamp, and edit / delete affordances gated on author-or-admin. The legacy plaintext notes textarea was retired in favour of this timeline; pre-existing column data was migrated as a single “legacy note” entry per customer so no prior content was lost.
The notes timeline is the in-context narrative surface — the “Mrs Chen prefers Saturday appointments,” the “heads-up: father in palliative care, this is why the bespoke deadline keeps moving,” the “don't cold-call — sister manages all the piece logistics now.” Different staff stack chronologically; nothing overwrites anything.
Common questions
Why are twelve tabs flat instead of grouped under parent categories?
Flat tabs preserve constant click-distance to every tab from anywhere on the page. Operationally, customer-history reads are short and pivoty: open a customer, jump to Repairs to confirm the repair number, jump to Communications to check the last ready-for-collection message went, jump to Notes to read the heads-up. A two-level navigation would add a click to every pivot. The trade-off is that twelve labels in one row is dense — but each label is a familiar word and a count badge, so the read cost is lower than the click cost saved.
The same design choice runs through the workshop hub and the marketing hub. When the count of distinct surfaces grows past what reads cleanly on one row, it'll get a re-grouping pass.
Why is the passport-customer link via email rather than a direct foreign key?
Passports are designed to travel with the piece, not with the originating customer. The passport's primary identity field is the current_owner_email — which can change over the piece's life as ownership transfers. Modelling it as a foreign key to customers(id) would either (a) force every passport to have a corresponding customer row in your tenant, which collapses if the piece transfers to a buyer who isn't in your CRM, or (b) require nulling the FK on transfer, which loses the link entirely.
Email-as-link handles both cases: a passport whose current owner happens to be in your customer table surfaces in their tab; a passport whose current owner has moved to someone outside your customers surfaces with no tenant-side customer association (which is correct). The cost is the join semantics (we're joining on email substrings rather than an indexed FK column) — fine for the tenant-scoped query pattern we actually run here.
Why doesn't the Notes tab merge in the communication log entries?
Two different evidentiary regimes. Notes are internal narrative — written by staff, for staff, freely edited and freely deleted, intended to accumulate context that helps the next staff member who picks up the customer. The audit behaviour around notes is “who wrote what when” — not “what did we send the customer.”
Communications are outbound records — every message the system sent on your tenant's behalf. Append-only, never edited, never deleted, with delivery status from the underlying provider. The audit behaviour is the legal-grade “what was sent, when, by whom, did it arrive.” Merging the two into one timeline would compromise the second contract — a deleted note next to a delivered email looks like the email was reversible. Two tabs, two contracts.
The Lifetime Spend doesn't include this customer's repairs or bespoke jobs — why?
Lifetime Spend sums paid invoices specifically. Repairs and bespoke jobs are billed through invoices when you invoice them — a repair that's been invoiced and paid shows up in Lifetime Spend via its invoice. A repair that was rung through the POS as a sale instead surfaces via the Sales tab and contributes to revenue numbers there rather than to Lifetime Spend.
This is a design choice driven by what the hero card is meant to convey: “how much has this customer paid into the store across their full relationship.” The number is meant to be spend-volume-attached. A quoted repair that's never paid doesn't belong; a sold piece doesn't belong if it was refunded. If you need a different definition — e.g. invoiced-regardless- of-payment, or all-transactions-including-POS — the underlying data is all there per-tab; the hero number is one specific summary.
The tab count badge says “3 Repairs” but the tab shows only 2 — what's the third?
The count badge reads off the loaded data — up to 20 most-recent repairs are fetched per detail-page render. The tab list shows what loaded. The discrepancy is most often: (1) a soft-deleted repair that's being excluded from the list correctly but the badge is reading off a stale cache, or (2) more than 20 repairs exist and the badge is capped against the loaded set.
For (1), hard-refresh the page. For (2), you're looking at a 21+-repair customer (rare in practice) — open the customer's data export, or filter repairs at /repairs?customer_id=… for the full list.
Troubleshooting
Passports tab is empty for a customer who definitely owns a passport
Symptom:a customer's Passports tab renders “No passports yet” but you know you issued them a passport recently. Cause: passport-to-customer association is via email, not FK. The passport's current_owner_email field needs to exactly match the customer's email on file. If the customer's email was updated after the passport was issued, or the passport was issued with a typo'd email, or the customer was added to your CRM without an email at all, the join misses. Fix: open the passport at /passports directly (search by title or jewellery type), edit the passport's ownership block to set the correct email, save. The Passports tab on the customer detail page will pick up the row on the next render.
Communications tab shows a message status of “failed” but the customer says they got it
Symptom: a row in Communications shows the failed icon / status pill but the customer confirms receipt. Cause: two candidates. (1) The underlying provider returned an error code that the integration treats as failure, but the message was actually delivered (some providers have ambiguous status codes around soft bounces). (2) A retry succeeded but the original failure row was never updated. Fix:the row stays as evidence of the recorded provider response; if the customer confirms receipt, that's the ground truth. The Communications tab is system-recorded delivery state, not customer- confirmed delivery — staff should trust the customer over the system on the rare disagreement. For a pattern of false-failed rows on a specific message type, contact support so we can audit the provider integration.
Store Credit balance on the hero doesn't match the last balance-after number in the history table
Symptom:the hero card shows $80 store credit but the Store Credit tab's most-recent transaction row reads $200 in the balance-after column. Cause:a transaction was written without updating the materialised balance on the customer row (a real bug that's been patched on the canonical code paths, but old data may still show the gap). Less commonly, a manual SQL adjustment touched the row directly without inserting a corresponding history entry. Fix:contact support with the customer ID — we'll recompute the balance from the history table (which is the source of truth) and reconcile the row. If you find one of these, capture the timestamp of the suspect transaction; that helps us find any systemic write path that's skipping the sync.
Send Email button doesn't appear next to the customer's email address
Symptom: the hero card renders the customer email but no Send email button beside it. Cause: three possibilities. (1) Read-only / review mode — the affordance is hidden when the page is opened with the review token. (2) Your role lacks edit_customer — the same permission gates the send-email modal. (3) The customer has no email on file (the button only renders when there's an address to send to). Fix: for (1), open the page without the review token. For (2), ask owner / manager to grant the permission. For (3), open the edit form and add the email.
Wishlist Notify customer button is disabled
Symptom: the Notify customer button on a wishlist row is greyed out and shows “Notified” instead. Cause: a previous notification has already been sent — the row carries a notified_at timestamp that the button reads to disable re-sends. This prevents accidental double-notification on a piece that's been back in stock once. Fix: if you genuinely need to re-notify (e.g. the customer missed the first one and called asking), the cleanest path today is to remove the item from the wishlist and re-add it. A more graceful re-notify path is on the backlog.
Related
- Processing a sale — the canonical detail surface for the rows in the Sales tab
- Repair pipeline — the workshop-side board for the rows in the Repairs tab
- Bespoke pipeline — the workshop-side board for the rows in the Bespoke tab
- Passport management — the canonical jeweller-side detail surface for rows in the Passports tab
- Transferring passport ownership — what changes when a piece moves to a new owner email
- The customer record — what the row itself holds before the linked records stitch in