Skip to main content

Placio Subscriptions Management

The Admin System includes comprehensive subscription management features that allow administrators to manage workspace subscriptions, track service provider balances, and configure subscription-related settings.

Overview​

The Placio subscriptions management system provides multiple features:

  1. Workspace Subscription Management: Extend subscriptions, set discounts, manage invoice additions, allocate additional storage, and monitor subscription status
  2. Service Provider Balance Tracking: Monitor SMS service provider balances (e.g., Triple Core)
  3. Plan Management: Create and manage subscription plans with multiple billing periods
  4. Discount System: Apply workspace-level discounts to subscription prices
  5. Invoice Additions: Add custom, non-discountable charges to workspace monthly invoices
  6. Additional Storage Management: Allocate extra storage beyond plan limits

Triple Core SMS Balance​

The subscriptions page displays the remaining SMS message balance from Triple Core service provider.

Features​

  • Real-time Balance Display: Shows the current remaining message count
  • Status Monitoring: Displays the subscription status
  • Balance Alerts: Visual indicators for low, medium, and good balance levels
  • Manual Refresh: Ability to refresh balance data on demand

Configuration​

To use the Triple Core balance tracking feature, you need to configure the API token in the backend (main-api):

  1. Set the SMS_TRIPLE_CORE_API_TOKEN environment variable in your main-api .env file
  2. The token should be obtained from your Triple Core service provider account
  3. Restart the main-api service after setting the environment variable

Environment Variable​

In apps/main-api/.env:

SMS_TRIPLE_CORE_API_TOKEN=your_api_token_here

API Endpoint​

Backend Endpoint:

GET /v1/admin/placio-subscriptions/triple-core-balance

Requires: Admin authentication with dashboard.view permission

Response:

{
  "balance": 1000,
  "currency": "messages",
  "status": "active",
  "message": "Balance retrieved successfully"
}

The backend internally calls:

http://triple-core.ps/getbalance.php?api_token=<token>

Response Format​

The API returns balance information in one of the following formats:

  1. Number: Direct balance value

    1000

  2. Object: Structured response with additional metadata

    {
      "balance": 1000,
      "currency": "messages",
      "status": "active",
      "message": "Balance retrieved successfully"
    }

Balance Status Indicators​

  • Low: Balance < 100 messages (Red indicator)
  • Medium: Balance 100-500 messages (Yellow indicator)
  • Good: Balance > 500 messages (Green indicator)

Access​

Navigate to Placio Subscriptions in the admin system sidebar to access the subscriptions management page.

Workspace Subscription Management​

Administrators can manage workspace subscriptions directly from the workspace detail page in the admin dashboard.

Features​

1. Extend Subscription​

Extend a workspace's subscription by days or months:

  • Location: Workspace Detail Page → Subscription Management Section
  • Options:
    • Extend by days (1-365+ days)
    • Extend by months (1-12+ months)
  • Preview: Shows current subscription end date and calculated new end date before confirmation
  • Immediate Update: Subscription end date is updated immediately after extension

API Endpoint:

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

Request Body:

{
  "days": 30
}

or

{
  "months": 3
}

Response:

{
  "workspace": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Example Workspace",
    "subscriptionEndDate": "2024-12-31T23:59:59.000Z",
    ...
  },
  "newSubscriptionEndDate": "2024-12-31T23:59:59.000Z"
}

Authentication: Requires admin authentication with businesses.manage permission

2. Workspace Discount Management​

Set or remove discount percentages for workspace subscriptions:

  • Location: Workspace Detail Page → Discount Management Section
  • Range: 0-100% discount
  • Application: Discount is automatically applied to all plan prices during renewal
  • Removal: Set to null to remove discount

API Endpoint:

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

Request Body:

{
  "discountPercentage": 20
}

To remove discount:

{
  "discountPercentage": null
}

Response:

{
  "message": "Discount set to 20%",
  "workspace": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Example Workspace",
    "discountPercentage": 20,
    ...
  }
}

Authentication: Requires admin authentication with businesses.manage permission

3. Invoice Additions Management​

Add custom, non-discountable charges to workspace monthly invoices:

  • Location: Workspace Detail Page → Subscription Information Tab → Invoice Additions Management
  • Features:
    • Add custom charges with reason, quantity, and unit price
    • Edit existing invoice additions
    • Delete invoice additions
    • View all invoice additions for a workspace
  • Non-Discountable: Invoice additions are NOT subject to workspace discount
  • Automatic Calculation: Total is calculated as quantity × unit price

