Unified Addons System -- User Guide

A plain-language guide for operations staff, administrators, and managers.

---

What Are Addons?

Addons are extra charges, discounts, or taxes that get added on top of a shipment’s base freight rate. Think of them as line items that adjust the final price a customer pays.

Common examples:

• Fuel Levy — a percentage added to cover fuel costs
• Tailgate Fee — a flat charge when a tailgate lift is needed at pickup or delivery
• GST — the 10% goods and services tax
• Residential Delivery Fee — extra charge for delivering to a home address
• Volume Discount — a reduction for high-volume customers

Before this system, these charges were managed in different places with different rules. The Unified Addons System brings them all into one place so they are easier to set up, maintain, and understand.

---

Where to Find Addons

From the Operations Portal sidebar, navigate to:

Rates > Addons

This opens the Addons management page where you can view, create, edit, and delete addons.

You will also see addons applied in two other places:

• Create Booking page — addons are calculated and shown as line items when you create a new booking
• Rate Card Details page — the Surcharges tab shows which addons are linked to that rate card

---

Types of Addons

Every addon falls into one of four categories:

Type	What It Does
Surcharge	Adds an extra charge on top of the base rate (e.g. Fuel Levy, Tailgate Fee)
Discount	Reduces the price (e.g. Loyalty Discount, Volume Discount)
Tax	Calculates tax on the total (e.g. GST at 10%). Tax addons are always applied last
Document Addition	Requires a document or special information (e.g. Dangerous Goods Declaration)

---

How Addon Values Are Calculated

Each addon uses one of these methods to work out its value:

Fixed Amount

A set dollar amount regardless of the shipment details.

Example: Tailgate Fee = $20.00 flat

Percentage

A percentage of a base amount (such as the freight rate or running subtotal).

Example: Fuel Levy = 20% of the subtotal

Per Unit

A rate multiplied by a quantity from the shipment.

Example: $1.50 per kilometre, or $5.00 per pallet

Available unit types: pallets, kilograms, kilometres, cubic metres, or items.

External / Dynamic Pricing

The system calls an outside service to get a live price. This is used for things like toll calculations or insurance quotes where the cost depends on the specific route or cargo.

Example: Toll fees fetched based on the actual route

Text Input

No calculation — just a text field for notes or special instructions.

Example: “Handle with care” notation on the shipment

---

Trigger Modes — When Addons Are Applied

Each addon has a trigger mode that controls when it kicks in during a booking:

Mandatory

The addon is always applied to every booking. The user cannot remove it.

Example: Fuel Levy — every shipment includes it automatically.

Automatic

The addon is applied when the user clicks a specific button on the booking form. It turns on and off with that button.

Example: When you click the “Tailgate” button under Pickup handling options, the Tailgate Pickup fee is automatically added. Click it again to remove it.

Manual

The addon appears in a list that the user can choose from. The user opens the “Add Surcharge / Addon” panel and ticks the ones they want.

Example: Insurance or Premium Packaging — the operator decides whether to include them.

---

How Prices Are Built Up (The Waterfall)

When a booking is created, the system calculates the final price by processing addons in a specific order, like water flowing down steps:

1. Start with the base freight rate (e.g. $800) plus any flat rate (e.g. $50 pickup fee) = Subtotal: $850

2. Apply non-tax addons in order:

   • Handling charges first (e.g. Tailgate Fee: +$20)
   • General charges next (e.g. Fuel Levy 20%: +$170)
   • Service and custom charges after that (e.g. Insurance: +$45)

3. Apply tax addons last:

   • GST is calculated only on the taxable portion (e.g. 10% of $1,040 = $104)

4. Final total: $1,189.00

The order matters because percentage-based addons use the running total from previous steps. This is why Fuel Levy (which is a percentage) comes after flat fees like Tailgate.

What Happens with Non-Taxable Items?

Some addons are marked as tax-exempt (e.g. certain types of insurance). These are still added to the final price, but GST is not calculated on them.

---

