Skip to main content

Workspace Subscription

What it is​

The Workspace Subscription system tracks subscription end dates for each workspace and manages access control based on subscription status. Workspaces receive warnings before subscription expiration and are blocked from accessing the system when subscriptions expire.

Who it's for​

Workspace Owner

Access & Scope​

PropertyValue
Moduleworkspace-subscription
Personasworkspace-owner
ScopeWorkspace-level
UI LocationDashboard (banner), Subscription Renewal Page
Statusactive

UI Location​

  • Warning Banner: Appears at the top of the dashboard when subscription is within 10 days of expiration
  • Expired Page: Redirected to /subscription/expired when subscription has expired
  • Select Plan Page: Accessible at /subscription/select-plan for choosing a subscription plan
  • Renewal Page: Accessible at /subscription/renew for subscription renewal with period selection
  • Subscription Info Tab: Dedicated tab in Workspace Settings (Dashboard > Settings > Subscription Info) displaying current subscription details, monthly invoice additions, and expected renewal price

How it works​

The Workspace Subscription system manages subscription lifecycle through several components:

1. Subscription Initialization​

  • When a new workspace is created, the subscription end date is automatically calculated based on the plan's trial period
  • Formula: subscriptionEndDate = createdAt + plan.trialPeriodDays
  • If the plan has no trial period, the subscription end date is set to the creation date (workspace starts with an expired subscription, requiring immediate renewal)

2. Subscription States​

The system recognizes three subscription states:

  • Active: Subscription is valid and more than 10 days remain until expiration
  • Warning: Subscription is valid but 10 days or less remain until expiration
  • Expired: Subscription end date has passed

3. Access Control​

  • Active State: Full access to all workspace features
  • Warning State: Full access with a warning banner displayed at the top of the dashboard
  • Expired State: Access is blocked, redirects to the subscription expired page

4. Warning System​

  • 10-Day Warning: When 10 days or less remain until expiration, a warning banner is displayed
  • Email Notification: An automated email is sent when the subscription enters the warning state (10 days remaining)
  • Banner Display: The warning banner appears on all dashboard pages, showing:
    • Number of days remaining
    • Link to renewal page

5. Plan Selection​

Before renewing a subscription, workspace owners can choose from available plans:

  1. Navigate to the Select Plan page at /subscription/select-plan
  2. View all available subscription plans (excluding the free plan)
  3. Each plan displays:
    • Plan name and description
    • Available billing periods (monthly, quarterly, semiannual, annual)
    • Prices for each period
    • Plan features
  4. Select a plan to proceed to the renewal page
  5. The selected plan ID is passed to the renewal page via URL query parameter

Note: If the current plan is "free", users are automatically redirected to the select plan page when attempting to renew.

6. Subscription Renewal​

Workspace owners can renew their subscription through a multi-step process:

Step 1: Plan Selection (if needed)​

  • If changing plans or on free plan, select a plan from the plan selection page
  • If renewing current plan, proceed directly to renewal page

Step 2: Period Selection​

Each plan supports multiple billing periods with different pricing:

  • Monthly: 30 days - Best for short-term commitments
  • Quarterly: 90 days (3 months) - Balanced option
  • Semiannual: 180 days (6 months) - Mid-term commitment
  • Annual: 365 days (1 year) - Long-term commitment with potential savings

The renewal page displays:

  • All available periods for the selected plan
  • Original price for each period
  • Discounted price (if workspace has a discount percentage applied)
  • Discount percentage indicator (if applicable)
  • Currency code (USD, ILS, JOD, EUR, etc.)

Step 3: Payment Method Selection​

Choose between two payment methods:

Method 1: WhatsApp Payment​
  1. Select "WhatsApp" as payment method
  2. Click the "Open WhatsApp" button
  3. This opens WhatsApp with a pre-filled message to the support team
  4. After payment is confirmed, an admin manually updates the subscription end date
Method 2: Card Payment (Mock)​
  1. Select "Card" as payment method
  2. Fill in card details:
    • Cardholder name
    • Card number (formatted with spaces)
    • Expiry date (MM/YY format)
    • CVV
  3. Submit the form
  4. The system automatically extends the subscription based on the selected period:
    • Monthly: +30 days
    • Quarterly: +90 days
    • Semiannual: +180 days
    • Annual: +365 days
  5. Success message is displayed, and the user is redirected to the dashboard

Note: The card payment form is currently a mock implementation. All card details are accepted, and the payment is processed automatically.

Renewal Flow Restrictions​

  • Trial Period Active: If the trial period hasn't ended yet (and user didn't come from select-plan with a new plan), renewal is blocked until trial expires
  • Free Plan: Cannot renew free plan - must select a paid plan first
  • Period Required: Must select a billing period before proceeding with payment

