Skip to content

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

  1. How Tax/Extra Fee Works
  2. Fee Group Structure
  3. Four Value Types
  4. Choosing the Right Type
  5. Step-by-Step Guide
  6. All Fields Explained
  7. Best Practices
  8. Common Examples
  9. 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:      1725

Fee 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)  | 15

Four 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:     1725

Example — 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.50

Use Cases:

✅ Single VAT / GST on a package
✅ Tax + surcharge (surcharge on subtotal)
✅ Any scenario where taxes stack on each other

Type 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:     2000

Example — 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:     2100

Use Cases:

✅ Installation charges (one-time)
✅ Equipment rental (monthly)
✅ Connection fees (one-time)
✅ Service charges (monthly)
✅ Maintenance fees

Type 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 results

Example — 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.50

Example — 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:     1760

Use Cases:

✅ Tax-on-tax regulatory requirements
✅ Multi-step cascading calculations
✅ Mixed flat + percentage chains
✅ Complex government-mandated tax structures

EQUATION 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.


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:     1875

Example — 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:     1755

Use 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 price

WHICH 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:

ScenarioType to Use
Single VAT/GST on package priceType 1 or Type 4 (same result)
Two or more taxes — all on same base priceType 4
Tax + surcharge — surcharge is on subtotalType 1
True tax-on-tax chain (each step on previous result)Type 3
Fixed installation or rental feeType 2
Fixed fee + percentage on base priceType 2 + Type 4
No tax on a packageDon't assign a fee group

Step-by-Step Guide

Step 1: Access Tax/Extra Fee

Navigate to Tax/Extra Fee:

  1. Go to Package menu
  2. Click Tax/Extra Fee
  3. 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 Tax

Item 2 — Service Tax

Name:        Service Tax
Type:        Percentage (Base Price)
Value:       15
Description: 15% Service Tax

Result on a 1500 package:

GST (10%):          150   ← 1500 × 10%
Service Tax (15%):  225   ← 1500 × 15%
Total Extra Fee:    375
Grand Total:       1875

Step 4: Save Fee Group

Click "Submit"

✅ Successfully Added.

Step 5: Assign to Package

Go to Package → Add/Edit Package:

  1. Find Extra Fee Group field
  2. Select your fee group from the dropdown
  3. Save the package

Now all subscribers on this package will have these fees on every invoice.


Step 6: Add More Items to Existing Group

  1. Go to Tax/Extra Fee page
  2. Find your group in the table
  3. Click Add New for that group
  4. Add new fee item and submit

Step 7: Edit or Delete Fee Item

Edit:

  1. Click Edit action next to the item
  2. Modify Name, Type, Value, or Description
  3. Submit

Delete:

  1. Click Delete action next to the item
  2. 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., 10 for 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 chains

3. Check Regulations

✅ Government tax rates (VAT, GST, sales tax)
✅ Regulatory requirements
✅ Whether multiple taxes apply on the same base or cascade

During 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 deploying

After Fee Creation

1. Test with Packages

✅ Assign fee group to a test package
✅ Generate a test invoice
✅ Verify the calculations match expectations
✅ Check invoice display

2. Assign to Packages

✅ Residential packages  → Standard fees
✅ Corporate packages    → Corporate fees
✅ Special packages      → Custom fees
✅ Tax-exempt packages   → No fee group assigned

Common 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 first

Common 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 Tax

Calculation on a 1500 package:

Package Price:  1500
VAT (15%):       225   ← 1500 × 15%
─────────────────────
Total Extra:     225
Grand Total:    1725

Example 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 Tax

Calculation on a 1500 package:

Package Price:    1500
GST (10%):         150   ← 1500 × 10%
Service Tax (15%): 225   ← 1500 × 15%
─────────────────────────
Total Extra:       375
Grand Total:      1875

Example 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: 2

Calculation 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:        1755

Example 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 fee

Calculation on a 1500 package:

Package Price:       1500
Installation (flat):  500
Router Rental (flat): 100
─────────────────────────
Total Extra:          600
Grand Total:         2100

Example 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: 15

Calculation 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:          2400

TIP

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 tax

Calculation 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.5

Example 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: 5

Calculation 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:              7250

Troubleshooting

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 package

Cause 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 percentages

Issue 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%"}      ← mixed

Issue 4: Fee Item Not Saving

Cause: Missing Required Fields

All four fields are required:
  ✅ Name
  ✅ Type
  ✅ Value
  ✅ Description

Issue 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 group

Summary

Tax/Extra Fee — Four Types, Every Scenario Covered

TypeNameBest For
1Percentage (Compound)Single tax · Tax + surcharge (stacked)
2Flat-RateInstallation · Rental · Fixed charges
3EquationCascading tax chain · Tax-on-tax
4Percentage (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 empty

Configuration 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

www.onezeroart.com