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.

The big picture (one diagram)

---

How It Works (Behind the Scenes)

The Sales system is an Admin Console feature backed entirely by PostgreSQL (via Prisma) — there is no Strapi involvement here. Everything you do in the UI writes to a small family of Postgres tables, and reader access is granted by linking institution users to existing Reader accounts.

Step by step, what actually happens:

1. An opportunity is created (POST /api/institution-inquiries) → a row in institution_inquiries with status = new, opportunityType = new_inquiry, probability = 50 by default. A created entry is written to inquiry_activities.
2. You work the deal — logging activities (inquiry_activities), sending email (POST /api/institution-inquiries/:id/send-email), dragging across stages (updates status). Sending an email auto-bumps new → contacted and sets lastContactedAt.
3. You convert (POST /api/institution-inquiries/:id/convert) → a new row in institutions (status = active, with seats, planId, startDate, endDate), the inquiry's status becomes converted, and convertedToId links the two. An optional institutional_welcome email fires.
4. You add users (POST /api/institutions/:id/users) → rows in institution_users with status = invited, each linked to a Reader account (created if needed). An invited member holds a seat but does not yet have reader access. The seat cap (active + invited) is enforced here.
5. You send login emails (POST /api/institutions/:id/invite) → magic-link emails via the Email System; loginEmailSentAt is stamped (24h resend throttle). The email does not grant access and does not activate the member — it simply lets them sign in. On their first successful sign-in (which runs the OTP + Terms/Privacy gate), the member is promoted invited → active and activatedAt is stamped (activateInstitutionUserOnLogin). Only an active member, on a non-expired active institution, gets reader-portal access.
6. Renewals (POST /api/institutions/:id/renew) extend endDate, optionally add seats, write a renewal_history row, and email an institutional_renewal_confirmation.
7. The cron (/api/cron/institutional-renewal-reminders) runs daily, finds institutions nearing endDate, and sends 30/14/7-day reminders, recording each in institution_reminder_logs (idempotency, keyed by institution + endDate + window).

---

Concepts: Pipeline, Institutions & Institutional Subscriptions

Four ideas anchor the whole system.

• Opportunity (a.k.a. Inquiry) — a potential deal, stored in institution_inquiries. It has an opportunity type (new_inquiry, renewal, upsell, winback), a pipeline stage (new, contacted, negotiating, converted, declined), value tracking (expectedValue in paise, probability 0–100), and follow-up tracking. An "Inactive" Kanban column is virtual — it surfaces deals with no contact for 30+ days; it is not a stored status.
• Institution — a confirmed customer account, stored in institutions. It owns the commercial relationship: type, contacts, billing/tax details, offline-payment fields, and the institutional subscription (seats, planId, startDate, endDate, status, totalAmount). Default status on raw create is pending; conversion creates it directly as active.
• Institutional subscription — not a separate table, but the subscription-bearing fields on the institution row plus the linked SubscriptionPlan. The plan should be marked Audience = Institutional so it never leaks into self-service flows. Seats define the licensed user ceiling. A plan marked Audience = Institutional stays out of every self-service flow — it does not appear in the public /subscribe catalog, the admin Create-Reader Grant dialog, the Change Plan dialog, or the Send Payment Link modal — which guarantees a library/university plan is never accidentally sold to an individual.
• Institutional user — a member of the institution, stored in institution_users and linked one-to-one to a Reader account (readerId). Status is invited, active, or deactivated. A member is created as invited (holds a seat, may receive a login link, but has no reader access), becomes active on first sign-in (this is what grants subscriber access in the Reader Portal), and can be deactivated to revoke access and free their seat. Both invited and active members consume a seat; deactivated members do not.

A deal's lifecycle through the pipeline:

An institutional member's lifecycle (institution_users.status):

---

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. (Optional) Fill in the Offline Payment section to record how the institution actually paid, since institutional commercials are negotiated and paid outside the platform:
   • Offline Payment Mode — one of Bank Transfer / Cheque / Cash / Other
   • Offline Payment Reference — bank reference, cheque number, internal invoice ID, or any free-text identifier
   • Offline Payment Date — the date the payment was received
7. 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 Invited — they hold a seat but do not have reader access yet
• An invited member becomes Active only after their first magic-link sign-in
• The institution's seat count is checked against active + invited members — you cannot add more users than the licensed seats

Important: Adding users does NOT automatically send them login emails, and it does NOT grant access. You need to send invitations separately (see next section), and the member only gains access once they sign in for the first time.

When an invited member clicks their sign-in link for the first time, they complete the standard OTP + Terms/Privacy flow before access is granted, and their status is promoted from Invited to Active. Members without a prior Terms acceptance record will see the Terms/Privacy checkbox (needsTermsAcceptance) — this is intentional and ensures GDPR-compliant consent for every member.

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) and frees their seat
• Re-activating a deactivated user restores access (subject to seat availability) without requiring them to go through the magic link again
• 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 Login Email 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 be login-eligible — Invited or Active status — and have a linked Reader account (Deactivated users are skipped)

