CloudPOS Documentation

# SaaS Configuration

This guide covers configuring the multi-tenant SaaS features: plans, limits, tenant onboarding, and subscription management.

# Understanding the SaaS Model

CloudPOS is a multi-tenant SaaS system, meaning:

  • One installation serves multiple tenants (clients)
  • Each tenant has isolated data
  • Tenants subscribe to plans with different features/limits
  • You manage everything from the Admin Panel

# Creating Subscription Plans

# Step 1: Access Plans Section

  1. Login to Admin Panel: http://localhost:5173/admin/login
  2. Navigate to Plans → Create Plan

# Step 2: Configure Plan Details

Fill in the form:

  • Name: Plan name (e.g., "Basic", "Pro", "Enterprise")
  • Description: Plan description (shown to tenants)
  • Monthly Price: Price per month (e.g., 29.99)
  • Yearly Price: Price per year (e.g., 299.99)
  • Currency: ISO code (e.g., USD)
  • Billing Cycle: Default cycle (Monthly or Yearly)
  • Is Active: Toggle to enable/disable plan
  • Is Popular: Mark as featured plan
  • Sort Order: Display order (lower = first)

# Step 3: Configure Plan Features

Add features list (JSON array format):

[
  "Unlimited products",
  "Up to 5 users",
  "2 branches",
  "Email support",
  "Basic reports"
]

# Step 4: Configure Plan Limits

Set limits (JSON object format):

{
  "users": 5,
  "branches": 2,
  "products": 1000,
  "storage": 1073741824,
  "api_calls": 10000
}

Common limits:

  • users: Maximum number of users
  • branches: Maximum number of branches
  • products: Maximum number of products
  • storage: Storage in bytes (e.g., 1GB = 1073741824)
  • api_calls: API calls per month

# Step 5: Configure Stripe Price IDs (If Using Stripe)

If you're using Stripe for payments:

  1. Get Price IDs from Stripe Dashboard:

    • Go to Stripe Dashboard → Products
    • Create products for each plan
    • Copy Price IDs (e.g., price_1234567890)

  2. Add to Plan:

    • Stripe Price ID (Monthly): price_xxxxx
    • Stripe Yearly Price ID: price_xxxxx

  3. Save Plan

# Plan Assignment Flow

# How Plans Are Assigned

  1. Tenant Registers

    • Tenant creates account via registration page
    • Account created with no active plan

  2. Tenant Subscribes

    • Tenant navigates to Subscription page
    • Selects a plan
    • Completes payment (if Stripe configured)
    • Plan is automatically assigned

  3. Admin Manual Assignment

    • Admin can manually assign plans via Admin Panel
    • Useful for free trials or custom arrangements

# Verifying Plan Assignment

Check tenant subscription:

  1. Admin Panel → Tenants → Select tenant
  2. Go to Subscription tab
  3. View:
    • Current plan
    • Subscription status (ACTIVE, TRIAL, etc.)
    • Start/end dates
    • Payment history

# Subscription Statuses

Status Description
TRIAL Free trial period active
ACTIVE Subscription active and paid
SUSPENDED Payment failed or past due
CANCELLED Subscription cancelled
EXPIRED Subscription expired

# Plan Limits Enforcement

CloudPOS enforces plan limits automatically:

# How Limits Work

  1. When tenant tries to create resource:

    • System checks current count
    • Compares to plan limit
    • Blocks if limit exceeded

  2. Error message shown:

    Plan limit exceeded: You've reached your plan limit for users (5/5). 
Upgrade to continue.

# Common Limit Checks

  • Users: When creating new user
  • Branches: When creating new branch
  • Products: When creating new product
  • Storage: When uploading files
  • API Calls: When making API requests

# Bypassing Limits (Admin)

Admins can:

  • Manually assign higher plans
  • Temporarily increase limits
  • Override limits for specific tenants

# Tenant Onboarding Process

# Step 1: Tenant Registration

Option A: Self-Registration

  1. Tenant visits: https://yourdomain.com/register
  2. Fills registration form:
    • Email
    • Password (min 8 chars, uppercase, lowercase, number)
    • First name, Last name
    • Company name (tenant name)
    • Subdomain (optional, if using subdomain routing)
  3. Submits form
  4. Receives email verification (if enabled)

Option B: Admin Creates Tenant

  1. Admin Panel → Tenants → Create Tenant
  2. Fill tenant details
  3. Create tenant
  4. Send login credentials to tenant