7. Discount System​

Workspaces can have a discount percentage applied to subscription prices:

  • Discount Range: 0-100% (set by administrators)
  • Application: Discount is automatically applied to all plan prices during renewal
  • Display:
    • Original price shown with strikethrough
    • Discounted price displayed prominently
    • Discount percentage shown as a badge
  • Calculation: discountedPrice = originalPrice × (1 - discountPercentage / 100)

Example: If a plan costs $100/month and workspace has 20% discount:

  • Original: $100.00
  • Discounted: $80.00
  • Badge: "خصم 20%"

8. Workspace Owner Subscription Information​

Workspace owners can view comprehensive subscription information directly in the workspace settings:

Subscription Info Tab​

A dedicated tab in the workspace settings provides complete subscription information:

  1. Current Plan Display:

    • Plan name and description
    • Plan icon and visual indicator

  2. Subscription Status:

    • Active, Warning, or Expired status badge
    • Color-coded status indicators

  3. Remaining Days:

    • Large display of days remaining until expiration
    • Formatted expiration date
    • Visual warning when subscription is near expiration

  4. Monthly Invoice Additions:

    • Complete list of all monthly invoice additions
    • For each addition:
      • Reason/description
      • Quantity and unit price
      • Monthly total (quantity × unit price)
    • Total monthly additions sum
    • Displayed in workspace currency

  5. Expected Renewal Price:

    • Calculated monthly price breakdown:
      • Base plan price (with discount applied if applicable)
      • Monthly invoice additions total
      • Total monthly price
    • Currency symbol display
    • Discount percentage indicator (if applicable)

Access Location​

  • UI Location: Dashboard > Settings > Subscription Info Tab
  • Persona: Workspace Owner
  • Permissions: Available to all workspace owners

Features​

  • Real-time Calculation: All prices are calculated in real-time based on current plan and invoice additions
  • Currency Support: Prices displayed in workspace currency (USD, ILS, JOD, EUR)
  • Discount Visibility: Shows applied discount percentage and discounted price
  • Transparency: Clear breakdown of all charges included in monthly subscription
  • Renewal Link: Direct link to renewal page when subscription is near expiration (10 days or less)

9. Admin Subscription Management​

Administrators have comprehensive subscription management tools in the admin dashboard:

Subscription Information Tab​

