WiFi Management System

English

简体中文

English

简体中文

Theme

Package Sales ​

Track and manage all package transactions, renewals, and assignments to customers.

Overview ​

Package Sales are transaction records that track when packages are sold, assigned, or renewed for subscribers. Each sale captures pricing, bandwidth limits, data quotas, and validity periods.

Key Concepts:

  • Package Sale - A transaction record linking a subscriber to a package with specific terms
  • Active Sale - Currently valid package assignment for a subscriber
  • Expired Sale - Past package that has exceeded its validity period
  • Renewal - Creating a new package sale to extend or upgrade a subscriber's access

Navigate to Package Sales in the sidebar to view all transactions.

Viewing Package Sales ​

Package Sales List ​

The package sales list displays all transactions across your network with powerful filtering options.

Available Columns:

  • Subscriber - Customer name/username (click to view subscriber details)
  • Package - Package name (click to view package details)
  • Location - Where the sale occurred
  • Status - Active, Inactive, or Expired (color-coded badges)
  • Bandwidth - Upload/download speed limits
  • Data Limit - Data quota (shows "Unlimited" for unlimited packages)
  • Sale Price - Amount charged to subscriber
  • Valid Until - Expiration date
  • Days Remaining - Countdown until expiry (for active packages)

Filtering Options:

  • Status Filter - Filter by active, inactive, or expired
  • Subscriber Filter - View sales for specific customer
  • Location Filter - View sales at specific location
  • Date Range - Filter by sale creation date
  • Search - Search by subscriber name or package name

Sorting: Click any column header to sort ascending/descending.

Package Sale Details ​

Click any row to view comprehensive sale information.

Status Overview ​

Quick dashboard showing:

  • Status Badge - Visual indicator (green=active, red=expired, gray=inactive)
  • Days Remaining - Countdown for active packages
  • Sale Price - Amount charged (formatted with currency)
  • Expiry Date - When package expires

Subscriber Information ​

Customer details for this sale:

  • Full name and username
  • Email and phone number
  • Link to subscriber profile

Package Information ​

Details about the sold package:

  • Package name and type (Standard, Premium, Trial)
  • Package description
  • Link to package template

Bandwidth & Data Limits ​

Technical specifications:

  • Upload Speed - Bandwidth cap for uploads (e.g., "1024 kbps")
  • Download Speed - Bandwidth cap for downloads (e.g., "2048 kbps")
  • Data Limit - Total data quota (e.g., "5 GB" or "Unlimited")

Speed Units

  • kbps - Kilobits per second (k = kilobit)
  • mbps - Megabits per second (m = megabit)
  • 1024 kbps = 1 mbps

Validity Information ​

Expiration tracking:

  • Valid Until - Exact expiration date and time
  • Is Expired - Yes/No indicator
  • Days Remaining - Countdown (negative numbers show days overdue)

System Information ​

Audit trail:

  • Created By - User who created the sale
  • Updated By - User who last modified the sale
  • Created At - Original transaction timestamp
  • Updated At - Last modification timestamp

Selling Packages ​

Renewing Subscribers ​

To sell a package to an existing subscriber:

  1. Go to Subscribers page
  2. Click the subscriber you want to renew
  3. Click Renew button in the subscriber details
  4. Select the package from the dropdown
  5. Click Confirm

What Happens:

  • New PackageSale record is created
  • Package specifications copied to the sale
  • Subscriber's current package updated
  • State transition logged in audit trail
  • Expiration calculated based on package validity settings

Renewal vs New Sale

Renewing creates a fresh package sale with a new validity period. The old package sale remains in history but is no longer the active package.

Voucher-Based Sales ​

Packages can also be sold through vouchers:

  1. Customer receives voucher code
  2. Customer activates voucher during WiFi login
  3. System automatically creates PackageSale record
  4. Package assigned to subscriber's account

See Vouchers for voucher management.

Editing Package Sales ​

Modify package sale terms after creation.

Editable Fields ​

Click Edit button on the package sale details page to modify:

Status - Change between:

  • Active - Package is currently valid and usable
  • Inactive - Package is disabled (subscriber loses access)
  • Expired - Package validity has ended

Upload Bandwidth - Adjust upload speed limit

  • Amount (number)
  • Unit (k=kilobits, m=megabits)

