Tax System

Q: How do I add a new tax type beyond vehicle, property and bank?

Append an entry to Config.TaxTypes = { ["business"] = { rate = 0.05, account = "bank", source = "queryPlayerBusinessValue" } }. The source value is a server-side function name in editable/server.lua that returns the taxable amount per player. The scheduler and admin panel pick up the new type automatically.

Q: How do I change the collection interval (e.g. weekly instead of daily)?

Config.CollectionInterval accepts any cron-like string: "daily@03:00", "weekly:monday@10:00", or "hourly". The scheduler uses a monotonic timer so restarts do not skip or double-charge a window. Test with /taxrunnow (admin only) before changing the production interval.

Q: How do I exempt specific jobs or grade levels from tax (e.g. homeless, unemployed)?

Fill Config.ExemptJobs = { "unemployed", "homeless" } and Config.ExemptGrades = { ["police"] = 5 }. The server checks the player's job name and grade before each type of tax and skips collection for matches. Exemptions are applied per tax type by default, or globally if you set exempt = "*".

Q: How do I query a player's current tax debt from another resource?

exports.legends_tax:GetPlayerDebt(citizenId) returns a table keyed by tax type with { amount, overdueSince, nextChargeAt }. Use it to build a custom HUD widget or to hold doors closed until the player pays up. The data comes from the cached in-memory state and is refreshed every time collection runs.

Q: How do I customize what happens when a player cannot afford tax?

Edit OnTaxOverdue in editable/server.lua. The hook receives { playerId, type, amount, daysOverdue } and is called every interval while debt is outstanding. Plug in your own garage lock, bank seizure or Discord notification. The default implementation applies the overdue fee configured in Config.OverduePenalty.

This is a step-by-step installation guide, configuration preview, and full explanation of all settings for legends_tax.

⚠️

If you lack programming experience, ensure you read each step thoroughly without skipping, as all documentation is essential!

Before submitting a support ticket or following the guides in this documentation, please make sure that you are running the latest version of the resource.

What is legends_tax?

legends_tax is a comprehensive tax collection system that automatically taxes players based on their vehicles, properties, and bank balance. The system features an in-game admin panel for easy configuration, supports multiple frameworks, and includes interest on unpaid taxes, automatic payment, and detailed audit logging.

Non-technical users: This resource includes an in-game admin panel. Most configuration can be done through the UI without editing files!

Key Features

Multi-Framework Support - Compatible with QBox, QB-Core, and ESX
In-Game Admin Panel - Configure all settings without editing files
Three Tax Types:
- Vehicle Tax - Based on vehicle value and class
- Property Tax - Based on owned properties
- Bank Tax - Percentage of bank balance
Flexible Tax Intervals:
- Global interval for all taxes
- Separate intervals per tax type
- Testing mode with seconds instead of days
Unpaid Tax System:
- Interest accumulation on overdue taxes
- Configurable maximum interest cap
- Auto-pay from bank after grace period
Job-Based Discounts - Configure tax discounts per job
Tax Exemptions - Exempt specific players with permanent or time-limited exemptions
Player Interaction Mode - Choose between NPC interaction or /taxui command
Inactive Player Bypass - Automatically skip taxation for players who haven't logged in recently
Audit Logging - Track all admin actions
Discord Webhook - Log admin actions to Discord
Database Auto-Setup - Tables created automatically on first start

Permission System

The resource supports multiple permission methods:

ACE Permissions - Use FiveM's ACE system
Identifier Whitelist - Steam, Discord, License, FiveM ID
CitizenID Whitelist - For legacy support

Supported Housing Scripts

Property tax works with the following housing systems, which are automatically detected:

Housing Script	Description
NoLag Properties	Uses `properties` and `properties_owners` tables
PS-Housing	Uses `properties` table with `owner_citizenid`
QB-Houses	Classic QB housing with `player_houses` and `houselocations` tables
QS-Housing Advanced	Extended housing with rental support via `house_rents` table

No configuration is needed — the resource automatically detects which housing script is installed and adapts accordingly.

Database Tables

The system automatically creates these tables:

player_tax_data - Player tax timestamps and last seen tracking
tax_invoices - All tax invoices (pending and paid)
tax_invoices_archive - Archived paid invoices
tax_audit_logs - Admin action logs
tax_exemptions - Exempt players (with optional expiry)
tax_statistics - Aggregated statistics

Need help? Join our Discord (opens in a new tab) for support!

FAQ

How do I add a new tax type beyond vehicle, property and bank?

Append an entry to Config.TaxTypes = { ["business"] = { rate = 0.05, account = "bank", source = "queryPlayerBusinessValue" } }. The source value is a server-side function name in editable/server.lua that returns the taxable amount per player. The scheduler and admin panel pick up the new type automatically.

How do I change the collection interval (e.g. weekly instead of daily)?

Config.CollectionInterval accepts any cron-like string: "daily@03:00", "weekly:monday@10:00", or "hourly". The scheduler uses a monotonic timer so restarts do not skip or double-charge a window. Test with /taxrunnow (admin only) before changing the production interval.

How do I exempt specific jobs or grade levels from tax (e.g. homeless, unemployed)?

Fill Config.ExemptJobs = { "unemployed", "homeless" } and Config.ExemptGrades = { ["police"] = 5 }. The server checks the player's job name and grade before each type of tax and skips collection for matches. Exemptions are applied per tax type by default, or globally if you set exempt = "*".

How do I query a player's current tax debt from another resource?

exports.legends_tax:GetPlayerDebt(citizenId) returns a table keyed by tax type with { amount, overdueSince, nextChargeAt }. Use it to build a custom HUD widget or to hold doors closed until the player pays up. The data comes from the cached in-memory state and is refreshed every time collection runs.

How do I customize what happens when a player cannot afford tax?

Edit OnTaxOverdue in editable/server.lua. The hook receives { playerId, type, amount, daysOverdue } and is called every interval while debt is outstanding. Plug in your own garage lock, bank seizure or Discord notification. The default implementation applies the overdue fee configured in Config.OverduePenalty.

Exports & API Installation