Recurring Expenses Management

What it is

A comprehensive system that allows workspace owners to create rules for recurring expenses (rent, subscriptions, utilities, etc.) and automatically generate expense occurrences. The system tracks upcoming, pending, posted, and skipped occurrences, and allows users to post occurrences as actual expenses or skip them.

Who it's for

Workspace Owner
Staff (with financial permissions)

Access & Scope

Property	Value
Module	workspace-financial
Personas	workspace-owner, staff
Scope	Workspace-level
UI Location	Dashboard > Payments & Expenses > Recurring Expenses Tab
Status	active

UI Location

Dashboard > Payments & Expenses > Recurring Expenses Tab

How it works

The Recurring Expenses Management system automates the tracking of expenses that repeat on a schedule. Instead of manually creating expense records for recurring items like rent, subscriptions, or utility bills, you create a rule once and the system automatically generates expense occurrences based on the schedule.

Recurring Expense Rules

Create rules that define how expenses repeat:

Frequencies

• Daily: Expenses that occur every day

  • Example: Daily office supplies, daily cleaning service
  • Creates occurrences every day from start date

• Monthly: Expenses that occur on a specific day of each month

  • Example: Monthly rent (day 1), monthly subscription (day 15)
  • Requires specifying day of month (1-31)
  • Creates occurrences on the specified day of each month

• Yearly: Expenses that occur on a specific date each year

  • Example: Annual insurance (January 1), annual license renewal (March 15)
  • Requires specifying month (1-12) and day of month (1-31)
  • Creates occurrences on the specified date each year

Rule Configuration

Each recurring expense rule includes:

• Title: Name for the recurring expense (e.g., "Office Rent", "Internet Subscription")
• Amount: Fixed amount per occurrence (in workspace currency)
• Currency: Workspace currency (defaults to workspace currency)
• Start Date: When the recurring expense begins generating occurrences
• End Date: Optional end date when the recurring expense should stop (leave empty for ongoing)
• Day of Month: For monthly expenses, the day of month (1-31) when expense occurs
• Month of Year: For yearly expenses, the month (1-12) when expense occurs
• Category: Expense category (optional) - links to workspace expense categories
• Account: Account ID (optional) - for accounting integration
• Vendor: Vendor or payee name (optional) - e.g., "ABC Company", "Utility Provider"
• Notes: Additional notes (optional) - any relevant information

Rule Status

• Active: Rule is generating occurrences automatically
• Paused: Rule is temporarily disabled (no new occurrences generated)

Automatic Occurrence Generation

The system automatically generates expense occurrences based on rules:

Generation Process

1. Rule Creation: When you create a rule, the system immediately starts generating occurrences
2. Scheduled Generation: Occurrences are created in advance for upcoming periods
3. Frequency-Based:
   • Daily rules: Creates occurrences every day from start date
   • Monthly rules: Creates occurrences on specified day of month
   • Yearly rules: Creates occurrences on specified month and day of year
4. End Date Handling: If end date is set, no occurrences are created after that date

Occurrence Properties

Each generated occurrence includes:

• Rule Reference: Link to the parent rule
• Due Date: When the expense is due
• Amount: Amount from the rule
• Currency: Currency from the rule
• Status: Upcoming, Pending, Posted, or Skipped
• Metadata: Category, vendor, notes from the rule

Occurrence Management

Each generated occurrence has a status and can be managed:

Occurrence Statuses

• Upcoming: Occurrence is scheduled but not yet due

  • Future occurrences that haven't reached their due date
  • Automatically transitions to "Pending" when due date arrives

• Pending: Occurrence is due and needs attention

  • Current or past due occurrences that haven't been posted or skipped
  • These require action (post or skip)

• Posted: Occurrence has been converted to an actual expense

  • User posted the occurrence, creating an expense record
  • Expense record is linked to the occurrence
  • Cannot be posted again

• Skipped: Occurrence was skipped without creating expense

  • User chose to skip this occurrence
  • No expense record is created
  • Useful for expenses that don't apply in a specific period

Post Occurrence

Convert an occurrence to an actual expense record:

1. Select Occurrence: Choose a pending or upcoming occurrence
2. Post Action: Click "Post" or "ترحيل" button
3. Set Expense Date: Optionally set custom expense date (defaults to occurrence due date)
4. Create Expense: System creates expense record with:
   • Amount from occurrence
   • Category from rule (if set)
   • Date (custom or due date)
   • Description from rule title
   • Notes from rule
5. Mark Posted: Occurrence status changes to "Posted"
6. Link Created: Expense record is linked to occurrence

Skip Occurrence

Mark an occurrence as skipped without creating expense:

1. Select Occurrence: Choose a pending or upcoming occurrence
2. Skip Action: Click "Skip" or "تخطي" button
3. Confirm: Confirm skipping the occurrence
4. Mark Skipped: Occurrence status changes to "Skipped"
5. No Expense: No expense record is created

Features

Rule Management