Download Bandwidth - Adjust download speed limit

  • Amount (number)
  • Unit (k=kilobits, m=megabits)

Data Limit - Modify data quota

  • Amount (0 for unlimited)
  • Unit (MB or GB)

Sale Price - Update the charged amount (for record-keeping)

Valid Until - Extend or shorten validity period

Live Changes

Changes to bandwidth and data limits apply immediately to active subscribers. Use caution when modifying active packages.

Common Modifications ​

Extend Expiration:

Valid Until: 2024-12-31 → 2025-01-31

Useful for customer service exceptions or promotions.

Upgrade Bandwidth:

Download: 1024 kbps → 2048 kbps
Upload: 512 kbps → 1024 kbps

Upgrade customer mid-package without renewal.

Add More Data:

Data Limit: 5 GB → 10 GB

Top up data quota for active package.

Deactivate Package:

Status: Active → Inactive

Immediately disable subscriber access without waiting for expiry.

Package Sale Status ​

Understanding the three status states:

Active ​

Meaning: Package is currently valid and subscriber can use it.

Characteristics:

  • valid_till is in the future
  • Subscriber has network access
  • Bandwidth and data limits enforced
  • Shows green badge in UI

Transitions To:

  • Expired - Automatically when valid_till passes
  • Inactive - Manually by admin

Inactive ​

Meaning: Package is disabled regardless of validity date.

Characteristics:

  • Subscriber loses network access immediately
  • Can be reactivated by changing status back to Active
  • Shows gray badge in UI
  • Used for temporary suspensions

Use Cases:

  • Customer payment issues
  • Policy violations
  • Temporary account holds
  • Testing/troubleshooting

Expired ​

Meaning: Package validity period has ended.

Characteristics:

  • valid_till is in the past
  • Subscriber loses network access
  • Cannot be changed back to Active (use renewal instead)
  • Shows red badge in UI
  • Historical record maintained

Status vs Expiration

Status "Expired" is set automatically by the system when valid_till passes. Admins cannot manually set status to "Expired" - use "Inactive" for manual deactivation.

Pricing & Revenue Tracking ​

Price Tiers ​

The system tracks three price levels:

  1. Cost Price - Wholesale cost (in OperatorPackage)
  2. Location Price - Price to resellers/locations (in OperatorPackage)
  3. Sale Price - Price charged to subscriber (in PackageSale)

Example:

