Skip to main content

API Changelog (v1)

This document summarizes all recent changes, additions, and updates to the Placio API v1.

Recent Updates​

Payments Management System​

Added: Complete unified payments management system for tracking all workspace payments.

New Endpoints​

  • GET /api/v1/admin/payments - List all workspace payments with filtering and pagination
  • GET /api/v1/admin/payments/stats - Get payment statistics (total, monthly, weekly, daily)
  • POST /api/v1/admin/payments - Create a new manual payment record
  • PATCH /api/v1/admin/payments/:paymentId - Update an existing manual payment
  • DELETE /api/v1/admin/payments/:paymentId - Delete a manual payment record

Features​

  • Payment Types: Supports four payment types:

    • ai-tools: Payments for AI tool usage and credits
    • sms: Payments for SMS message credits
    • storage: Payments for additional storage capacity
    • subscription: Payments for workspace subscription renewals

  • Payment Methods: Cash, bank transfer, card, and other payment methods

  • Automatic Payment Recording: System automatically creates payment records for:

    • Subscription renewals (when workspace renews subscription)
    • SMS payments (when admin adds SMS payment)
    • AI tools payments (when admin adds AI tools payment)

  • Manual Payment Management: Admins can add, edit, and delete manual payments for offline transactions

  • Advanced Filtering: Filter by workspace, payment type, date range, and manual/automatic status

  • Statistics: Real-time statistics for total, monthly, weekly, and daily payments

Documentation​

Expenses Management System​

Added: Complete expenses management system for tracking platform operational costs.

New Endpoints​

  • GET /api/v1/admin/expenses - List all platform expenses with filtering and pagination
  • GET /api/v1/admin/expenses/stats - Get expense statistics with category breakdown
  • POST /api/v1/admin/expenses - Create a new expense record
  • GET /api/v1/admin/expenses/:expenseId - Get a single expense by ID
  • PATCH /api/v1/admin/expenses/:expenseId - Update an existing expense
  • DELETE /api/v1/admin/expenses/:expenseId - Delete an expense record
  • POST /api/v1/admin/expenses/:expenseId/receipt - Upload a receipt image for an expense

Features​

  • Expense Categories: Six predefined categories:

    • services: Service-related expenses
    • salaries: Employee salaries and wages
    • rent: Office rent and facility costs
    • utilities: Utility bills (electricity, water, internet)
    • marketing: Marketing and advertising expenses
    • other: Other miscellaneous expenses

  • Receipt Management: Upload and attach receipt images to expenses

  • Advanced Filtering: Filter by category and date range

  • Statistics: Comprehensive statistics with category breakdown:

    • Total expenses (all time)
    • This month's expenses
    • This week's expenses
    • Today's expenses
    • Breakdown by category

Documentation​

Dashboard Enhancements​

Updated: Admin dashboard endpoints with enhanced financial data.

Updated Endpoints​

  • GET /api/v1/admin/dashboard/overview - Enhanced with payment and expense statistics
  • GET /api/v1/admin/dashboard/revenue - New endpoint for detailed revenue, expenses, and net income

New Features​

  • Payment Statistics: Dashboard overview now includes:

    • Payment statistics (today, this week, this month)
    • Revenue breakdown by payment type (AI tools, SMS, storage, subscription)
    • Monthly recurring revenue (MRR)

  • Expense Statistics: Dashboard overview now includes:

    • Expense statistics (today, this week, this month)
    • Expense count and totals

  • Revenue Analysis: New revenue endpoint provides:

    • Time-series breakdown of revenue and expenses
    • Net income calculation (revenue - expenses)
    • Support for multiple time periods (today, week, month, custom range)
    • Detailed breakdown by time buckets

Documentation​

Database Schema Changes​

New Models​

WorkspacePayment Model​

{
  workspaceId: ObjectId (required, indexed),
  paymentType: 'ai-tools' | 'sms' | 'storage' | 'subscription' (required, indexed),
  amount: Number (required, min: 0),
  paymentMethod: 'cash' | 'bank-transfer' | 'card' | 'other' (required),
  paymentDate: Date (required, indexed),
  description: String (optional),
  notes: String (optional),
  isManual: Boolean (required, default: false),
  createdBy: ObjectId (optional, ref: 'Admin'),
  receiptImage: Object | null,
  metadata: Object (optional),
  createdAt: Date (auto),
  updatedAt: Date (auto)
}

Expense Model​

{
  amount: Number (required, min: 0),
  date: Date (required, indexed),
  description: String (required),
  category: 'services' | 'salaries' | 'rent' | 'utilities' | 'marketing' | 'other' (required, indexed),
  receiptImage: Object | null,
  notes: String (optional),
  createdBy: ObjectId (required, ref: 'Admin'),
  createdAt: Date (auto),
  updatedAt: Date (auto)
}

Indexes Added​

  • WorkspacePayment:

    • { workspaceId: 1, paymentDate: -1 }
    • { workspaceId: 1, paymentType: 1 }
    • { paymentDate: -1 }
    • { paymentType: 1, paymentDate: -1 }

  • Expense:

    • { date: -1 }
    • { category: 1, date: -1 }
    • { createdBy: 1, date: -1 }

Integration Changes​

Automatic Payment Creation​

The system now automatically creates WorkspacePayment records when:

  1. Subscription Renewal: When a workspace renews subscription via /workspace/:workspaceId/subscription/renew

    • Calculates payment amount from plan price
    • Applies workspace discount if available
    • Records payment method
    • Sets isManual: false

  2. SMS Payment: When admin adds SMS payment via SMS tracking service

    • Creates both SmsPayment and WorkspacePayment
    • Links via metadata.smsPaymentId
    • Sets isManual: true

  3. AI Tools Payment: When admin adds AI tools payment via AI tracking service

    • Creates both AiPayment and WorkspacePayment
    • Links via metadata.aiPaymentId
    • Sets isManual: true

Authentication & Permissions​

New Permissions​

  • payments.view: Required to view payments list and statistics
  • payments.manage: Required to create, update, or delete payments
  • dashboard.view: Required to view expenses (reuses existing permission)

Response Format Changes​

Payment Response​

All payment endpoints now return consistent response format with:

  • Workspace information (id, name, email)
  • Payment details (type, amount, method, date)
  • Receipt image information (if available)
  • Metadata for type-specific data
  • Manual/automatic flag

Expense Response​

All expense endpoints return:

  • Expense details (amount, date, description, category)
  • Receipt image information (if available)
  • Creator information
  • Timestamps

Breaking Changes​

None. All changes are additive and backward compatible.

Migration Notes​

For Existing Integrations​

  • No migration required for existing endpoints
  • New endpoints are optional and can be integrated gradually
  • Automatic payment creation is transparent and doesn't affect existing flows

For New Integrations​

  • Use the new unified payments endpoints for all payment tracking
  • Use expenses endpoints for platform cost tracking
  • Leverage dashboard endpoints for comprehensive financial overview

Future Enhancements​

Planned improvements:

  1. Payments:

    • Export payments to CSV/Excel
    • Payment reports and analytics
    • Recurring payment management
    • Payment reminders
    • Integration with accounting systems

  2. Expenses:

    • Expense approval workflows
    • Budget tracking
    • Expense reports
    • Category management

  3. Dashboard:

    • Advanced analytics and insights
    • Custom date range comparisons
    • Export capabilities
    • Real-time updates

Version History​

  • v1.0.0 (Current): Initial release with payments and expenses management
  • All endpoints follow v1 versioning policy (see API Intro)