What the User Experiences

1. The user receives an email with a magic link to log in
2. They click the link, which takes them to the Reader Portal
3. They complete the OTP + Terms/Privacy gate — they verify a one-time code sent to their email and, if they have no prior Terms acceptance record, tick the Terms/Privacy checkbox
4. On this first successful sign-in the system promotes them Invited → Active and stamps activatedAt
5. They can now read subscriber-only content (access is granted by the institution's plan, but only once they are active)

---

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)

---

Configuration Reference

Every field you can set, what it does, and where it lives. UI path is relative to the Admin Console (:3000). Role is the minimum permission needed.

Opportunity / Deal fields (institution_inquiries)

Activity fields (inquiry_activities)

Institution fields (institutions)

Institutional subscription & provisioning fields

Renewal fields (renewal_history, set via Renew modal)

Backend-only / not user-editable: convertedToId, linkedInstitutionId resolution, lastContactedAt, loginEmailSentAt, activatedAt, reminder_day/endDate in institution_reminder_logs, and all createdAt/updatedAt audit timestamps are written by the system, not entered in the UI.

---

Dependencies & Impact

The Sales system does not stand alone. Here is what it touches and what depends on it.

It depends on:

• Subscriptions — every institution must reference a SubscriptionPlan. The plan should be flagged Audience = Institutional so it stays out of self-service catalogs, the Create-Reader Grant dialog, Change Plan, and Send Payment Link. At least one plan must exist before you can create or convert.
• Reader Management — institutional users are real Reader accounts. Adding a user creates a Reader if one doesn't exist; the readerId link plus Active membership status is what grants subscriber access. An invited or active member of a live institution is classified as the institutional tier in the reader directory (this is the institutional lock/badge on the reader card — see Reader Management), and bulk / complimentary / gift provisioning is classified as subscriber even when the plan price is 0. Deactivating a user revokes their sessions and frees their seat.
• Email System — magic-link logins, renewal reminders/confirmations, welcome emails, and pipeline outreach all route through the notification service. The subscription_lifecycle and inquiry_followup purposes must be mapped to a verified email account, and templates (institutional_login, institutional_welcome, institutional_renewal_reminder, institutional_renewal_confirmation) must be seeded.
• Admin Settings & RBAC — visibility and actions are gated by the institutions:* and institution_inquiries:* permissions listed in §3.
• Automated Tasks (Cron) — /api/cron/institutional-renewal-reminders drives the 30/14/7-day reminder cycle; without it, reminders never fire.

What it impacts / cross-links:

• Reader Management — institutional onboarding creates/links Reader accounts that then appear in reader lists and can read subscriber-only content.
• Future Readers — Sales Institutions and Future Readers Institutes are separate models; use the Sync to Future Readers action on the institution detail page to associate them.
• Analytics — converted revenue, active institutions, seat utilization, and pipeline metrics feed the Sales Reports view and broader analytics.
• Email System — each conversion, invite, and renewal generates outbound email whose deliverability you can monitor there.

---

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 Invited and no invitation sent. All 10 already consume a seat (10/200 used).

Sending Invitations:

6. Click the "Send Invitations" button in Quick Actions
7. The system sends magic link emails to all 10 invited users
8. The "Login Email Sent" column updates with today's date for each user — note the status stays Invited

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, completes the OTP + Terms/Privacy gate, and gains access
11. Go back to the institution detail page and click "Refresh"
12. Anika's row now shows:
    • Status: Active (green badge) — promoted from Invited
    • Activated: today's date
    • Linked Reader: yes
13. The "Active Members" metric card increases from 0 to 1 (and "Invited" decreases from 10 to 9)
14. The "Seats Used" on the Institutions list page already reflected all 10 (invited members hold seats)

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. Remember that seats are consumed by both Invited and Active members — invited members who have never signed in still hold a seat. Fix: Either:

• Renew the subscription with additional seats (Section 5.5)
• Deactivate or remove members you no longer need (deactivating frees their seat)
• 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. No email account configured: Go to Settings → Email → Accounts, click an account, and click Verify connection. If it fails, fix the credentials. If no accounts exist, click + New email account. See the Email System Guide.
2. subscription_lifecycle purpose not mapped: Go to Settings → Email → Purposes and confirm the row has a primary account.
3. Institution is not Active: Invitations can only be sent for active institutions with valid subscriptions.
4. User was already invited within 24 hours: The system prevents re-sending within 24 hours to avoid spam. Wait and try again.
5. 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.

---

Known Limitations

---

FAQ

Common questions about institutional (B2B) accounts, seats, gifting, and billing entitlements.