> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theroyalglow.in/llms.txt
> Use this file to discover all available pages before exploring further.

# CRM & Lead Pipeline

> Customer profiles, tags, notes, and lifetime value, plus the Meta-ad lead pipeline that turns ad clicks into booked customers.

# CRM & Lead Pipeline

The CRM is how Royal Glow understands and nurtures every relationship — both the
customers it already has and the prospects ("leads") that come in from Meta and
Instagram ads. One side is about knowing your regulars; the other is about
converting cold ad traffic into paying customers.

<Info>
  **Lead vs customer.** A *lead* is a prospect captured from a Meta/Instagram ad
  via the `/book` page — no slot, no sign-in. A *customer* books through the
  homepage dialog (organic, GMB, in-store QR) or as a receptionist walk-in. The
  two live in different tables (`lead` vs `booking`).
</Info>

## What it is

Two connected things:

* **Customer management** — a rich profile for each customer: contact details,
  visit history, tags, staff notes, and lifetime value (LTV).
* **Lead pipeline** — a kanban board that tracks ad-sourced prospects from first
  contact to a booked, paying customer.

## How it works — customer profiles

Each customer has a profile that staff use to give a personal, informed service:

* **Identity** — name, phone, email, gender, "member since" date.
* **Tags** — short labels for segmentation. Some are assigned automatically
  (e.g. `vip`, `loyal`, `spa_lover`, `dormant`); others are added manually by
  staff (e.g. `bridal`, `corporate`).
* **Notes** — free-text notes staff add after visits (e.g. "allergic to
  ammonia").
* **KPIs** — visits, lifetime value (total spend), average spend, no-show count,
  and gems balance.

The customer list can be searched and sorted by LTV, visits, last visit, gems,
or no-show count, so staff can quickly find their best (or at-risk) customers.

## How it works — the Meta-ad lead pipeline

This is the paid-acquisition funnel, designed for maximum conversion from cold
ad traffic:

```
Meta / Instagram ad
   ↓
theroyalglow.in/book   (distraction-free landing page)
   ↓
3-field form: name, phone, service interested in
   ↓
POST /api/leads → lead row created (source: meta_ad) + CAPI Lead event
   ↓
Redirect to /?book=1&leadId={id}   (into the homepage booking dialog)
   ↓
Customer signs in / onboards, then submits the booking
   ↓
lead.converted_booking_id is set → lead status becomes "booked"
```

The `/book` page is deliberately minimal — no navigation, no sign-in prompt,
trust signals (4.9★, reviews, city) above a 3-field form, and a "Continue to
Booking" button. It exists only for ad traffic; the homepage, GMB, Google Maps,
and in-store QR all use `/?book=1` instead so attribution stays clean.

<Info>
  If a lead submits the form but never completes a booking, a background job
  flags it as stale after 48 hours and the receptionist follows up by phone or
  WhatsApp from `admin.theroyalglow.in/leads`.
</Info>

### Lead status pipeline

A lead moves through a fixed set of statuses:

```
new → contacted → follow_up → booked → won
                                    ↘ lost
```

| Status      | Meaning                                                  |
| ----------- | -------------------------------------------------------- |
| `new`       | Just captured; no contact yet.                           |
| `contacted` | Receptionist has called or messaged.                     |
| `follow_up` | Needs more nurturing; appointment not yet set.           |
| `booked`    | A booking was created and linked to the lead.            |
| `won`       | The booking was completed and paid — revenue attributed. |
| `lost`      | Unreachable or declined; a reason is recorded.           |

A lead automatically becomes `won` when its linked booking is completed. Marking
a lead `lost` requires a reason.

## Rules

<Warning>
  **First-touch attribution is permanent.** A customer's acquisition source
  (`organic`, `meta_ad`, `gmb`, `walkin`) is stored once on first contact and is
  **never** overwritten by later visits — this keeps revenue attribution honest.
</Warning>

<AccordionGroup>
  <Accordion title="How are phone numbers stored?">
    Phone numbers are normalised to canonical `+91XXXXXXXXXX` before storage, so the
    same number is never duplicated under two formats.
  </Accordion>

  <Accordion title="Is the public lead form protected?">
    Yes. `POST /api/leads` is the only unauthenticated write endpoint and is
    rate-limited per IP to prevent abuse.
  </Accordion>

  <Accordion title="How many tags can a customer have?">
    Up to 10 tags. Automatic tags (e.g. `vip`, `loyal`, `spa_lover`, `dormant`)
    cannot be removed by hand.
  </Accordion>

  <Accordion title="How does WhatsApp follow-up stay in sync?">
    Lead conversations are handled through AiSensy. When a status changes there, a
    webhook updates Neon so the database stays the single source of truth.
  </Accordion>

  <Accordion title="What source do admin-created leads get?">
    Leads created from inside the admin portal are forced to `source = manual`
    (versus `meta_ad` for ad traffic).
  </Accordion>
</AccordionGroup>

## Related links

<Columns cols={2}>
  <Card title="Leads API" href="/docs/api-reference/leads">
    Public lead capture plus the admin pipeline (list, detail, status, notes).
  </Card>

  <Card title="Customers & CRM API" href="/docs/api-reference/customers-crm">
    Customer directory, profiles, notes, and tags.
  </Card>

  <Card title="Booking System" href="/docs/features/booking">
    How a lead's booking links back for attribution.
  </Card>

  <Card title="Data Model" href="/docs/data-model">
    The lead, lead\_note, customer\_tag, and customer\_note tables.
  </Card>
</Columns>


## Related topics

- [Booking System](/content/docs/features/booking.md)
- [No-Show Policy](/content/docs/features/no-show-policy.md)
- [Features](/content/docs/features/index.md)
- [Tech Stack](/content/docs/tech-stack.md)
- [Admin & Staff Guide](/content/docs/product/admin-staff-guide.md)