yaml
Package: Premium WiFi
  Cost Price: $50 (your cost)
  Location Price: $75 (location's cost)
  Sale Price: $100 (customer pays)

Margins:
  Location Margin: $25 ($75 - $50)
  Your Revenue: $50 ($100 - $50) or Location Revenue: $25 ($100 - $75)

Revenue Reports ​

Filter package sales by date range and location to calculate:

  • Total sales revenue
  • Revenue by package type
  • Revenue by location
  • Average sale price
  • Total active vs expired packages

Export for Analysis

Use the export function to download package sales data for external analysis in Excel or accounting software.

Understanding Validity & Expiration ​

Validity Calculation ​

When a package sale is created, valid_till is calculated based on the OperatorPackage's validity settings:

Time-Based Packages:

Created: 2024-12-01 10:00 AM
Package Validity: 30 Days
Valid Until: 2024-12-31 10:00 AM

Usage-Based Packages:

Created: 2024-12-01
Data Limit: 5 GB
Valid Until: When 5 GB consumed OR time limit reached

Expiration Behavior ​

What Happens When Package Expires:

  1. Status automatically changes to "Expired"
  2. Subscriber loses network access
  3. Subscriber sees "Package Expired" message on login portal
  4. Package sale record preserved for history

Auto-Renewal: If free package auto-renewal is enabled in Settings, subscribers automatically receive a new free package after expiry.

No Automatic Paid Renewal

Paid packages do NOT auto-renew. Subscribers must purchase/activate a new package through vouchers or admin renewal.

Best Practices ​

Track all sales - Every package assignment should create a PackageSale record for accurate reporting.

Use consistent pricing - Set sale price to match package's price_to_subscriber for consistency.

Don't modify active packages - Avoid changing bandwidth/data limits mid-package unless absolutely necessary.

Extend instead of renew - For customer service, extend valid_till rather than creating new sale.

Use status wisely:

  • Active = Normal operation
  • Inactive = Temporary suspension (can reactivate)
  • Expired = Natural end (use renewal for new package)

Document modifications - Keep notes on why package sales were manually edited.

Review expired sales - Regularly check expired sales to identify renewal opportunities.

Monitor days remaining - Proactively reach out to customers with packages expiring soon.

Voucher for self-service - Use vouchers for customer self-service purchases to reduce admin workload.

Common Workflows ​

Hotel Guest Workflow ​

Check-in:

  1. Front desk creates subscriber account
  2. Assigns 24-hour free package (Trial)
  3. PackageSale created automatically
  4. Guest receives login credentials

Extended Stay:

  1. Guest extends stay
  2. Front desk clicks Renew on subscriber
  3. Assigns another 24-hour package
  4. New PackageSale created with fresh validity

Cafe Workflow ​

First Visit:

  1. Customer signs up on WiFi portal
  2. Auto-assigned 1-hour free package
  3. PackageSale created with 1-hour validity

Next Day:

  1. Customer returns and connects
  2. Free package auto-renewed (if enabled)
  3. New PackageSale created with fresh 1-hour validity

Reseller Workflow ​

Voucher Distribution:

  1. Operator creates voucher series for Premium package
  2. Vouchers distributed to reseller/location
  3. Reseller sells vouchers to customers
  4. Customer activates voucher code
  5. PackageSale created automatically
  6. System tracks sale to that location

Troubleshooting ​

Package sale not appearing ​

Cause: Sale wasn't created properly during subscriber creation or renewal.

Fix:

  1. Check subscriber's current package status
  2. If missing, use Renew function to assign package
  3. Verify PackageSale appears in list

Subscriber has access but no package sale ​

Cause: Data inconsistency or manual database changes.

Fix:

  1. Check subscriber's current_package_sale_id
  2. Use Renew to create proper package sale
  3. Contact support if issue persists

Package expired but subscriber still has access ​

Cause: Caching or status not updated.

Fix:

  1. Manually set status to Inactive
  2. Wait 1-2 minutes for cache to clear
  3. Verify subscriber cannot authenticate

Cannot edit package sale ​

Cause: Permissions or package is in protected state.

Fix:

  1. Verify you have admin/operator permissions
  2. Check if package sale exists and is not deleted
  3. Try refreshing the page

Sale price doesn't match package price ​

Cause: Sale price is independent from package template price.

Fix:

  • Sale price is set at time of creation from price_to_subscriber
  • Changes to package template don't affect existing sales
  • Manually update sale price if needed for record-keeping

Days remaining showing negative number ​

Cause: Package has expired but status hasn't updated.

Fix:

  • Negative number = days overdue
  • Status should automatically change to Expired
  • Manual renewal required for continued access

Integration with Other Features ​

Subscribers ​

  • Each subscriber has one current_package_sale
  • Subscriber status derived from package sale status
  • Renewal creates new package sale

Packages ​

  • OperatorPackage is the template
  • PackageSale is the instance sold to subscriber
  • Changes to OperatorPackage don't affect existing sales

Vouchers ​

  • Voucher activation creates PackageSale
  • Voucher tracks which package it includes
  • PackageSale tracks the actual assignment

Locations ​

  • PackageSale records which location sold the package
  • Revenue reporting by location
  • Location-specific pricing supported

Settings ​

  • Free package auto-renewal creates new PackageSales
  • Currency setting affects price display
  • SMS notifications sent on package events

API Reference ​

For developers integrating with the package sales API:

Endpoints:

  • GET /api/v1/package_sales - List sales with filters
  • GET /api/v1/package_sales/:id - Get sale details
  • PATCH /api/v1/package_sales/:id - Update sale
  • PATCH /api/v1/subscribers/:id/renew - Renew subscriber

Query Parameters:

  • status - Filter by active/inactive/expired
  • subscriber_id - Filter by subscriber
  • location_id - Filter by location
  • start_date - Sales created after date
  • end_date - Sales created before date
  • page - Page number (default: 1)
  • per_page - Results per page (default: 25)

Next Steps ​

Start Selling

After understanding package sales:

  1. Create your packages in Packages
  2. Add subscribers in Subscribers
  3. Use Renew to assign packages
  4. Monitor sales in Package Sales dashboard
  5. Generate vouchers for self-service in Vouchers

See also:

Released under the MIT License

Copyright � 2023-2026 XceedNet