Price Overrides — Customer and Rate Card Specific Values

An addon can have different values for different customers or rate cards without creating duplicate addons:

• Customer override: A specific customer might have a negotiated Fuel Levy of 18% instead of the standard 20%
• Rate card override: A particular rate card might set the Tailgate Fee at $25 instead of the standard $20

The system checks for overrides in this priority:

1. Customer-specific value (highest priority)
2. Rate card-specific value
3. Default value (if no overrides exist)

---

Conditions — When Addons Should Appear

You can set rules so that an addon only appears under certain circumstances:

• Job type: Only show for Full Truck Load (FTL) jobs
• Service level: Only show for Express deliveries
• Weight: Only apply if the shipment weighs more than 500 kg
• Distance: Only apply if the delivery is more than 100 km away
• Customer group: Only apply for VIP customers

Multiple conditions use AND logic — all conditions must be met for the addon to appear.

---

Assigning Addons to Customers and Rate Cards

By default, a new addon applies to all customers and all rate cards. You can restrict this:

Restricting to Specific Customers

1. Open the addon and go to Customer Assignments
2. Uncheck “Apply to all customers”
3. Select the specific customers who should see this addon
4. Optionally set an override value for each customer

Restricting to Specific Rate Cards

1. Open the addon and go to Rate Card Assignments
2. Uncheck “Apply to all rate cards”
3. Select the specific rate cards that should include this addon
4. Optionally set an override value for each rate card

---

Form Targets — Where Addons Appear

Each addon can be set to appear on one or more forms across the system. Form targets are organised by context:

Booking Form Targets

Target	Where It Shows Up
booking	The Create Booking page (system addons: Fuel Levy, GST)
create_booking_pickup	Pickup section handling options on the booking page
create_booking_delivery	Delivery section handling options on the booking page

Admin Quotation Targets

Target	Where It Shows Up
quotation_widget_admin	Internal admin quotation forms
admin_quotation_pickup	Pickup handling options in admin quote form
admin_quotation_delivery	Delivery handling options in admin quote form

Public Quotation Widget Targets (Stencil.js)

Target	Widget Section	What Goes Here
widget_subtotal	Price breakdown (computed, no UI toggles)	Fuel Levy (% of subtotal), GST (% of grand total)
quotation_widget_pickup	Pickup row checkboxes	Residential Pickup, Tail Lift Required
quotation_widget_delivery	Delivery row checkboxes	Residential Delivery, Tail Lift Required
quotation_widget_services	”Additional Services” panel	DG, Manual Handling, Time Slot, Hand Unload

Other Targets

Target	Where It Shows Up
rate_card	The Rate Card Details page (Surcharges tab)
customer_quotation	Customer portal quotation request form
invoice	Invoice generation

A single addon (like Fuel Levy) can be assigned to multiple form targets so it appears in bookings, quotes, the public widget, and invoices.

---

Tax Handling

Tax Categories

Every addon is assigned a tax category that determines whether GST (or the relevant regional tax) is calculated on it:

Category	What It Means	GST Charged?
Standard	Normal taxable item	Yes
GST-Free	Exempt from GST	No
Zero-Rated	Zero-rated supply (e.g. exports)	No
Input Taxed	Special financial items	No

Tax-Inclusive Pricing

If a tax addon is marked as “tax inclusive”, it means the tax is already built into the displayed prices. The tax amount is shown for information but does not increase the total.

Regional Tax

The system is configured for a specific country/region. This means:

• An Australian deployment uses GST at 10%
• A Dubai deployment uses VAT at 5%
• A Philippines deployment uses VAT at 12%

Addons tagged for a different region are automatically hidden. For example, a Dubai VAT addon will never appear on an Australian deployment.

---

Min/Max Guardrails

For per-unit addons (charged by the kilogram, kilometre, etc.), you can set safety limits:

• Minimum charge: The addon will never be less than this amount, even if the per-unit calculation gives a lower number
• Maximum charge: The addon will never exceed this amount, even if the per-unit calculation gives a higher number

