> For the complete documentation index, see [llms.txt](https://grouple.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://grouple.gitbook.io/docs/frontend/merchant-flows.md).

# Merchant Flows

### 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
```

### [​](https://grouple.mintlify.app/frontend/merchant-flows#lead-management-flow)Lead Management Flow <a href="#lead-management-flow" id="lead-management-flow"></a>

```
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
```

### [​](https://grouple.mintlify.app/frontend/merchant-flows#lead-status-lifecycle)Lead Status Lifecycle <a href="#lead-status-lifecycle" id="lead-status-lifecycle"></a>

```
pending → accepted → connected → closed_won
                  ↘ declined
                  ↘ closed_lost
```

### [​](https://grouple.mintlify.app/frontend/merchant-flows#proposal-creation-flow)Proposal Creation Flow <a href="#proposal-creation-flow" id="proposal-creation-flow"></a>

```
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
```

### [​](https://grouple.mintlify.app/frontend/merchant-flows#beo-banquet-event-order)BEO (Banquet Event Order) <a href="#beo-banquet-event-order" id="beo-banquet-event-order"></a>

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

### [​](https://grouple.mintlify.app/frontend/merchant-flows#analytics-dashboard)Analytics Dashboard <a href="#analytics-dashboard" id="analytics-dashboard"></a>

`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

### [​](https://grouple.mintlify.app/frontend/merchant-flows#subscription-plan-limits)Subscription Plan Limits <a href="#subscription-plan-limits" id="subscription-plan-limits"></a>

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`   |

[<br>](https://grouple.mintlify.app/frontend/customer-flows)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://grouple.gitbook.io/docs/frontend/merchant-flows.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.