• List Rules: View all recurring expense rules with filtering by status and frequency
• Create Rule: Add new recurring expense rule with full configuration
• Update Rule: Edit rule details (amount, schedule, status, metadata, etc.)
• Pause Rule: Temporarily disable a rule (stops generating new occurrences)
• Resume Rule: Re-enable a paused rule (resumes generating occurrences)
• Delete Rule: Remove recurring expense rule (does not delete occurrences)

Occurrence Management

• List Occurrences: View all occurrences with filtering by:
  • Rule (filter by specific rule)
  • Date range (from date, to date)
  • Status (upcoming, pending, posted, skipped)
  • Frequency (daily, monthly, yearly)
• Get Occurrence: View detailed occurrence information
• Post Occurrence: Convert occurrence to expense record
• Skip Occurrence: Mark occurrence as skipped
• Statistics: View comprehensive occurrence statistics

Statistics Dashboard

The system provides comprehensive statistics:

• Pending Occurrences:

  • Count of pending occurrences
  • Total amount of pending occurrences
  • Requires immediate attention

• Posted Occurrences:

  • Count of posted occurrences
  • Total amount of posted occurrences
  • Successfully converted to expenses

• Upcoming Occurrences:

  • Count of upcoming occurrences
  • Total amount of upcoming occurrences
  • Future expenses to plan for

• Skipped Occurrences:

  • Count of skipped occurrences
  • Total amount of skipped occurrences
  • Expenses that were not applied

Dashboard Widgets

Recurring expenses are fully integrated into the dashboard with dedicated widgets:

1. Recurring Expenses Stats Widget

Widget ID: recurring-expenses-stats
Default Size: 8 × 6
Status: ✅ Implemented

Comprehensive statistics widget showing:

• Pending occurrences count and total amount
• Posted occurrences count and total amount
• Upcoming occurrences count and total amount
• Skipped occurrences count and total amount
• Visual indicators and color coding

2. Upcoming Recurring Expenses Widget

Widget ID: upcoming-recurring-expenses
Default Size: 6 × 6
Status: ✅ Implemented

List of the next 5-10 upcoming recurring expense occurrences showing:

• Title (from rule)
• Vendor (if set)
• Due date
• Amount
• Status indicator

3. Recurring Expenses This Month Widget

Widget ID: recurring-expenses-this-month
Default Size: 4 × 3
Status: ✅ Implemented

Shows:

• Total value of all recurring expenses scheduled for current month
• Count of occurrences in current month
• Visual summary card

4. Pending Recurring Expenses Widget

Widget ID: pending-recurring-expenses
Default Size: 4 × 3
Status: ✅ Implemented

Displays:

• Count of pending recurring expenses
• Total value of pending expenses
• Requires attention indicator

5. Active Recurring Expense Rules Widget

Widget ID: active-recurring-expense-rules
Default Size: 4 × 3
Status: ✅ Implemented

Shows:

• Count of active recurring expense rules
• Quick overview of configured rules

6. Recurring Expenses by Frequency Widget

Widget ID: recurring-expenses-by-frequency
Default Size: 8 × 6
Status: ✅ Implemented

Pie chart showing:

• Distribution of recurring expenses by frequency
• Daily expenses: count and total amount
• Monthly expenses: count and total amount
• Yearly expenses: count and total amount
• Visual breakdown with percentages

Advanced Filtering

Rule Filtering

• Status Filter: Filter by active or paused rules
• Frequency Filter: Filter by daily, monthly, or yearly
• Pagination: Configurable page size (1-1000 items per page)

Occurrence Filtering

• Rule Filter: Filter by specific rule
• Date Range: Filter by from date and to date
• Status Filter: Filter by upcoming, pending, posted, or skipped
• Frequency Filter: Filter by daily, monthly, or yearly
• Pagination: Configurable page size (1-1000 items per page)

Use Cases

1. Rent Management:

   • Create monthly rent rule (day 1 of each month)
   • System generates monthly occurrences
   • Post occurrences when rent is paid

2. Subscription Tracking:

   • Track software subscriptions (monthly on day 15)
   • Monitor service subscriptions
   • Track membership renewals

3. Utility Bills:

   • Track monthly utility expenses (electricity, water, internet)
   • Set different days for different utilities
   • Post when bills are received

4. Salary Payments:

   • Automate salary expense tracking
   • Set monthly salary rule
   • Post when salaries are paid

5. Annual Expenses:

   • Track yearly expenses (insurance, licenses, renewals)
   • Set specific dates for annual payments
   • Plan for large annual expenses

6. Budget Planning:

   • Plan for recurring expenses in advance
   • View upcoming expenses
   • Track pending expenses

Settings

The Recurring Expenses Management feature includes the following configuration options:

1. Rule Settings:

   • Frequency selection (daily, monthly, yearly)
   • Amount and currency
   • Start and end dates
   • Day of month (for monthly)
   • Month of year (for yearly)
   • Category, vendor, notes