Example: A per-km surcharge of $1.50/km with a minimum of $10 and a maximum of $500. A 3 km trip would charge $10 (not $4.50), and a 1,000 km trip would charge $500 (not $1,500).

---

Calculation Order

Addons are processed in a set sequence. Each addon has an order number that determines when it runs:

Range	Category	Examples
1 — 49	System (runs first)	Base adjustments
50 — 99	Handling	Tailgate, Residential
100 — 199	General	Fuel Levy, Distance surcharge
200 — 499	Service Level	Express premium
500 — 899	Custom	Any user-defined addons
900+	Tax (always last)	GST, VAT

This ordering ensures that percentage-based charges are calculated on the correct base amounts and that tax is always the final calculation.

---

Visibility

Each addon has a “Client Visible” setting:

• Visible: The addon name and amount will appear on customer-facing documents (invoices, quotes, booking confirmations)
• Hidden: The addon is applied to the price but its details are not shown to the customer — they only see the final total

---

Creating a New Addon — Step by Step

1. Go to Rates > Addons in the Operations Portal sidebar
2. Click Create New Addon
3. Fill in the basic details:
   • Name: Internal reference name (e.g. “fuel_levy”)
   • Label: Display name the user sees (e.g. “Fuel Levy”)
   • Description: A note explaining what this addon is for
4. Choose the Addon Type: Surcharge, Discount, Tax, or Document Addition
5. Choose the Value Type: Fixed Amount, Percentage, Per Unit, or External
6. Set the Default Value: The amount or percentage
7. Choose the Trigger Mode: Mandatory, Automatic, or Manual
8. Select which Forms this addon should appear on (Booking, Rate Card, Invoice, etc.)
9. Set the Tax Category: Standard (taxable) or GST-Free
10. Set the Region: Choose the applicable region or leave as Global for all regions
11. Click Save

Optional Steps After Creating

• Add Conditions: Set rules for when the addon should appear (e.g. only for shipments over 500 kg)
• Assign Customers: Restrict to specific customers or set customer-specific values
• Assign Rate Cards: Restrict to specific rate cards or set rate-card-specific values

---

Editing and Managing Addons

Editing an Addon

Click the edit button on any addon card to open the edit form. Make your changes and save.

Activating / Deactivating

Use the toggle switch on the addon card to turn an addon on or off. Deactivated addons are not applied to any bookings or quotes.

Deleting an Addon

Click the delete button on the addon card. This permanently removes the addon and all its conditions and assignments. Use with caution — consider deactivating instead if you might need it again.

---

How Addons Look on a Booking

When creating a booking, the price breakdown panel shows:

Base Rate                          $800.00
Flat Rate (Pickup)                  $50.00
                                 ---------
Subtotal                           $850.00

Tailgate Fee                        $20.00
Fuel Levy (20%)                    $170.00
Insurance                           $45.00
                                 ---------
Taxable Subtotal                 $1,040.00

GST (10%)                          $104.00
                                 ---------
Estimated Total (inc. tax)       $1,189.00

Mandatory addons appear automatically. Automatic addons appear when you click the relevant handling button. Manual addons can be added by clicking “Add Surcharge / Addon” and selecting from the list.

---

Frequently Asked Questions

Can I have different fuel levy rates for different customers?

Yes. Create one Fuel Levy addon with a default value (e.g. 20%), then assign specific customers with override values (e.g. Customer ABC gets 18%).

Why doesn’t my addon show up on a booking?

Check the following:

• Is the addon active (not deactivated)?
• Is the addon assigned to the Booking form target?
• Is the addon assigned to this customer (or set to “all customers”)?
• Is the addon assigned to this rate card (or set to “all rate cards”)?
• Does the addon have conditions that this booking doesn’t meet?
• Is the addon set to the correct region?

Can an addon apply to both bookings and invoices?

Yes. When creating or editing an addon, you can select multiple form targets. The addon will appear on all selected forms.

What is the difference between “applies on base rate” and “applies on subtotal”?

