Merchant Flows

End-to-end flows for merchants and venue managers on Grouple

Merchant Onboarding Flow

New merchants onboard via a 3-step flow (client/components/merchant/onboarding/):

StepOne — Business Profile
  - First name, last name, phone, company name, role
  - Company logo upload (→ Supabase Storage: Logos bucket)
  - Saves merchant record to DB
        ↓
StepTwo — Venue Details
  - Venue name, venue type, description, venue image (→ venue-images bucket)
  - Seated + floating capacity
  - City + neighbourhood (searched + auto-created if new)
  - Address, postal code
  - Cuisines (free text tags)
  - Amenities (free text tags)
  - DB Trigger: tr_check_venue_limit (BEFORE INSERT on venues)
        ↓
StepThree — Venue Pricing + Shifts
  - Currency selection (USD, AED, GBP, INR, EUR)
  - Min + max price per person
  - Operating hours (shifts with days + start/end time)
  - On complete → merchant.onboarding_completed = true
  - Redirects to /dashboard
        ↓
SuccessModal — "You're All Set! 🎉"
        ↓
DB Trigger: tr_check_venue_limit — enforces venue limit per subscription plan

Lead Management Flow

Merchant receives new lead notification email (send-lead-email Edge Function)
        ↓
Goes to Leads page (/leads)
  Tabs: Pending | Accepted | Declined | Connected | Closed Won | Closed Lost | All
  Shows: RFQ ID, Customer Name, Venue, Event Date, Time Slot, 
         Group Size, Event Type, Budget, Status
        ↓
Clicks lead → RFQ Detail page (/rfq/RFQ-XXXX/pending/{venue_lead_id})
  Shows:
    Left: Event Type, Group Size, Event Date, Preferred Time, 
          Venue, Food Preference, Special Requirements
    Right: Budget Range (e.g. Standard $101-$250)
           Customer Details (Full Name, Company, Phone, Email)
  Actions: "Decline" or "Accept" buttons (when Pending)
        ↓
Merchant clicks Accept → status changes to "Accepted"
  → "Send Proposal" button appears top right
        ↓
Merchant clicks "Send Proposal" → goes to proposal creation page
        ↓
DB Trigger: trg_set_venue_lead_timestamps → records accepted_at
DB Trigger: trg_record_response_time → logs response time

Lead Status Lifecycle

pending → accepted → connected → closed_won
                  ↘ declined
                  ↘ closed_lost

Proposal Creation Flow

Merchant clicks "Send Proposal" on an accepted lead
        ↓
SendProposalPage → ProposalSendContainer
        ↓
Right side shows Enquiry Details (read-only context):
  Event Type, Group Size, Event Date, Event Time, Budget Range, Requirements
        ↓
Proposal form sections (all auto-filled by AI except noted):

1. Packages — Merchant selects from Sales Library
   (AI uses these for pricing context)

2. Proposal Details (AI fills automatically):
   - Proposal title
   - Choose a venue ← merchant can change
   - Event date + time (pre-filled from enquiry)
   - Group size (pre-filled from enquiry)
   - Offer validity date ← merchant fills manually

3. Executive Summary (AI fills automatically)

4. Package inclusions (AI fills automatically)

5. Pricing:
   - Amount (AI fills automatically)
   - Price type: "per person" (default) or "per event" (flat rate) ← merchant can change
   - Service fee ← merchant fills manually
   - Discount ← merchant fills manually

6. Optional add-ons (Label, Description, Price)
   → NOT included in Total Quote automatically
   → Only added to total if end customer selects them on the proposal

7. Payment terms (AI fills automatically)

8. Venue policies (AI fills automatically)

TOTAL QUOTE shown at bottom = Amount × Group Size (updates live)
        ↓
Merchant clicks "Send Proposal status: "sent"
        ↓
DB Trigger: proposal-updated-email → sends send-proposal-email Edge Function

BEO (Banquet Event Order)

After a booking is confirmed, merchants can generate a BEO document (beo/BEODocument.tsx) containing:

• Event details, setup time, table setup
• AV requirements, staffing requirements
• Customer and venue contact information
• Financial summary

Analytics Dashboard

analytics/AnalyticsPage.tsx powered by merchant_analytics_v3 view shows:

• Total leads, wins, pending, accepted, connected, lost
• Average group size, average lead value
• Average response time (hours)
• Lead distribution by category
• Top budget tiers

Subscription Plan Limits

Merchant actions are governed by their subscription_plans record:

Limit	Field
Max venues	max_venues
Max menu PDFs	max_menu_pdfs
Monthly proposal limit	monthly_proposal_limit
AI model access	ai_model_name
Performance insights	has_performance_insights
Commission rate	success_fee_percentage