> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aps-store.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Taxes & Treasury

`config/taxes.lua` · `Config.Features.taxes`. Personal taxes, monthly business taxes, recurring vehicle and property taxes, and a city treasury. Players pay in the **Finances** app.

## Personal taxes

Other scripts add a tax when something taxable happens (a property purchase, a private vehicle sale…). Staff can also add one in the Government Portal. The player has `paymentDays` to pay; after that a late fee of `overduePercentPerDay` per day is added, up to `overdueMaxPercent`.

```lua theme={null}
Config.TaxSettings = {
    paymentDays          = 14,
    overduePercentPerDay = 2,       -- 10 days late = +20 %
    overdueMaxPercent    = 100,
    autoCollectAfterDays = false,   -- e.g. 7: taken from the bank automatically, also offline
    historyDays          = 30,
}
```

```lua theme={null}
-- esx_property: tax on a purchase
exports['aps_cityhall']:addPlayerCustomTaxToPay(xPlayer.identifier, price, 15, 'Property purchase tax')
-- by a rate from Config.Taxes
exports['aps_cityhall']:addPlayerTaxToPay(identifier, 25000, 'gains.vehicleexcise', 'Vehicle sale')
```

## Business taxes

Businesses report income as it happens; City Hall adds up the tax for each month. At the start of a month the previous month is *due*, and a boss pays it from the business account in Finances → Business taxes. Every further month adds `percentPerMonthDelay` interest. After `autoCollectAfterMonths` City Hall takes the money itself.

```lua theme={null}
-- a store sold food for $250 → 33 % tax (Config.Taxes.products.food) on this month's account
exports['aps_cityhall']:addCompanyTaxAmount('ltd1', 250, 'products.food')
exports['aps_cityhall']:addCompanyCustomTaxAmount('taxi', total, 8)
exports['aps_cityhall']:addCompanyFlatTaxAmount('mechanic', 500)
```

Where the money comes from is set per account in `Config.BusinessTaxes.accounts`: a vms business script (`resource` + `id`, using its `getCompanyMoney` / `removeCompanyMoney`), otherwise the job's society account through [Config.Society](https://docs.aps-store.com/assets/aps_cityhall/compability.md). Accounts whose resource isn't running are ignored, so the vms defaults do nothing on servers without those scripts. Business Register businesses linked to a job get an account automatically, optionally with a flat monthly tax (`registerFlatMonthly`).

Who may pay: the framework's boss grade, a grade from `bossGrades`, or vms\_bossmenu's `taxesAccess` permission when vms\_bossmenu runs. Due taxes are announced through the vms business script / vms\_bossmenu, or by phone to online bosses.

## Rates

`Config.Taxes` uses the same paths and defaults as vms\_cityhall (`gains.vehicleexcise`, `tuning`, `vehicles.*`, `products.*`, `tattoos`, `barber`, `gym.*`), so vms scripts find their rates. `income` is taken from paychecks when they are collected.

## Recurring vehicle & property tax

Off by default. Once per period every owner gets a tax: a percentage of the vehicle's catalog price (job and business vehicles exempt) or of the property price.

```lua theme={null}
Config.RecurringTaxes = {
    vehicle  = { enabled = false, interval = 'week',  percent = 0.5, min = 50,  max = 5000,  exemptCategories = { 'cycles' } },
    property = { enabled = false, interval = 'month', percent = 1.0, min = 100, max = 20000, system = 'auto' },
}
```

Property systems: `esx_property` (tested), `qb-houses`, `ps-housing`, `vms_housing` (written from their table / export layout, untested).

## Treasury

Every tax payment goes into the treasury (`aps_treasury`). `Config.Treasury.society` can send a share to a society account instead. In the Government Portal, **Taxes & Treasury** shows the balance, the ledger and every business account; `treasury.manage` can transfer money to a department's society account.

| Permission | Allows |
| - | - |
| `taxes.view` | See citizens' and businesses' taxes and the treasury |
| `taxes.manage` | Add and cancel taxes |
| `treasury.manage` | Transfer treasury money to a job's society account |

Scheduled work (late collection, monthly reminders, recurring taxes) runs every `Config.Scheduler.interval` minutes and only once per period, also across restarts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.