• Base rate: The percentage is calculated only on the original freight rate
• Subtotal: The percentage is calculated on the freight rate plus any flat fees
• Running total: The percentage is calculated on everything that has been added so far (including previous addons)

Can I set a Fuel Levy that is mandatory for everyone but with different rates per customer?

Yes. Set the Fuel Levy addon as Mandatory with a default value. Then use customer assignments to set override values for specific customers.

What happens if an external pricing service is unavailable?

The system waits up to 2 seconds for a response. If the service does not respond in time or returns an error, the addon falls back to its fallback value (a fixed amount you set when creating the addon).

Can I change the order that addons are calculated?

Yes. Each addon has a calculation order number. Lower numbers run first, higher numbers run later. Tax addons should always be 900 or above to ensure they run last.

---

Fuel Levy — How It Works

Fuel levy is the most important surcharge in freight operations. It compensates for fluctuating diesel prices and is applied to every shipment by default.

Current Setup

Fuel levy is configured as a mandatory surcharge addon:

• Type: Percentage
• Default Rate: 20% (adjustable — the current rate may be 22.5%)
• Applied On: Subtotal (base rate + any flat charges)
• Trigger: Mandatory — always included, cannot be removed
• Taxable: Yes — GST is calculated on top of the fuel levy amount

Where Fuel Levy Appears

Location	How It’s Shown
Admin Quote Form (Create Quote page)	Separate “Fuel:” line on each pricing card
Create Booking page	Line item in the surcharges list
Customer Quote Widget	Included in the total (visible if client_visible = true)
Connote	Stored as fuel_levy_percentage and fuel_levy_amount
Invoice	Separate line item
Quote PDF	”Fuel Surcharge: $XX.XX”

Changing the Fuel Levy Rate

1. Go to Rates > Addons in the Operations Portal
2. Find the Fuel Surcharge addon
3. Click Edit
4. Change the Default Value to the new percentage (e.g. 22.5 for 22.5%)
5. Click Save

The new rate takes effect immediately for all new quotes and bookings.

Per-Customer Fuel Levy

To give a specific customer a different fuel levy rate:

1. Edit the Fuel Surcharge addon
2. Go to Customer Assignments
3. Add the customer
4. Set their override value (e.g. 18 for 18%)

That customer will see 18% fuel levy instead of the standard rate.

Quote Templates and Fuel Levy

When saving a quote as a template, the fuel levy amount is preserved. When the template is loaded later:

• Dynamic rate mode: Fuel levy is recalculated at the current rate
• Fixed rate mode: The original fuel levy amount from the template is used (displayed with a lock icon)

---

GST — Default Tax Configuration

Default GST Settings

GST (Goods and Services Tax) is set to 10% by default for Australian deployments. This is:

• Applied automatically to every quote and booking (mandatory)
• Calculated on the total of base rate + all taxable surcharges (including fuel levy)
• Added on top of the subtotal (tax-exclusive by default)

How GST Is Calculated

Example:
  Base Rate:                    $500.00
  + Fuel Levy (20%):            $100.00  (taxable)
  + Tailgate Delivery:           $25.00  (taxable)
  ──────────────────────────────────────
  Taxable Subtotal:             $625.00

  GST (10% of $625.00):         $62.50
  ──────────────────────────────────────
  Grand Total:                  $687.50

GST applies to the fuel levy and surcharges because they are tagged as Standard tax category. If a surcharge is tagged as GST-Free, it is excluded from the GST calculation.

GST on the Quote Form

When creating a quote in the Operations Portal, GST appears as the last line in every pricing card:

  Base:       $500.00
  Fuel:       $100.00
  Surcharges:  $25.00
  GST:         $62.50
  Total:      $687.50

Changing the GST Rate

The GST rate is controlled at two levels:

1. Tenant Settings (Global):

• Navigate to Admin > Tenant Settings > Tax Configuration
• Change Tax Rate (e.g. 0.10 = 10%)
• Change Tax Name if needed (e.g. “VAT” for other regions)