# Step 2: Email Verification (Optional)

If email verification is enabled:

  1. Tenant receives verification email
  2. Clicks verification link
  3. Account activated

# Step 3: Plan Selection

  1. Tenant logs in
  2. Sees "Subscribe to a Plan" prompt
  3. Navigates to Subscription → Plans
  4. Selects plan
  5. Completes payment (if Stripe configured)

# Step 4: Access Granted

After subscription:

  1. Tenant can access full system
  2. Can create users, branches, products
  3. Limited by plan limits

# Managing Tenant Subscriptions

# View All Subscriptions

  1. Admin Panel → Subscriptions
  2. View list of all subscriptions
  3. Filter by status, plan, date

# Manual Plan Assignment

  1. Admin Panel → Tenants → Select tenant
  2. Go to Subscription tab
  3. Click Assign Plan
  4. Select:
    • Plan
    • Billing cycle (Monthly/Yearly)
    • Start date
    • End date (optional)
  5. Click Assign

# Cancel Subscription

  1. Admin Panel → Subscriptions → Select subscription
  2. Click Cancel Subscription
  3. Choose:
    • Cancel Immediately: Access revoked now
    • Cancel at Period End: Access until current period ends
  4. Confirm cancellation

# Suspend Tenant

  1. Admin Panel → Tenants → Select tenant
  2. Click Suspend
  3. Tenant loses access immediately
  4. Can reactivate later

# Subscription Webhooks (Stripe)

If using Stripe, webhooks automatically update subscriptions:

# Webhook Events Handled

  • checkout.session.completed - Assigns plan after payment
  • customer.subscription.created - Creates subscription
  • customer.subscription.updated - Updates subscription status
  • customer.subscription.deleted - Cancels subscription
  • invoice.payment_succeeded - Activates subscription
  • invoice.payment_failed - Suspends subscription

# Webhook Configuration

See Payment Gateway for Stripe webhook setup.

# Cron Jobs / Scheduled Tasks

CloudPOS uses NestJS Schedule for automated tasks:

# Subscription Expiry Check

Automatically checks and updates expired subscriptions:

  • Runs: Daily at midnight
  • Action: Marks expired subscriptions as EXPIRED
  • Location: server/src/subscriptions/ (scheduled task)

# Email Notifications

Sends email notifications for:

  • Subscription expiry warnings
  • Payment failures
  • Subscription renewals

# Testing the SaaS Flow

# Test Tenant Registration

  1. Go to: http://localhost:5173/register
  2. Fill registration form
  3. Submit
  4. Verify tenant created in Admin Panel

# Test Plan Assignment

  1. Login as tenant
  2. Navigate to Subscription page
  3. Select a plan
  4. Complete checkout (test mode)
  5. Verify plan assigned in Admin Panel

# Test Plan Limits

  1. Assign Basic plan (e.g., 5 users limit)
  2. Login as tenant
  3. Try to create 6th user
  4. Verify limit error appears

# Troubleshooting

# Plan Not Assigning After Payment

Issue: Payment succeeds but plan not assigned

Solutions:

  1. Check webhook configuration:

    • Verify webhook URL in Stripe Dashboard
    • Check webhook secret in Admin Panel
    • View webhook logs in Stripe Dashboard

  2. Check subscription logs:

    • Admin Panel → Subscriptions → Select subscription
    • View Logs tab
    • Look for errors

  3. Manually assign plan:

    • Admin Panel → Tenants → Select tenant
    • Manually assign plan

# Plan Limits Not Enforcing

Issue: Tenant can exceed plan limits

Solutions:

  1. Verify plan limits configured:

    • Check plan JSON limits
    • Ensure limits are numbers, not strings

  2. Check subscription status:

    • Subscription must be ACTIVE or TRIAL
    • Expired subscriptions may not enforce limits

  3. Review code:

    • Limits enforced in backend guards
    • Check server logs for errors

# Tenant Can't Access After Subscription

Issue: Tenant subscribed but can't login

Solutions:

  1. Check subscription status:

    • Must be ACTIVE or TRIAL
    • Check subscription end date

  2. Verify tenant is active:

    • Admin Panel → Tenants → Check "Is Active"

  3. Check user account:

    • Verify user email is verified (if required)
    • Check user is not deleted

Next: See Payment Gateway to set up Stripe payments.

← Payment Gateway Setup →