Sales System

1. Simple Feature Overview

The Sales & Institutional Subscription System helps your team manage the full lifecycle of institutional (B2B) sales — from initial contact with a prospective institution, through pipeline tracking and negotiation, all the way to closing a deal, onboarding users, and managing renewals.

Here is what the system lets you do:

• Create and manage institutions — universities, libraries, schools, corporates, nonprofits — each with their own subscription plan, seats, billing details, and contact information
• Track sales opportunities — use a visual Kanban pipeline to move deals through stages (New → Contacted → Negotiating → Converted or Declined)
• Log sales activities — record calls, emails, meetings, and notes against each opportunity so your team has a complete history
• Send outreach emails — use built-in email templates or write custom emails directly from the pipeline, with attachment support
• Convert opportunities to institutions — when a deal closes, convert the inquiry into a fully set-up institution with one click
• Manage institutional users — add users (readers) to an institution, send login invitations, and track activation
• Handle renewals — renew expiring subscriptions, with automated reminder emails sent at 30, 14, and 7 days before expiry
• View sales reports — see pipeline value, conversion rates, deal sizes, and expiring subscriptions at a glance

Implementation Status: All sales features listed above are fully implemented and working. The Sales Management Module is 100% complete as of March 2026.

---

2. Who Should Use This Feature

---

3. Before You Begin

Prerequisites You Must Have in Place

Before using the sales system, the following must be configured by your admin team:

Permissions Required

The system uses role-based access control. Here are the permissions relevant to sales:

If you cannot see the Sales section in the left sidebar, ask your admin to assign you a role with these permissions.

---

4. Key Terms in Simple Language

---

5. Step-by-Step Setup Guide

5.1 Institution Creation and Management

Creating a New Institution

Use this when you already have a confirmed deal and want to set up the institution immediately (skipping the pipeline).

1. In the left sidebar, click Sales → Institutions
2. Click the "Add Institution" button (top right)
3. Fill in the Basic Details section:
   • Institution Name — the official organization name (required)
   • Institution Type — select from the dropdown: University/College, Public Library, School (K-12), Corporate/Business, Nonprofit Organization, or Other (required)
   • Contact Name — primary point of contact at the institution (required)
   • Contact Email — their email address (required)
   • Contact Phone — phone number (optional)
   • Address — physical address (optional)
4. Expand the Billing & Tax Details section (click to expand):
   • GSTIN — 15-character GST identification number (optional)
   • PAN Number — 10-character PAN (optional)
   • Billing Address, Billing City, Billing State (dropdown), Billing Pincode — fill if different from primary address
5. Fill in the Subscription Details section:
   • Seats — how many user accounts this institution gets (required)
   • Subscription Plan — select from available plans in the dropdown (required)
   • Start Date — defaults to today (change if needed)
   • End Date — defaults to one year from today (change if needed)
   • Total Amount — contract value in INR (optional but recommended)
   • Currency — defaults to INR
   • Notes — any internal notes about this institution (optional)
6. Click "Save"

The institution is created with status Active and appears in the Institutions list.

Viewing and Editing an Institution

1. Go to Sales → Institutions
2. Use the search bar to find an institution by name, or use the Status and Type dropdown filters
3. Click the "View" button on any row (or click the row itself)
4. On the institution detail page, you can see:
   • Overview — all institution details, subscription dates, plan, seat usage, billing info
   • Users — table of all users added to this institution
   • Linked Opportunities — any renewal/upsell/winback opportunities created for this institution
5. To edit details, update the fields and save

Understanding Institution Metrics

At the top of the Institutions list page, you'll see four metric cards:

---

5.2 Sales Pipeline and Opportunity Management

Accessing the Pipeline

1. In the left sidebar, click Sales
2. The main Sales page shows the pipeline with metrics and opportunities

Understanding the Pipeline Layout

At the top of the page, you'll see:

• Header: "Sales Pipeline" with subtitle "Manage institutional opportunities and deals"
• Metric Cards:
  • Active Opportunities — count of all non-converted/non-declined opportunities
  • Pipeline Value — total expected value across all active opportunities
  • Avg Deal Size — average expected value per opportunity
  • Converted This Month — number of deals closed this month