A dedicated tab in the admin workspace detail page provides complete subscription information:

  1. Subscription Overview:

    • Current plan name
    • Remaining days until expiration
    • Subscription end date

  2. Monthly Price Breakdown:

    • Base plan price (from plan's monthly price period)
    • Applied discount (if any) with discount percentage
    • Price after discount
    • Invoice additions (custom charges) with details
    • Total monthly price (plan after discount + invoice additions)

  3. Discount Management:

    • Set workspace-specific discount percentage (0-100%)
    • Discount applies to all plan prices
    • Can be removed by setting to null

  4. Subscription Extension:

    • Extend subscription by days or months
    • Preview new subscription end date before confirmation
    • Immediate update after extension

  5. Invoice Additions Management:

    • Add custom, non-discountable charges to monthly invoice
    • Each addition includes: reason, quantity, unit price
    • Full CRUD operations: Create, Read, Update, Delete
    • Additions are added to monthly invoice without discount
    • Track creation date and admin who added it

  6. Additional Storage Management:

    • Add extra storage (in MB) beyond plan allocation
    • Total storage = Plan storage + Additional storage
    • Storage quota calculation automatically includes additional storage

Access Location​

  • UI Location: Admin Dashboard > Workspaces > [Workspace Detail] > Subscription Information Tab
  • Permissions: businesses.manage required

Features​

Warning Banner​

  • Displays on all dashboard pages when subscription is within warning threshold
  • Shows days remaining until expiration
  • Provides direct link to renewal page
  • Styled with warning colors (amber/yellow)

Subscription Expired Page​

  • Full-screen page blocking access to the workspace
  • Clear message explaining that subscription has expired
  • Link to renewal page
  • Link to return to home page

Select Plan Page​

  • Displays all available subscription plans (excluding free plan)
  • Shows plan features, pricing, and available billing periods
  • Plan selection navigates to renewal page with selected plan ID
  • Current plan indicator (if applicable)
  • Responsive grid layout for plan comparison

Subscription Renewal Page​

  • Plan Display: Shows selected plan name and details
  • Period Selection: Radio button interface for choosing billing period
    • Monthly, Quarterly, Semiannual, Annual options
    • Price display with currency
    • Discount indicator (if applicable)
    • Original vs. discounted price comparison
  • Payment Method Selection: Choose between WhatsApp or Card payment
  • Card Payment Form: Mock implementation with card details input
  • WhatsApp Integration: Pre-filled message with direct link
  • Success State: Confirmation message after successful renewal
  • Automatic Redirect: Redirects to dashboard after 3 seconds
  • Change Plan Button: Option to go back and select a different plan

Admin Subscription Management​

  • View subscription end date in workspace list and detail pages
  • Extend subscription by days or months
  • Preview new subscription end date before confirmation
  • Immediate update after extension

Subscription End Date Calculation​

Initial Calculation (Workspace Creation)​

subscriptionEndDate = createdAt + plan.trialPeriodDays

Extension Calculation​

By Days​

newEndDate = currentEndDate + days

By Months​

newEndDate = currentEndDate + months

Renewal Calculation (Card Payment)​

The renewal calculation depends on the selected billing period:

// Period-based calculation
switch (period) {
  case 'monthly':
    newEndDate = currentEndDate + 30 days
  case 'quarterly':
    newEndDate = currentEndDate + 90 days
  case 'semiannual':
    newEndDate = currentEndDate + 180 days
  case 'annual':
    newEndDate = currentEndDate + 365 days
  default:
    newEndDate = currentEndDate + 30 days (monthly fallback)
}

Note: If no period is specified, defaults to monthly (30 days).

Email Notifications​

Subscription Warning Email​

  • Trigger: When subscription enters warning state (10 days remaining)
  • Frequency: Sent once (tracked by subscriptionWarningSentAt field)
  • Content:
    • Workspace name
    • Subscription end date (formatted)
    • Days remaining
    • Renewal link (optional)

API Endpoints​

Client Endpoints​

  • GET /v1/client/plans - Get all available plans with price periods

    • Query: locale (optional, for localized plan names)
    • Response: { plans: Plan[] } where each plan includes:
      • id, name, slug, description
      • pricePeriods: Array of { period: 'monthly'|'quarterly'|'semiannual'|'annual', amountCents: number, currencyCode: string }
      • features, flags, trialPeriodDays

  • POST /v1/workspace/:workspaceId/subscription/renew

    • Body: { paymentMethod: 'whatsapp' | 'card', period?: 'monthly' | 'quarterly' | 'semiannual' | 'annual', cardDetails?: { cardNumber, expiryDate, cvv, cardholderName } }
    • Response: { success: boolean, newSubscriptionEndDate?: string, message: string }

Admin Endpoints​

  • PATCH /v1/admin/workspaces/:workspaceId/subscription/extend

    • Body: { days?: number, months?: number }
    • Response: { workspace: WorkspaceSummary, newSubscriptionEndDate: string }

  • PATCH /v1/admin/workspaces/:workspaceId/discount

    • Body: { discountPercentage: number | null } (0-100, or null to remove)
    • Response: { workspace: WorkspaceSummary, message: string }

  • GET /v1/admin/workspaces/:workspaceId/invoice-additions

    • Response: { additions: InvoiceAddition[] }

  • POST /v1/admin/workspaces/:workspaceId/invoice-additions

    • Body: { reason: string, quantity: number, unitPrice: number }
    • Response: { message: string, addition: InvoiceAddition }

  • PATCH /v1/admin/workspaces/:workspaceId/invoice-additions/:additionId

    • Body: { reason?: string, quantity?: number, unitPrice?: number }
    • Response: { message: string, addition: InvoiceAddition }

  • DELETE /v1/admin/workspaces/:workspaceId/invoice-additions/:additionId

    • Response: { message: string }

  • PATCH /v1/admin/workspaces/:workspaceId/storage

    • Body: { additionalStorageMB: number }
    • Response: { message: string, workspace: WorkspaceSummary }

Technical Details​

Database Fields​

Workspace Model:

  • subscriptionEndDate: Date | null - The date when the subscription expires
  • subscriptionWarningSentAt: Date | null - Timestamp when warning email was sent (prevents duplicate emails)
  • discountPercentage: number | null - Discount percentage (0-100) applied to subscription prices
  • additionalStorageMB: number - Additional storage in MB beyond plan allocation (default: 0)
  • invoiceAdditions: InvoiceAddition[] - Array of custom invoice additions (non-discountable charges)

InvoiceAddition Schema:

  • reason: string - Description/reason for the addition
  • quantity: number - Quantity (must be > 0)
  • unitPrice: number - Unit price in USD (must be >= 0)
  • createdAt: Date - Creation timestamp
  • createdBy: ObjectId - Admin ID who created the addition

Plan Model:

  • pricePeriods: PlanPricePeriod[] - Array of pricing periods, each containing:
    • period: 'monthly' | 'quarterly' | 'semiannual' | 'annual'
    • amountCents: number - Price in cents
    • currencyCode: string - Currency code (USD, ILS, JOD, EUR, etc.)

Middleware​

  • checkWorkspaceSubscription middleware is applied to all client routes with workspaceId parameter
  • Blocks requests with 403 Forbidden if subscription has expired
  • Allows requests to proceed if subscription is active or in warning state

Background Jobs (Optional)​

  • A scheduled job can be set up to periodically check for subscriptions entering the warning state
  • The checkAndSendWarnings() function in subscription-notification.service.ts can be called by a cron job

Subscription Periods​

The system supports four billing periods, each with different pricing:

PeriodDurationDays Added on RenewalUse Case
Monthly30 days+30 daysShort-term, flexible commitment
Quarterly90 days (3 months)+90 daysBalanced option for medium-term users
Semiannual180 days (6 months)+180 daysMid-term commitment with better value
Annual365 days (1 year)+365 daysLong-term commitment, often with best pricing

Period Selection​

  • Plans can have one or more available periods
  • Each period has its own price (in cents) and currency
  • Users must select a period before completing payment
  • Period selection affects the subscription extension duration

Price Periods in Plans​

Each plan can define multiple price periods:

{
  period: 'monthly',
  amountCents: 4900,      // $49.00
  currencyCode: 'USD'
}

Plans can have different prices for different periods, allowing for:

  • Discounted annual pricing
  • Regional currency support
  • Flexible pricing strategies

Discount System​

Workspace-Level Discounts​

Administrators can set a discount percentage (0-100%) for any workspace:

  • Automatic Application: Discount is automatically applied to all plan prices during renewal
  • Visual Feedback:
    • Original price shown with strikethrough
    • Discounted price displayed prominently
    • Discount percentage badge
  • Calculation: Applied to the base price before display
  • Removal: Set to null to remove discount

Example Discount Flow​

  1. Plan has monthly price: $100.00
  2. Workspace has discount: 20%
  3. Display shows:
    • $100.00 (original, strikethrough)
    • $80.00 (discounted, bold)
    • "خصم 20%" badge

Invoice Additions​

Overview​

Invoice additions are custom charges that administrators can add to a workspace's monthly subscription invoice. These additions are non-discountable and are added to the total invoice amount after the plan price discount is applied.

Features​

  • Custom Charges: Add any custom charge with reason, quantity, and unit price
  • Non-Discountable: Invoice additions are NOT subject to workspace discount
  • Automatic Calculation: Total is automatically calculated as quantity × unit price
  • Full Management: Create, read, update, and delete invoice additions
  • Tracking: Each addition tracks creation date and admin who added it

Calculation​

The total monthly invoice is calculated as:

Total Monthly Price = (Plan Price × (1 - Discount/100)) + Sum of Invoice Additions

Example:

  • Plan monthly price: $100.00
  • Workspace discount: 20%
  • Plan price after discount: $80.00
  • Invoice additions:
    • Additional 1GB storage: $2.00
    • Premium support: $50.00
  • Total Monthly Price: $80.00 + $2.00 + $50.00 = $132.00

Use Cases​

  1. Additional Services: Charge for extra services beyond plan features
  2. Storage Add-ons: Add charges for additional storage beyond plan limits
  3. Support Tiers: Premium support charges
  4. Custom Features: One-time or recurring custom feature charges
  5. Overage Charges: Charges for usage beyond plan limits

Additional Storage​

Overview​

Administrators can allocate additional storage (in MB) to workspaces beyond their plan's storage limit. This additional storage is added to the plan's storage quota to calculate the total available storage.

Features​

  • Flexible Allocation: Add any amount of storage in MB
  • Automatic Calculation: Total quota = Plan storage + Additional storage
  • Real-time Tracking: Storage usage tracking automatically includes additional storage
  • Quota Management: Storage quota calculation factors in additional storage

Calculation​

Total Storage Quota = Plan maxstorage flag + additionalStorageMB

Example:

  • Plan storage limit: 5 GB (5120 MB)
  • Additional storage: 1 GB (1024 MB)
  • Total Storage Quota: 5120 MB + 1024 MB = 6144 MB (6 GB)

Use Cases​

  1. Storage Upgrades: Provide extra storage to specific workspaces
  2. Promotional Storage: Offer additional storage as part of promotions
  3. Custom Plans: Allocate storage based on custom agreements
  4. Overage Management: Add storage when workspace approaches limit
  • Workspace Settings: General workspace configuration
  • Plans: Subscription plans, price periods, and trial periods
  • Email Notifications: Subscription warning emails
  • Admin Workspace Management: Admin tools for subscription management, discount configuration, invoice additions, and storage allocation
  • Payment Settings: Configuration for enabled payment methods (card, WhatsApp)
  • Storage Tracking: Monitor storage usage including additional storage