Appearance
Tax/Extra Fee
Overview
Tax/Extra Fee allows you to add additional charges to package invoices. This includes government taxes (VAT, sales tax), installation fees, equipment rental, regulatory fees, and any other charges. Extra fees are organized into groups and can be assigned to packages, automatically calculating charges on subscriber invoices.
WHAT IS TAX/EXTRA FEE?
Tax/Extra Fee is a flexible billing component that:
- Groups multiple fees - Organize related fees (e.g., "Installation Package", "Monthly Charges")
- Four calculation types - Percentage (Compound), Percentage (Base Price), Flat-Rate, or Equation
- Assigned to packages - Link fee groups to packages
- Auto-calculated - Fees automatically added to invoices
- Supports complex billing - One-time fees, recurring fees, single tax, multi-tax, cascading tax
Perfect for VAT, GST, installation charges, equipment rental, and regulatory fees!
📋 Table of Contents
- How Tax/Extra Fee Works
- Fee Group Structure
- Four Value Types
- Choosing the Right Type
- Step-by-Step Guide
- All Fields Explained
- Best Practices
- Common Examples
- Troubleshooting
How Tax/Extra Fee Works
The Group-Based System
Tax/Extra Fee uses a group-based structure:
Fee Group: "Standard-Tax"
├─ GST (Percentage Base Price: 10%)
└─ Service Tax (Percentage Base Price: 5%)
Fee Group: "Installation Package"
├─ Installation Fee (Flat-Rate: 500)
├─ Router Rental (Flat-Rate: 100)
└─ VAT (Percentage Compound: 15%)
Fee Group: "Monthly Charges"
├─ Service Charge (Flat-Rate: 50)
└─ VAT (Percentage Compound: 15%)Each group contains one or more fee items.
Groups are assigned to packages.
Fees are automatically calculated on every invoice.
Workflow
1. Create Fee Group
Group Name: "Standard-Tax"2. Add Fee Items to Group
Item 1: GST (Percentage Base Price: 10%)
Item 2: Service Tax (Percentage Base Price: 5%)3. Assign Group to Package
Package: "10 Mbps Home - Monthly"
Extra Fee Group: "Standard-Tax"4. Auto-Calculation on Invoice
Package Price: 1500
GST (10%): 150 ← 1500 × 10%
Service Tax (5%): 75 ← 1500 × 5%
─────────────────────
Total Extra Fee: 225
Grand Total: 1725Fee Group Structure
What is a Fee Group?
A Fee Group is a collection of related fees:
- Groups organize fees logically
- One group can have multiple fee items
- Groups are assigned to packages
- Each fee item has: Name, Type, Value, Description
Group Components
Group Name:
- Identifies the fee group
- Example: "Standard-Tax", "Installation Package"
- Auto-formatted (spaces removed, lowercase)
Fee Items (Multiple per group):
- Each item has a unique Value ID (1, 2, 3...)
- Items processed in Value ID order
- Can add/edit/delete individual items
Example Group Structure
Group: "Standard-Fees"
Value ID | Name | Type | Value
---------|-------------------|------------------------|-------
1 | Installation | Flat-Rate | 500
2 | Router Rental | Flat-Rate | 100
3 | VAT | Percentage (Compound) | 15Four Value Types
Type 1 — Percentage (Compound)
What It Is:
A percentage-based fee where the first item calculates on the base package price, and every subsequent item calculates on base price + first fee. Use this when you want each additional tax level to stack on top of the previous total.
How the calculation works:
Item 1 → calculates on: base package price
Item 2 → calculates on: base price + Item 1 result
Item 3 → calculates on: base price + Item 1 result (same as Item 2)
Item 4 → calculates on: base price + Item 1 result (same as Item 2)IMPORTANT
Items 2, 3, 4... all use the same base: package price + 1st item only. They do NOT cascade from one to the next.
Example — Single tax (most common):
Package Price: 1500
─────────────────────────────────────
Item 1: VAT (15%) → 1500 × 15% = 225
─────────────────────────────────────
Total Extra Fee: 225
Grand Total: 1725Example — Two compound taxes:
Package Price: 1500
─────────────────────────────────────────────────────────
Item 1: GST (10%) → 1500 × 10% = 150
Item 2: Surcharge (5%) → (1500 + 150) × 5% = 82.50
↑ base + 1st item result
─────────────────────────────────────────────────────────
Total Extra Fee: 232.50
Grand Total: 1732.50Use Cases:
✅ Single VAT / GST on a package
✅ Tax + surcharge (surcharge on subtotal)
✅ Any scenario where taxes stack on each otherType 2 — Flat Rate
What It Is:
A fixed currency amount added to the invoice regardless of package price or position.
How the calculation works:
Every flat-rate item adds its fixed value directly.
Package price has no effect on the amount.Example — Single flat fee:
Package Price: 1500
─────────────────────────────────────
Item 1: Installation (500 flat) → 500
─────────────────────────────────────
Total Extra Fee: 500
Grand Total: 2000Example — Multiple flat fees:
Package Price: 1500
─────────────────────────────────────
Item 1: Installation (500 flat) → 500
Item 2: Router Rental (100 flat) → 100
─────────────────────────────────────
Total Extra Fee: 600
Grand Total: 2100Use Cases:
✅ Installation charges (one-time)
✅ Equipment rental (monthly)
✅ Connection fees (one-time)
✅ Service charges (monthly)
✅ Maintenance feesType 3 — Equation (JSON)
What It Is:
A cascading JSON formula where each step builds on the running total from the previous step. The value is entered as a JSON object in the Value field.
JSON Format:
json
{"step_name": "percentage%", "another_step": "flat_amount"}- Use
"10%"for a percentage — calculates on the current running total - Use
"100"for a flat amount — added directly to the running total - Steps are processed in order, and each step updates the running total
How the calculation works:
Running total starts at: package price
Step 1: running total × percentage → add to running total
Step 2: new running total × percentage → add to running total
Step 3: (and so on...)
Final extra fee = sum of all individual step resultsExample — Two cascading percentages:
Package Price: 1500
Value entered: {"gst": "10%", "surcharge": "15%"}
─────────────────────────────────────────────────────────────
Step 1 (gst): 1500 × 10% = 150 → running total = 1650
Step 2 (surcharge): 1650 × 15% = 247.5 → running total = 1897.5
─────────────────────────────────────────────────────────────
Total Extra Fee: 397.50
Grand Total: 1897.50Example — Mix of percentage and flat:
Package Price: 1500
Value entered: {"service_fee": "100", "gst": "10%"}
─────────────────────────────────────────────────────────────
Step 1 (service_fee): flat 100 → running total = 1600
Step 2 (gst): 1600 × 10% = 160 → running total = 1760
─────────────────────────────────────────────────────────────
Total Extra Fee: 260
Grand Total: 1760Use Cases:
✅ Tax-on-tax regulatory requirements
✅ Multi-step cascading calculations
✅ Mixed flat + percentage chains
✅ Complex government-mandated tax structuresEQUATION TYPE IS ADVANCED
Use Percentage or Flat-Rate for most cases. Only use Equation when your tax chain truly requires each step to calculate on the result of the previous step.
Type 4 — Percentage (Base Price) ✨ Recommended for Multi-Tax
What It Is:
A percentage-based fee where every item always calculates independently on the original package base price, regardless of how many items are in the group. This is the correct type when multiple taxes are all applied to the same base price.
How the calculation works:
Every item → calculates on: original package price only
No cascading. No compounding. Each tax is truly independent.Example — Two independent taxes:
Package Price: 1500
─────────────────────────────────────────────────────────
Item 1: GST (10%) → 1500 × 10% = 150
Item 2: Service Tax (15%) → 1500 × 15% = 225
↑ always on original base price
─────────────────────────────────────────────────────────
Total Extra Fee: 375
Grand Total: 1875Example — Three independent taxes:
Package Price: 1500
─────────────────────────────────────────────────────────
Item 1: Federal Tax (10%) → 1500 × 10% = 150
Item 2: State Tax (5%) → 1500 × 5% = 75
Item 3: Municipal (2%) → 1500 × 2% = 30
─────────────────────────────────────────────────────────
Total Extra Fee: 255
Grand Total: 1755Use Cases:
✅ Multiple government taxes all applied to the same base price
✅ GST + Service Tax + Regulatory Fee (all on package price)
✅ Federal + State + Local taxes (all independent)
✅ Any scenario where every tax is calculated on the original priceWHICH PERCENTAGE TYPE TO USE?
- If you have one tax → either Type 1 or Type 4 gives the same result
- If you have multiple taxes all on the base price → use Type 4
- If you want tax on tax (each level stacks on the previous) → use Type 1 or Type 3
Choosing the Right Type
Use this table to pick the correct type for your scenario:
| Scenario | Type to Use |
|---|---|
| Single VAT/GST on package price | Type 1 or Type 4 (same result) |
| Two or more taxes — all on same base price | Type 4 ✅ |
| Tax + surcharge — surcharge is on subtotal | Type 1 |
| True tax-on-tax chain (each step on previous result) | Type 3 |
| Fixed installation or rental fee | Type 2 |
| Fixed fee + percentage on base price | Type 2 + Type 4 |
| No tax on a package | Don't assign a fee group |
Step-by-Step Guide
Step 1: Access Tax/Extra Fee
Navigate to Tax/Extra Fee:
- Go to Package menu
- Click Tax/Extra Fee
- View all existing fee groups
Permission Required:
- ✅ Admin can manage fees
- ✅ Staff can manage fees (if permission granted)
- ❌ Resellers CANNOT manage fees
Step 2: Create Fee Group
Click "Add Tax/Extra Fee" Button
1. Group Name (Required)
Purpose: Identifies the fee group
Rules:
- Will be auto-formatted (lowercase, no spaces)
- Use descriptive names
- Example: "Standard-Tax" → "standard-tax"
Good Examples:
✅ "Standard-Tax"
✅ "Installation-Package"
✅ "Monthly-Charges"
✅ "Corporate-Fees"Bad Examples:
❌ "Fee1" (not descriptive)
❌ "Test" (not professional)Step 3: Add Fee Items
You can add multiple fee items to one group using the repeater.
Fee Item Example: GST + Service Tax (both on base price)
Item 1 — GST
Name: GST
Type: Percentage (Base Price)
Value: 10
Description: 10% Goods and Services TaxItem 2 — Service Tax
Name: Service Tax
Type: Percentage (Base Price)
Value: 15
Description: 15% Service TaxResult on a 1500 package:
GST (10%): 150 ← 1500 × 10%
Service Tax (15%): 225 ← 1500 × 15%
Total Extra Fee: 375
Grand Total: 1875Step 4: Save Fee Group
Click "Submit"
✅ Successfully Added.Step 5: Assign to Package
Go to Package → Add/Edit Package:
- Find Extra Fee Group field
- Select your fee group from the dropdown
- Save the package
Now all subscribers on this package will have these fees on every invoice.
Step 6: Add More Items to Existing Group
- Go to Tax/Extra Fee page
- Find your group in the table
- Click Add New for that group
- Add new fee item and submit
Step 7: Edit or Delete Fee Item
Edit:
- Click Edit action next to the item
- Modify Name, Type, Value, or Description
- Submit
Delete:
- Click Delete action next to the item
- Confirm
WARNING
Fee changes affect all packages using this group. Changes apply to future invoices only. Existing invoices are not affected.
All Fields Explained
Group Level
1. Group Name (Required)
- What: Unique identifier for the fee group
- Format: Auto-formatted (lowercase, no spaces)
- Example: "Standard Tax" → "standardtax"
Fee Item Level
2. Value ID (Auto-generated)
- What: Sequential number for each item in the group
- Purpose: Controls the order items are processed
- Note: Auto-incremented, cannot be changed
3. Name (Required)
- What: Descriptive name for fee item
- Example: "GST", "Installation Fee", "Router Rental"
- Shown: On invoices and reports
4. Type (Required)
- 1 — Percentage (Compound): 1st item on base price; 2nd+ on base + 1st item
- 2 — Flat-Rate: Fixed currency amount, always the same
- 3 — Equation: JSON cascading formula (advanced)
- 4 — Percentage (Base Price): Every item always on the original package price
5. Value (Required)
- For Percentage (Compound or Base Price): Number (e.g.,
10for 10%) - For Flat-Rate: Currency amount (e.g.,
500) - For Equation: JSON object (e.g.,
{"gst": "10%", "surcharge": "5%"})
6. Description (Required)
- What: Explanation of the fee purpose
- Example: "10% GST on package price", "One-time installation charge"
Best Practices
Before Creating Fees
1. Plan Fee Structure
✅ List all charges (taxes, fees, rentals)
✅ Group related fees together
✅ Determine calculation type for each
✅ Check legal requirements (VAT, regulatory fees)2. Understand Your Billing
✅ One-time fees (installation, connection)
✅ Recurring fees (rental, service charge)
✅ Single percentage-based tax
✅ Multiple independent percentage taxes
✅ Cascading/compound tax chains3. Check Regulations
✅ Government tax rates (VAT, GST, sales tax)
✅ Regulatory requirements
✅ Whether multiple taxes apply on the same base or cascadeDuring Fee Creation
1. Naming Convention
✅ Use clear, descriptive names
✅ Example: "GST 10%", "Installation Fee", "Router Rental"
✅ Avoid: "Fee1", "Charge", "Extra"2. Group Organization
✅ Group by purpose: "Standard-Tax", "Installation-Package"
✅ Group by package type: "Residential-Fees", "Corporate-Fees"
✅ Keep groups logical (3-5 items per group is ideal)3. Value Type Selection
✅ Multiple independent taxes (all on base price) → Type 4
✅ Single tax or stacking taxes → Type 1
✅ Fixed charges (installation, rental) → Type 2
✅ Complex cascading formula → Type 3
✅ Test calculations before deployingAfter Fee Creation
1. Test with Packages
✅ Assign fee group to a test package
✅ Generate a test invoice
✅ Verify the calculations match expectations
✅ Check invoice display2. Assign to Packages
✅ Residential packages → Standard fees
✅ Corporate packages → Corporate fees
✅ Special packages → Custom fees
✅ Tax-exempt packages → No fee group assignedCommon Mistakes to Avoid
❌ Mistake 1: Using Type 1 for multiple independent taxes
Problem: Two Type 1 items (10% + 15%) on a 1500 package gives 150 + 247.50
instead of the expected 150 + 225
Solution: Use Type 4 (Base Price) for all items → 150 + 225 = 375 ✅❌ Mistake 2: Wrong equation format for Type 3
Problem: Entering a PHP expression like (price > 1000) ? 100 : 50
Solution: Type 3 expects a JSON object: {"step1": "10%", "step2": "5%"}❌ Mistake 3: Unclear names
Problem: "Fee1", "Charge2", "Extra"
Solution: "GST 10%", "Installation Fee", "Router Rental"❌ Mistake 4: Not testing before deploying
Problem: Fees deployed to live packages without verifying calculations
Solution: Always generate a test invoice and verify the math firstCommon Examples
Example 1 — Simple Single Tax (Most Common)
Group Name: "standard-vat"
Fee Items:
1. VAT
Type: Percentage (Base Price) or Percentage (Compound)
Value: 15
Description: 15% Value Added TaxCalculation on a 1500 package:
Package Price: 1500
VAT (15%): 225 ← 1500 × 15%
─────────────────────
Total Extra: 225
Grand Total: 1725Example 2 — Two Independent Taxes (Both on Base Price)
Use Type 4 (Percentage Base Price) for both items.
Group Name: "gst-service-tax"
Fee Items:
1. GST
Type: Percentage (Base Price)
Value: 10
Description: 10% Goods and Services Tax
2. Service Tax
Type: Percentage (Base Price)
Value: 15
Description: 15% Service TaxCalculation on a 1500 package:
Package Price: 1500
GST (10%): 150 ← 1500 × 10%
Service Tax (15%): 225 ← 1500 × 15%
─────────────────────────
Total Extra: 375
Grand Total: 1875Example 3 — Three Independent Taxes (All on Base Price)
Group Name: "multi-tax"
Fee Items:
1. Federal Tax
Type: Percentage (Base Price) | Value: 10
2. State Tax
Type: Percentage (Base Price) | Value: 5
3. Municipal Fee
Type: Percentage (Base Price) | Value: 2Calculation on a 1500 package:
Package Price: 1500
Federal Tax (10%): 150 ← 1500 × 10%
State Tax (5%): 75 ← 1500 × 5%
Municipal (2%): 30 ← 1500 × 2%
──────────────────────────
Total Extra: 255
Grand Total: 1755Example 4 — Flat Fees Only
Group Name: "installation-package"
Fee Items:
1. Installation Fee
Type: Flat-Rate | Value: 500
Description: One-time installation charge
2. Router Rental
Type: Flat-Rate | Value: 100
Description: Monthly router rental feeCalculation on a 1500 package:
Package Price: 1500
Installation (flat): 500
Router Rental (flat): 100
─────────────────────────
Total Extra: 600
Grand Total: 2100Example 5 — Flat Fees + VAT (Compound)
Group Name: "full-package-fees"
Fee Items:
1. Installation Fee
Type: Flat-Rate | Value: 500
2. Router Rental
Type: Flat-Rate | Value: 100
3. VAT
Type: Percentage (Compound) | Value: 15Calculation on a 1500 package:
Package Price: 1500
Installation (flat): 500 ← Item 1 (flat)
Router Rental (flat): 100 ← Item 2 (flat)
VAT (15%): 300 ← (1500 + 500) × 15%
↑ base + 1st item only
────────────────────────────
Total Extra: 900
Grand Total: 2400TIP
When mixing Flat-Rate and Percentage (Compound), the percentage applies to base price + first item's value — not to all flat items combined. If you want VAT calculated on the full subtotal including all flat fees, use the Equation type instead.
Example 6 — Cascading Tax Chain (Equation)
Group Name: "cascading-tax"
Fee Items:
1. Tax Chain
Type: Equation
Value: {"base_tax": "10%", "surcharge": "15%"}
Description: Cascading regulatory taxCalculation on a 1500 package:
Package Price: 1500
Step 1 (10%): 150 ← 1500 × 10%, running = 1650
Step 2 (15%): 247.5 ← 1650 × 15%, running = 1897.5
↑ calculates on previous running total
─────────────────────────────
Total Extra: 397.5
Grand Total: 1897.5Example 7 — Corporate Package with Full Fees
Group Name: "corporate-fees"
Fee Items:
1. Installation
Type: Flat-Rate | Value: 1000
2. Dedicated Support
Type: Flat-Rate | Value: 500
3. GST (on base price)
Type: Percentage (Base Price) | Value: 10
4. Service Tax (on base price)
Type: Percentage (Base Price) | Value: 5Calculation on a 5000 package:
Package Price: 5000
Installation (flat): 1000
Dedicated Support (flat): 500
GST (10%): 500 ← 5000 × 10%
Service Tax (5%): 250 ← 5000 × 5%
──────────────────────────────
Total Extra: 2250
Grand Total: 7250Troubleshooting
Issue 1: Fee Not Showing on Invoice
Cause 1: Fee Group Not Assigned to Package
Solution:
1. Go to Package → Edit Package
2. Find "Extra Fee Group" field
3. Select your fee group
4. Save packageCause 2: Invoice Already Generated
Fee changes only apply to NEW invoices.
Existing invoices are not affected.
Generate a new invoice to see updated fees.Issue 2: Wrong Fee Calculation
Cause 1: Using Type 1 instead of Type 4 for multiple taxes
Problem: Two Type 1 items (10% + 15%) on a 1500 package:
Item 1: 150 ✅
Item 2: (1500+150) × 15% = 247.50 ❌ (expected 225)
Solution: Change both items to Type 4 (Percentage - Base Price):
Item 1: 1500 × 10% = 150 ✅
Item 2: 1500 × 15% = 225 ✅Cause 2: Wrong Value for Percentage type
Problem: Entered 0.15 instead of 15 for 15% VAT
Solution: Enter 15 (the system divides by 100 automatically)
Percentage: Value = 15 (for 15%)
Flat-Rate: Value = 15 (for 15 currency units)Cause 3: Wrong equation JSON syntax
Problem: {"gst": "10", "surcharge": "15"} ← missing % signs
Treated as flat amounts, not percentages
Solution: {"gst": "10%", "surcharge": "15%"} ← add % for percentagesIssue 3: Equation Type Not Calculating Correctly
Common mistakes:
❌ Using PHP ternary: (price > 1000) ? 100 : 50
❌ Missing % sign: {"gst": "10"}
❌ Invalid JSON: {gst: 10%, surcharge: 5%} ← keys must be quoted
Correct format:
✅ {"gst": "10%", "surcharge": "5%"} ← percentages
✅ {"setup_fee": "100"} ← flat amount
✅ {"setup": "100", "gst": "10%"} ← mixedIssue 4: Fee Item Not Saving
Cause: Missing Required Fields
All four fields are required:
✅ Name
✅ Type
✅ Value
✅ DescriptionIssue 5: Cannot Delete Fee Group
Cause: Group is assigned to packages
Solution:
1. Find all packages using this group (Package list, filter by group)
2. Remove the group from those packages or assign a different group
3. Then delete the fee groupSummary
Tax/Extra Fee — Four Types, Every Scenario Covered
| Type | Name | Best For |
|---|---|---|
| 1 | Percentage (Compound) | Single tax · Tax + surcharge (stacked) |
| 2 | Flat-Rate | Installation · Rental · Fixed charges |
| 3 | Equation | Cascading tax chain · Tax-on-tax |
| 4 | Percentage (Base Price) | Multiple independent taxes on base price |
Quick Decision:
One tax on package price? → Type 1 or Type 4 (same result)
Multiple taxes all on same base price? → Type 4 ✅
Tax + surcharge (surcharge on subtotal)? → Type 1
Cascading tax-on-tax chain? → Type 3
Fixed installation / rental fee? → Type 2
No tax on a package? → Leave Extra Fee Group emptyConfiguration Checklist:
✅ Create fee group with a descriptive name
✅ Add all fee items to the group
✅ Choose the correct Type for each item (see table above)
✅ Enter accurate Values
✅ Write clear Descriptions
✅ Assign the group to the right packages
✅ Generate a test invoice and verify all calculations
✅ Update tax rates whenever regulations change