2. Display Settings:

   • Rules list with pagination
   • Occurrences list with pagination
   • Statistics dashboard
   • Filter options

3. Occurrence Settings:

   • Default expense date (use due date or custom)
   • Auto-post option (future feature)

Permissions

Access to Recurring Expenses Management requires:

• Workspace Owner: Has full access to create, update, and delete rules, and manage occurrences
• Staff: Access based on financial permissions
  • financial.view: Required to view recurring expenses
  • financial.manage: Required to create, update, or delete rules and post/skip occurrences

Note: Recurring expenses contain sensitive financial information. Access is typically restricted to workspace owners and staff with financial permissions.

API Integration

The Recurring Expenses Management system is fully integrated with the workspace API:

Recurring Expense Rules Endpoints

• List Rules: GET /api/v1/client/workspace/:workspaceId/recurring-expense-rules
• Get Rule: GET /api/v1/client/workspace/:workspaceId/recurring-expense-rules/:ruleId
• Create Rule: POST /api/v1/client/workspace/:workspaceId/recurring-expense-rules
• Update Rule: PATCH /api/v1/client/workspace/:workspaceId/recurring-expense-rules/:ruleId
• Pause Rule: POST /api/v1/client/workspace/:workspaceId/recurring-expense-rules/:ruleId/pause
• Resume Rule: POST /api/v1/client/workspace/:workspaceId/recurring-expense-rules/:ruleId/resume
• Delete Rule: DELETE /api/v1/client/workspace/:workspaceId/recurring-expense-rules/:ruleId

Recurring Expense Occurrences Endpoints

• List Occurrences: GET /api/v1/client/workspace/:workspaceId/recurring-expense-occurrences
• Get Occurrence: GET /api/v1/client/workspace/:workspaceId/recurring-expense-occurrences/:occurrenceId
• Get Occurrence Stats: GET /api/v1/client/workspace/:workspaceId/recurring-expense-occurrences/stats
• Post Occurrence: POST /api/v1/client/workspace/:workspaceId/recurring-expense-occurrences/:occurrenceId/post
• Skip Occurrence: POST /api/v1/client/workspace/:workspaceId/recurring-expense-occurrences/:occurrenceId/skip

See API Documentation for detailed endpoint documentation.

Best Practices

1. Create Rules Early: Set up recurring expense rules as soon as you identify recurring expenses
2. Use Descriptive Titles: Use clear, descriptive titles for rules (e.g., "Office Rent - Main Building")
3. Set Appropriate Categories: Link rules to expense categories for better organization
4. Review Regularly: Periodically review pending occurrences and post them promptly
5. Use Skip Wisely: Only skip occurrences when the expense truly doesn't apply
6. Monitor Statistics: Regularly check statistics to understand recurring expense patterns
7. Update Rules: Keep rule amounts and schedules up to date
8. Use Dashboard Widgets: Add recurring expense widgets to dashboard for quick overview

Notes / Limits

1. Rule Limits:

   • No limit on number of rules per workspace
   • Each rule generates occurrences independently
   • Rules can be paused/resumed without losing data

2. Occurrence Generation:

   • Occurrences are generated in advance
   • System generates occurrences for upcoming periods
   • Past occurrences are not automatically generated (only from start date forward)

3. Occurrence Status:

   • Occurrences automatically transition from "Upcoming" to "Pending" when due date arrives
   • Posted occurrences cannot be unposted (expense record must be deleted separately)
   • Skipped occurrences cannot be unskipped (create manual expense if needed)

4. Date Handling:

   • All dates use workspace timezone
   • Day of month for monthly: 1-31 (system handles months with fewer days)
   • Yearly dates: System handles leap years correctly

5. Amount and Currency:

   • Amount is fixed per occurrence (cannot vary)
   • Currency is set at rule level
   • All occurrences from a rule use the same amount and currency

6. Rule Updates:

   • Updating rule amount affects future occurrences only
   • Updating schedule affects future occurrences only
   • Posted occurrences are not affected by rule updates

7. Rule Deletion:

   • Deleting a rule does not delete occurrences
   • Occurrences remain but lose link to rule
   • Posted occurrences remain linked to expense records

8. Performance:

   • Large numbers of rules (100+) may impact performance
   • Large numbers of occurrences may require pagination
   • Statistics are calculated in real-time

Future Enhancements

Potential improvements:

• Variable amounts per occurrence
• Multiple frequencies per rule (e.g., bi-weekly)
• Auto-post option for occurrences
• Recurring expense templates
• Budget alerts for recurring expenses
• Integration with accounting systems
• Recurring expense reports
• Email reminders for pending occurrences

Changelog

Recent Updates

• Initial release with complete recurring expenses management system
• Support for daily, monthly, and yearly frequencies
• Automatic occurrence generation
• Post and skip occurrence functionality
• Comprehensive statistics dashboard
• Six dedicated dashboard widgets
• Full API integration