Below the metrics:

• Search bar: "Search opportunities..." — search by institution name, contact name, or email
• Filters: Opportunity Type dropdown (All Types, New Inquiry, Renewal, Upsell, Win-back)
• View toggle: Switch between Kanban and List views

Using the Kanban View

The Kanban board has six columns:

Each column header shows:

• The stage name with a colored dot
• Number of opportunities in that stage
• Total pipeline value for that stage

Each opportunity card shows:

• Institution name (with building icon)
• Opportunity type badge (Inquiry, Renewal, Upsell, Win-back)
• Contact name (with user icon)
• Probability bar (color-coded: green for 75%+, blue for 50–74%, orange for 25–49%, red for below 25%)
• Expected value in INR (if set)
• Next follow-up date (with warning icon if overdue)
• Assigned team member (if assigned)

Pipeline Summary Bar (above the columns):

• Total Pipeline — sum of expected values
• Weighted Value — sum of (expected value × probability / 100) for all active deals
• Active Opportunities — count

Drag and Drop:

• Drag an opportunity card from one column to another to change its status
• You cannot drag into the Inactive column (it's automatically populated)
• The system updates the status immediately when you drop

Using the List View

Click the List button to switch to a table view. Columns include:

• Institution, Contact, Type, Status, Value, Created, Last Contact, Follow-up, Actions

Creating a New Opportunity

1. On the Sales Pipeline page, click "New Opportunity" (top right)
2. Fill in the Basic Information section:
   • Institution Name — the prospect's organization name (required)
   • Organization Type — select from dropdown (required)
   • Contact Name — person you're working with (required)
   • Contact Email — their email (required)
   • Contact Phone — their phone (optional)
3. Fill in the Opportunity Details section:
   • Opportunity Type — defaults to "New Inquiry"; change to Renewal, Upsell, or Win-back if applicable
   • Lead Source — how they found you: Website Form, Referral, Cold Outreach, Conference/Event, Email Campaign, Social Media, Partner, or Other (optional)
   • Estimated Seats — how many users the prospect might need (optional)
4. Fill in the Sales Metrics section:
   • Expected Value — estimated deal value in INR (optional)
   • Probability — your estimated close probability, defaults to 50% (0–100)
   • Next Follow-up Date — when you plan to contact them next (optional)
5. Add any Notes (optional)
6. Click "Create Opportunity"

The opportunity appears in the New column of the Kanban.

---

5.3 Managing Users Within an Institution

Adding Users to an Institution

1. Go to Sales → Institutions → click on the institution
2. In the Users section, click "Add Users"
3. Enter user details: Email and Name for each user
4. Click "Add"

What happens behind the scenes:

• The system creates a Reader account for each email (if one doesn't already exist) — these accounts are passwordless initially
• The user is linked to the institution with status Active
• The institution's seat count is checked — you cannot add more users than the licensed seats

Important: Adding users does NOT automatically send them login emails. You need to send invitations separately (see next section).

Viewing User Status

The Users table on the institution detail page shows:

Changing User Status

• Click the status toggle button next to a user to change them between Active and Deactivated
• Deactivating a user immediately revokes their active sessions (they get logged out)
• Click the Remove button to completely remove a user from the institution (does not delete their Reader account)

---

5.4 Sending Invitations to Institutional Users

Invitations send magic link login emails to users so they can access the platform without a password.

Sending Invitations (Bulk or Selective)

1. Go to Sales → Institutions → click on the institution
2. Option A: Send to all active users — click the "Send Invitations" button in the Quick Actions area
3. Option B: Send to specific users — check the boxes next to the users you want to invite, then click "Send Invitations" in the bulk actions bar

What happens:

• Each selected user receives an email with a magic login link
• The link is unique per user and valid for a single use
• The Invitation Sent column updates with today's date
• The system prevents re-sending to the same user within 24 hours

Requirements:

• The institution must have Active status
• The subscription must not be expired
• Users must have Active status and a linked Reader account

What the User Experiences

1. The user receives an email with a link to log in
2. They click the link, which takes them to the Reader Portal
3. If they're a new user, they set a password; if existing, they're logged in directly
4. Their status changes from Invited to Active once they activate
5. They receive a confirmation email (institutional_activation_success template)

---

5.5 Renewal Management

How Automatic Renewal Reminders Work

The system automatically sends reminder emails to the institution's contact person (not the users) at three intervals before the subscription expires:

These are handled by the cron job /api/cron/institutional-renewal-reminders. The system prevents duplicate reminders within a 6-day window.

Manually Renewing an Institution

1. Go to Sales → Institutions → click on the institution
2. Click the "Renew" button in the Quick Actions area
3. The Renew Subscription modal appears:
   • New End Date — select the new subscription end date (must be after the current end date)
   • Additional Seats — enter a number if the institution is adding more seats (optional)
   • Notes — any notes about this renewal (optional)
4. Click "Renew"

What happens:

• The institution's end date is updated
• If additional seats were specified, the total seat count increases
• The institution's status is set to Active (useful if it had expired)
• A Renewal History record is created (tracking previous dates, seats, and who renewed)
• A confirmation email is sent to the institution's contact person (institutional_renewal_confirmation template)

Viewing Renewal History

The renewal history is tracked in the system with full details:

• Previous end date and seat count
• New end date and seat count
• Total amount (if entered)
• Who performed the renewal and when

---

5.6 Converting an Opportunity to an Institution

When a deal closes and you want to set up the institution:

1. Go to the opportunity detail page (click on any opportunity in the pipeline)
2. Click the "Convert to Institution" button in the Quick Actions bar
3. The Convert Inquiry to Institution modal appears:
   • Seats — number of user accounts (required)
   • Subscription Plan — select from the dropdown (required)
   • Start Date — subscription start date
   • End Date — subscription end date
   • Total Amount — contract value in INR (optional)
   • Notes — any notes (optional)
   • Expand Billing & Tax Details if needed: GSTIN, PAN, Billing Address, City, State, Pincode
4. Click "Convert"

What happens:

• A new Institution record is created with the contact info from the opportunity
• The opportunity's status changes to Converted
• A "Converted" activity is logged in the opportunity's timeline
• The institution appears in Sales → Institutions
• If you checked the send welcome email option, the contact person receives an email (institutional_welcome template)

---

5.7 Logging Activities and Sending Emails from the Pipeline

Logging an Activity

1. Go to the opportunity detail page
2. Click the "Log Activity" button (or the dropdown arrow next to it)
3. Choose the activity type:
   • Log Call — record a phone conversation
   • Log Email — record an email you sent outside the system
   • Log Meeting — record a meeting (in-person or virtual)
   • Add Note — add an internal note
4. Fill in the modal:
   • Subject — brief description of the interaction (optional)
   • Notes — details of what was discussed (optional)
   • Next Follow-up Date — set the next follow-up date (optional)
5. Click "Log Activity"

The activity appears in the Activity Timeline on the opportunity page with a timestamp, the activity type icon, and who logged it.

Sending an Email from the Pipeline

1. Go to the opportunity detail page
2. Click the "Send Email" button
3. Choose your email mode:
   • Select Template — pick from 16+ pre-built templates organized by category:
     • Initial Outreach: Initial Follow-up, Demo Invitation, Information Request
     • Sales Process: Pricing Proposal, Proposal Sent, Contract Sent, Negotiation Follow-up, Meeting Confirmation
     • Follow-ups: General Follow-up
     • Renewal: Renewal Reminder, Renewal Confirmation
     • Upsell: Upsell Opportunity
     • Win-back: Win-back Outreach
     • Post-Conversion: Welcome/Onboarding, Thank You
   • Custom Email — write your own subject and body
4. Optionally set a Next Follow-up Date
5. Optionally attach files using Attachments (file upload)
6. Click "Send Email"

What happens:

• The email is sent to the opportunity's contact email
• A copy is CC'd to you (the sender)
• An "Email Sent" activity is logged in the timeline
• If the opportunity was in "New" status, it automatically moves to "Contacted"
• The lastContactedAt field is updated

Editing Contact Information

1. On the opportunity detail page, find the Contact Information panel
2. Click into the Contact Name, Contact Email, or Contact Phone fields to edit them
3. Click "Save" to save changes

Updating Sales Metrics

On the opportunity detail page, you can update:

• Status — change using the dropdown (New, Contacted, Negotiating, Converted, Declined)
• Expected Value — update the deal value
• Probability — slide between 0% and 100%
• Next Follow-up Date — set or change the next follow-up
• Notes — add or edit notes

Changes save automatically or on clicking Save.

---

5.8 Creating Opportunities from Existing Institutions

You can create renewal, upsell, or win-back opportunities directly from an existing institution:

1. Go to Sales → Institutions → click on the institution
2. Click the "Create Opportunity" button
3. Select from the dropdown:
   • Create Renewal Opportunity — for subscription renewals
   • Create Upsell Opportunity — for expanding the deal (more seats, higher plan)
   • Create Win-back Opportunity — for re-engaging a cancelled or expired institution
4. Fill in any additional details (expected value, notes, follow-up date)
5. The opportunity is created and linked to this institution

The linked opportunity appears in the Linked Opportunities section on the institution detail page.

---

5.9 Sales Reports and Analytics

1. Go to Sales → click the "Reports" button (or navigate to Sales → Reports)
2. The reports page shows:

3. Use the Date Range filter (Month, Quarter, Year) to adjust the view
4. Review the Metrics by Stage breakdown (New, Contacted, Negotiating counts)
5. Review the Metrics by Opportunity Type breakdown (New Inquiry, Renewal, Upsell, Win-back counts)

---

6. How to Verify It Worked

After Creating an Institution

After Creating an Opportunity

After Sending Invitations

After Renewing an Institution

After Converting an Opportunity

---

7. Worked Examples (End-to-End Scenarios)

Example 1: Creating a New Institution and Preparing It for Subscription Onboarding

Scenario: Delhi University has signed a contract for 200 seats on the Annual plan, starting April 1, 2026.

Steps:

1. Go to Sales → Institutions
2. Click "Add Institution"
3. Fill in:
   • Institution Name: Delhi University
   • Institution Type: University / College
   • Contact Name: Dr. Priya Sharma
   • Contact Email: priya.sharma@du.ac.in
   • Contact Phone: +91-9876543210
   • Address: North Campus, Delhi 110007
4. Expand Billing & Tax Details:
   • GSTIN: 07AABCU9603R1ZM
   • PAN Number: AABCU9603R
   • Billing Address: Accounts Department, North Campus
   • Billing City: New Delhi
   • Billing State: Delhi
   • Billing Pincode: 110007
5. Fill in Subscription Details:
   • Seats: 200
   • Subscription Plan: select Annual (or your institutional plan)
   • Start Date: 2026-04-01
   • End Date: 2027-03-31
   • Total Amount: ₹5,00,000
   • Notes: Contract #DU-2026-001. Payment via wire transfer.
6. Click "Save"

Verification:

• Go to Sales → Institutions — "Delhi University" appears with status "Active", 200 seats, 0 used
• Metric cards update: "Active Institutions" and "Total Seats" increase

Next Steps:

• Add users to the institution (Section 5.3)
• Send invitations so users can log in (Section 5.4)

---

Example 2: Creating and Tracking a New Sales Opportunity in the Pipeline

Scenario: You met a representative from Mumbai Public Library at a conference. They expressed interest in a 50-seat subscription.

Steps:

1. Go to Sales → click "New Opportunity"
2. Fill in Basic Information:
   • Institution Name: Mumbai Public Library
   • Organization Type: Public Library
   • Contact Name: Rajesh Mehta
   • Contact Email: rajesh.mehta@mumbailib.org
   • Contact Phone: +91-9988776655
3. Fill in Opportunity Details:
   • Opportunity Type: New Inquiry
   • Lead Source: Conference/Event
   • Estimated Seats: 50
4. Fill in Sales Metrics:
   • Expected Value: ₹1,50,000
   • Probability: 30
   • Next Follow-up Date: 2026-03-20
5. Notes: Met at LitFest 2026. Interested in digital-only plan for branch libraries.
6. Click "Create Opportunity"

Tracking over time:

Day 2 — Send initial email:

1. Open the opportunity from the Kanban (click the card in the "New" column)
2. Click "Send Email" → Select Template → "Initial Follow-up"
3. Set Next Follow-up Date to 2026-03-25
4. Click "Send Email"
5. Status automatically changes to "Contacted"

Day 7 — Log a call:

1. Click "Log Activity" → "Log Call"
2. Subject: Discussed pricing and seat options
3. Notes: Rajesh is checking budget approval. Expects answer by month-end.
4. Next Follow-up Date: 2026-04-01
5. Click "Log Activity"

Day 12 — Update probability:

1. On the opportunity detail page, change Probability from 30 to 60
2. Change status to "Negotiating" (or drag the card to the Negotiating column)

Day 20 — Deal closes:

1. Click "Convert to Institution"
2. Fill in: Seats: 50, Plan: Annual, Start Date: 2026-04-15, End Date: 2027-04-14
3. Click "Convert"
4. The opportunity moves to "Converted" and a new institution is created

Verification:

• Pipeline → Kanban: card is in "Converted" column
• Sales → Institutions: "Mumbai Public Library" is in the list with 50 seats
• Activity Timeline shows: Created → Email Sent → Call Logged → Status Changed → Converted

---

Example 3: Sending Invitations to Institutional Users and Verifying Activation

Scenario: Delhi University (from Example 1) has provided a list of 10 initial users to onboard.

Steps:

1. Go to Sales → Institutions → click Delhi University
2. Click "Add Users"
3. Enter the 10 users' email addresses and names:
   • student1@du.ac.in — Anika Gupta
   • student2@du.ac.in — Vikram Patel
   • ... (repeat for all 10)
4. Click "Add"
5. The Users table now shows 10 users, all with status "Active" and no invitation sent

Sending Invitations:

6. Click the "Send Invitations" button in Quick Actions
7. The system sends magic link emails to all 10 users
8. The "Invitation Sent" column updates with today's date for each user

Verifying Activation:

9. Ask one of the users (e.g., Anika) to check her email and click the login link
10. She is taken to the Reader Portal, sets a password, and gains access
11. Go back to the institution detail page and click "Refresh"
12. Anika's row now shows:
    • Status: Active (green badge)
    • Activated: today's date
    • Linked Reader: yes
13. The "Active Users" metric card increases from 0 to 1
14. The "Seats Used" on the Institutions list page updates

Verification:

• Institution detail → Users table: one or more users show "Active" status
• Institution detail → metric cards: "Active Users" matches the number who activated
• Institutions list → Seats column: shows "1/200" (or however many activated)
• The activated user can access subscriber-only content on the Reader Portal

---

Example 4: Handling an Institutional Renewal and Checking Reminder Behavior

Scenario: Bangalore International School's subscription expires on April 15, 2026. They want to renew for another year with 20 additional seats.

Automatic Reminders (no action needed from you):

• March 16 (30 days before): The cron job sends a renewal reminder email to the contact person
• April 1 (14 days before): Second reminder email sent
• April 8 (7 days before): Third reminder email sent

You can verify reminders were sent by checking:

• The contact person's email inbox
• The institution's renewal history (the system logs REMINDER_SENT entries)

Processing the Renewal:

1. Go to Sales → Institutions → click Bangalore International School
2. Note the alert: "Subscription expiring within 30 days" (if within 30 days)
3. Click the "Renew" button
4. In the modal:
   • New End Date: 2027-04-15
   • Additional Seats: 20
   • Notes: Renewed for AY 2026-27. Added 20 seats for new batch.
5. Click "Renew"

Verification:

• Institution detail → Overview:
  • End Date now shows 2027-04-15
  • Seats increased (e.g., from 100 to 120)
  • Status: "Active"
• Contact person receives a renewal confirmation email
• The "Expiring Soon" metric card on the Institutions list decreases
• All existing users continue to have access without interruption

---

Example 5: Following Up on an Institution Inquiry and Verifying Downstream Impact

Scenario: A nonprofit organization, Literacy Foundation, submitted an inquiry through the website. You need to nurture this lead and close the deal.

Step 1: Inquiry is in the pipeline

1. Go to Sales → Pipeline
2. Find "Literacy Foundation" in the New column
3. Click the card to open the detail page
4. Review the inquiry details: contact info, estimated seats, message

Step 2: Initial outreach

5. Click "Send Email" → Select Template → "Information Request"
6. The template auto-fills with the contact's name and institution name
7. Set Next Follow-up Date: 5 days from now
8. Click "Send Email"
9. Status moves to Contacted

Step 3: Follow-up call

10. When the follow-up date arrives, you'll see a warning icon on the opportunity
11. Call the contact and log the activity:
    • Click "Log Activity" → "Log Call"
    • Subject: Discussed pricing for 25 seats
    • Notes: Interested in digital-only annual plan. Needs board approval. Will confirm by end of month.
    • Next Follow-up Date: 2 weeks from now
12. Update Probability to 55%
13. Drag the card to Negotiating (or change status in the dropdown)

Step 4: Close the deal

14. After board approval, click "Convert to Institution"
15. Fill in:
    • Seats: 25
    • Subscription Plan: Annual
    • Start Date: 2026-05-01
    • End Date: 2027-04-30
    • Total Amount: ₹75,000
16. Check "Send Welcome Email" if available
17. Click "Convert"

Step 5: Onboard users

18. Go to Sales → Institutions → Literacy Foundation
19. Add users, send invitations (per Sections 5.3 and 5.4)

Verification of downstream impact:

---

8. Common Mistakes and How to Fix Them

"I can't see the Sales section in the sidebar"

Cause: Your admin role doesn't have institutions:read or institution_inquiries:read permissions. Fix: Ask your Super Admin to go to Settings → Admin Users → your account, and assign a role that includes sales permissions.

"I can't add more users to the institution"

Cause: You've reached the seat limit. Fix: Either:

• Renew the subscription with additional seats (Section 5.5)
• Remove inactive/deactivated users to free up seats
• Edit the institution to increase the seat count (if you have institutions:update permission)

"Invitation emails are not being sent"

Cause: Could be one of several issues:

1. SMTP not configured: Check Settings → Integrations → SMTP Status. If it shows "Not configured," contact your system admin.
2. Institution is not Active: Invitations can only be sent for active institutions with valid subscriptions.
3. User was already invited within 24 hours: The system prevents re-sending within 24 hours to avoid spam. Wait and try again.
4. User doesn't have a linked Reader account: Users must have Active status with a Reader account to receive invitations.

"I can't convert an opportunity to an institution"

Cause: Possible reasons:

1. Missing permissions: You need both institution_inquiries:update AND institutions:create permissions.
2. Opportunity already converted: An opportunity can only be converted once. Check if the status is already "Converted."
3. No subscription plans available: At least one subscription plan must exist. Check Subscriptions → Plans.

"Drag and drop is not working on the Kanban"

Cause: You cannot drag into the Inactive column (it's read-only/virtual). You also cannot change the status of a Converted opportunity. Fix: Drag between the other columns (New, Contacted, Negotiating, Declined). For converted deals, the status is final.

"Renewal reminders are not being sent automatically"

Cause: The cron job /api/cron/institutional-renewal-reminders may not be scheduled. Fix: Contact your DevOps team to verify the cron job is configured and running. It should run daily.

"I deleted an opportunity by mistake"

Cause: Only Declined opportunities can be deleted. If it was declined and deleted, it cannot be recovered. Fix: Create a new opportunity. For active opportunities, the delete button is disabled — only Declined status allows deletion.

"The overdue follow-up alert won't go away"

Cause: You have opportunities where the Next Follow-up Date is in the past. Fix: Open each overdue opportunity, update the follow-up date to a future date, or log an activity to update the last contact date.

"Expected value shows ₹0 or looks wrong"

Cause: The system stores amounts in paise (1/100 of a rupee) internally. Fix: Enter amounts in rupees in the UI — the system handles the conversion. If you see unexpected values, check whether the amount was entered in rupees or paise.

---