API Endpoints:

List Invoice Additions:

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

Create Invoice Addition:

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

Request Body:

{
  "reason": "Additional 1GB storage",
  "quantity": 1,
  "unitPrice": 2.00
}

Update Invoice Addition:

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

Request Body:

{
  "reason": "Additional 2GB storage",
  "quantity": 2,
  "unitPrice": 2.00
}

Delete Invoice Addition:

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

Response Example:

{
  "id": "507f1f77bcf86cd799439013",
  "reason": "Additional 1GB storage",
  "quantity": 1,
  "unitPrice": 2.00,
  "total": 2.00,
  "createdAt": "2024-01-15T10:00:00.000Z",
  "createdBy": "507f1f77bcf86cd799439014"
}

Authentication: Requires admin authentication with businesses.manage permission

4. Additional Storage Management​

Allocate extra storage (in MB) to workspaces beyond their plan's storage limit:

  • Location: Workspace Detail Page → Subscription Information Tab → Additional Storage Management
  • Features:
    • Set additional storage in MB (must be >= 0)
    • Total storage quota = Plan storage + Additional storage
    • Storage quota calculation automatically includes additional storage
    • Real-time storage usage tracking includes additional storage

API Endpoint:

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

Request Body:

{
  "additionalStorageMB": 1024
}

Response:

{
  "message": "Workspace storage updated successfully",
  "workspace": {
    "id": "507f1f77bcf86cd799439011",
    "additionalStorageMB": 1024,
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

Authentication: Requires admin authentication with businesses.manage permission

Subscription Information Display​

Workspace subscription information is displayed in:

  1. Workspace List Page:

    • Subscription end date
    • Subscription status (active, warning, expired)
    • Days remaining

  2. Workspace Detail Page - Subscription Information Tab:

    • Subscription Overview: Current plan, remaining days, end date
    • Monthly Price Breakdown:
      • Base plan price
      • Applied discount (if any)
      • Price after discount
      • Invoice additions (custom charges)
      • Total monthly price
    • Discount Management: Set workspace-specific discount percentage
    • Subscription Extension: Extend subscription by days or months
    • Invoice Additions Management: Add, edit, delete custom charges
    • Additional Storage Management: Allocate extra storage beyond plan limits

Subscription Status​

The system tracks three subscription states:

  • Active: More than 10 days remaining
  • Warning: 10 days or less remaining
  • Expired: Subscription end date has passed

Plan Management​

Administrators can create and manage subscription plans with multiple billing periods. See Plans Management documentation for details.

Key Features​

  • Multiple Billing Periods: Each plan can have monthly, quarterly, semiannual, and annual pricing
  • Multi-Currency Support: Plans can be priced in different currencies (USD, ILS, JOD, EUR, etc.)
  • Trial Periods: Configure trial periods for new workspaces
  • Localized Content: Plans support multiple languages with translations
  • Feature Flags: Configure plan-specific features and limits

Subscription Renewal Flow​

When workspace owners renew their subscriptions:

  1. Plan Selection: Choose from available plans (excluding free plan)
  2. Period Selection: Select billing period (monthly, quarterly, semiannual, annual)
  3. Price Calculation:
    • Base plan price is retrieved from plan's price period
    • Workspace discount (if set) is applied to base plan price
    • Invoice additions (if any) are added to the total
    • Total Payment = (Plan Price × (1 - Discount/100)) + Sum of Invoice Additions
  4. Payment: Complete payment via card or WhatsApp
  5. Extension: Subscription is extended based on selected period:
    • Monthly: +30 days
    • Quarterly: +90 days
    • Semiannual: +180 days
    • Annual: +365 days

Monthly Invoice Calculation​

The monthly invoice amount is calculated as follows:

Monthly Invoice = (Plan Monthly 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 Invoice: $80.00 + $2.00 + $50.00 = $132.00

Important Notes:

  • Discount applies ONLY to the base plan price
  • Invoice additions are NOT subject to discount
  • Invoice additions are added after discount is applied

Future Enhancements​

Additional subscription providers and features may be added in future updates, including:

  • Multiple service provider support
  • Historical balance tracking
  • Automated alerts for low balances
  • Subscription analytics and reporting
  • Bulk subscription management
  • Automated subscription renewal reminders