2. GST Addon (Waterfall Engine):

• Navigate to Rates > Addons
• Edit the GST addon
• Change the Default Value (e.g. 10 for 10%)

Both should be kept in sync.

Tax-Inclusive Pricing

If your business shows prices with tax already included:

1. Edit the GST addon
2. Set Tax Inclusive to Yes
3. The GST amount will still be shown on documents for compliance, but it won’t be added to the total

---

Where Addons Appear on the Admin Quote Form

The admin quote form (Operations Portal > Quotes > Create Quote) shows addon results differently from the booking page:

Pricing Cards

Instead of line-item management, the quote form shows addons as part of the pricing comparison cards. Each service level (Express, Standard, Economy) gets its own card showing the full breakdown:

• Base: The initial cost from rate calculation
• Items: Per-item charges (if applicable)
• Flat: Any flat rate charges
• Min: Minimum charge (if applied)
• Fuel: Fuel levy amount (identified by the word “fuel” in the addon name)
• Surcharges: All other non-tax, non-fuel addon amounts combined
• GST: All tax addon amounts combined

How the System Determines What to Show

The backend runs the addon waterfall engine for three form targets and merges the results:

1. Booking — System addons: Fuel Levy, GST, DG Surcharge
2. admin_quotation_pickup — Pickup handling: Tailgate Pickup, Residential Pickup
3. admin_quotation_delivery — Delivery handling: Tailgate Delivery, Residential Delivery

All unique addons from these three targets appear in the pricing cards.

Handling Options on the Quote Form

If handling option buttons are available (tailgate, residential, etc.), clicking them sets ui_context flags that trigger automatic addons. The prices update in real-time.

---

Where Addons Appear on the Public Quotation Widget

The public quotation widget (embedded on customer-facing websites like Jatt Logistics) uses four separate form targets to organise addons by widget section:

Widget Layout

┌──────────────────────────────────────────────────┐
│  Freight Quotation Tool                          │
│                                                  │
│  Weight: [____] kg                               │
│                                                  │
│  Pickup:                                         │
│    ☐ Residential Pickup    ☐ Tail Lift Required  │  ← quotation_widget_pickup
│                                                  │
│  Delivery:                                       │
│    ☐ Residential Delivery  ☐ Tail Lift Required  │  ← quotation_widget_delivery
│                                                  │
│  FREIGHT ITEMS                                   │
│  [Packaging] [L] [W] [H] [Wt]                   │
│                                                  │
│  ADDITIONAL SERVICES              [+ ADD MORE]   │  ← quotation_widget_services
│    ☐ Dangerous Goods  ☐ Manual Handling  ...     │
│                                                  │
│  ─────────────────────────────────────────────── │
│  Subtotal:    $300.00                            │
│  Fuel Levy:    $67.50                            │  ← widget_subtotal (mandatory)
│  GST:          $36.75                            │  ← widget_subtotal (mandatory)
│  Total:       $404.25                            │
└──────────────────────────────────────────────────┘

Which form target does what?

Form Target	Section	Addons	Behaviour
widget_subtotal	Price breakdown only	Fuel Levy, GST	Always calculated, no UI toggles
quotation_widget_pickup	Pickup row	Residential Pickup, Tailgate Pickup	Checkboxes in the pickup section
quotation_widget_delivery	Delivery row	Residential Delivery, Tailgate Delivery	Checkboxes in the delivery section
quotation_widget_services	Additional Services	DG, Manual Handling, Time Slot, etc.	User picks from a list

How to add a new addon to the widget

1. Go to Rates > Addons
2. Create or edit the addon
3. Under Form Targets, select the appropriate widget target:
   • For pricing surcharges that always apply: select widget_subtotal
   • For pickup options: select quotation_widget_pickup
   • For delivery options: select quotation_widget_delivery
   • For optional extra services: select quotation_widget_services
4. Save

Fuel Levy and GST on the Widget

Fuel Levy and GST are assigned to widget_subtotal:

• Fuel Levy is calculated as a percentage of the subtotal (base rate)
• GST is calculated as a percentage of the grand total (subtotal + fuel + all taxable surcharges)
• Both are mandatory — the customer cannot remove them
• Both appear in the price breakdown, not as checkboxes

---

Setting Up Addons from the Portal — Step by Step

Adding a New Surcharge

1. Go to Rates > Addons in the Operations Portal sidebar
2. Click Create New Addon
3. Fill in:
   • Name: e.g. “After Hours Delivery”
   • Label: e.g. “After Hours”
   • Type: Surcharge
   • Value Type: Fixed Amount
   • Default Value: e.g. 65.00
   • Trigger Mode: Manual (operator chooses when to apply)
4. Under Form Targets, select where it should appear:
   • Check Booking (for the booking page)
   • Check admin_quotation_delivery (for the delivery section of quotes)
   • Check Invoice (if it should appear on invoices)
5. Set Tax Category: Standard (so GST applies to it)
6. Set Region: Australia (or Global)
7. Click Save

Setting Up a Percentage-Based Surcharge

1. Create new addon as above
2. Set Value Type: Percentage
3. Set Default Value: e.g. 15 (for 15%)
4. Set Applies On:
   • Base Rate — percentage of the original freight rate only
   • Subtotal — percentage of freight rate + flat charges
   • Running Total — percentage of everything calculated so far (including previous addons)
5. Set Calculation Order to control when it runs in the waterfall

Setting Up a Per-Unit Surcharge

1. Create new addon as above
2. Set Value Type: Per Unit
3. Set Application Scope: Per Unit
4. Set Unit Type: kg, km, pallet, cubic_meter, or item
5. Set Default Value: e.g. 0.50 (per unit)
6. Optionally set Minimum Charge and Maximum Charge guardrails

Restricting an Addon to Specific Customers

1. Edit the addon
2. Uncheck Apply to All Customers
3. Go to Customer Assignments
4. Select the customers who should see this addon
5. Optionally set per-customer override values

Setting Up Conditions

1. Edit the addon
2. Go to Conditions
3. Add a condition:
   • Type: e.g. “Weight Range”
   • Operator: e.g. “Greater Than”
   • Value: e.g. 500
4. The addon will only appear when the shipment weight exceeds 500 kg

---

Troubleshooting

Addon not appearing in calculation

1. Is the addon active (not deactivated)?
2. Is the addon assigned to the correct form target (e.g. widget_subtotal for the public widget, booking for bookings)?
3. Does the addon’s region match the deployment? (AU for Australian deployments)
4. For automatic addons: is the ui_binding value correct and does the form send the matching ui_context key?
5. For manual addons: is the addon ID included in selected_addon_ids?
6. Does the addon have conditions that this shipment doesn’t meet?

GST not calculating

1. Is the GST addon’s type set to Tax (not Surcharge)?
2. Is the calculation order 900 or above?
3. Is applies on set to Running Total?
4. Is tax inclusive set to No? (If Yes, the amount shows but doesn’t add to the total)
5. Is the addon assigned to the correct form target?

Fuel levy showing wrong amount

1. Check the default value on the Fuel Surcharge addon
2. Check for a customer override (the customer may have a negotiated rate)
3. Check for a rate card override
4. Is applies on set correctly? (subtotal = base rate + flat charges)
5. Is the calculation order correct? (should be low, e.g. 10)

Customer override not applying

1. Is is_enabled set to Yes on the customer assignment?
2. Is the override value set and numeric?
3. Is “Apply to All Customers” set to No on the addon? (if Yes, overrides are ignored)
4. Does the customer ID match?

Addon not showing on the public widget

1. Is the addon assigned to one of the widget form targets? (widget_subtotal, quotation_widget_pickup, quotation_widget_delivery, or quotation_widget_services)
2. Is the addon active?
3. Does the addon’s region match the deployment?
4. For the public widget, has a public API route been created? (The default endpoints require login)