> ## 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.lua

Tax rates, personal and business taxes, treasury, recurring taxes and the scheduler. More in the [Taxes & Treasury](https://docs.aps-store.com/assets/aps_cityhall/guides/taxes-and-treasury.md) guide.

> [!NOTE]
>
> Runs on: **shared**. This file stays editable when the resource is escrow-protected. Restart the resource after editing.

***

## Full View

Preview File Updated: 3.7.0 - 02.11.2026

```lua config/taxes.lua lines expandable theme={null}
Config = Config or {}

-- ═════════════════════════════════════════════
--  TAXES  (Config.Features.taxes)
--  Personal taxes, business taxes, recurring vehicle / property taxes and
--  the city treasury. Players pay in the Finances app on the City Hall PC.
-- ═════════════════════════════════════════════

-- ─────────────────────────────────────────────
--  Tax rates (%)
--  Other scripts pick a rate by its path, e.g. 'products.food' or 'tuning':
--    exports['aps_cityhall']:addCompanyTaxAmount('ltd1', 250, 'products.food')
--  The paths and defaults match vms_cityhall, so scripts written for it
--  (vms_tuning, vms_vehicleshopV2, vms_stores, vms_tattooshop, vms_barber,
--  vms_gym) find the same rates.
-- ─────────────────────────────────────────────
Config.Taxes = {
    gains = {               -- personal taxes
        vehicleexcise = 7,  -- buying a vehicle from another player
    },

    tuning   = 5,           -- business taxes
    vehicles = { mechanical = 18, electric = 9, bikes = 5 },
    products = { electronics = 21, alcohol = 23, food = 33, drinks = 30, other = 23, fuel = 20 },
    tattoos  = 18,
    barber   = 12,
    gym      = { memberships = 8, proteins = 10 },

    income   = 0,           -- taken from paychecks when they are withdrawn (Config.Features.paychecks)
}

-- ─────────────────────────────────────────────
--  Personal taxes
--    paymentDays           days to pay before late fees start
--    overduePercentPerDay  late fee per day, in % of the tax
--                          (2 → 20 % after 10 days late)
--    overdueMaxPercent     highest late fee in % (false = no limit)
--    autoCollectAfterDays  days late after which the tax is taken from the
--                          player's bank automatically, also offline
--                          (false = never)
--    historyDays           paid / cancelled taxes shown in the Finances app
-- ─────────────────────────────────────────────
Config.TaxSettings = {
    paymentDays          = 14,
    overduePercentPerDay = 2,
    overdueMaxPercent    = 100,
    autoCollectAfterDays = false,
    historyDays          = 30,
}

-- ─────────────────────────────────────────────
--  City treasury
--  Every tax payment goes into the treasury (Government Portal →
--  Taxes & Treasury). Optionally a share goes to a society account instead,
--  e.g. a 'cityhall' job's boss menu.
--    society         'society_cityhall' or nil
--    societyPercent  share of every tax payment sent to that society
-- ─────────────────────────────────────────────
Config.Treasury = {
    society        = nil,
    societyPercent = 90,
}

-- ─────────────────────────────────────────────
--  Business taxes
--  Businesses collect tax on their income through the exports below; at the
--  end of each month the total is due. A boss pays it in Finances →
--  Business taxes, from the business account.
--
--    allowDelayedDeclarations   late months can still be paid by the boss
--                               (false = only last month; older ones are
--                               only collected automatically)
--    percentPerMonthDelay       late interest per month, in %
--                               (20 → a tax two months late costs +40 %)
--    autoCollectAfterMonths     months late after which the tax (plus interest)
--                               is taken from the business account
--                               automatically (false = never)
--    bossGrades                 job → lowest grade that may pay
--                               (default: the framework's boss grade;
--                               vms_bossmenu's 'taxesAccess' permission when running)
--    registerBusinesses         Business Register businesses linked to a job
--                               get a tax account automatically
--    registerFlatMonthly        flat monthly tax for every active Business
--                               Register business linked to a job (0 = none)
--
--  accounts: job → { label, resource, id }
--    resource / id  where the money comes from: a vms business script
--                   (getCompanyMoney / removeCompanyMoney with that id).
--                   Without a resource the job's society account is used
--                   (vms_bossmenu, esx_addonaccount, qb-banking … Config.Society).
--                   Accounts whose resource isn't started are ignored.
--  Other scripts can also register accounts at runtime:
--    exports['aps_cityhall']:registerBusinessTaxAccount(job, label)
-- ─────────────────────────────────────────────
Config.BusinessTaxes = {
    allowDelayedDeclarations = true,
    percentPerMonthDelay     = 20,
    autoCollectAfterMonths   = 3,
    bossGrades               = {
        -- ['police'] = 4,
    },
    registerBusinesses       = true,
    registerFlatMonthly      = 0,

    accounts = {
        -- ['police']    = { label = 'LSPD' },
        -- ['ambulance'] = { label = 'EMS' },
        ['mechanic'] = { label = 'Bennys',                      resource = 'vms_tuning',        id = 'BennyS' },
        ['pdm']      = { label = 'Premium Deluxe Motorsports',  resource = 'vms_vehicleshopv2', id = 'PDM' },
        ['gym1']     = { label = 'Gym Plaza',                   resource = 'vms_gym',           id = 'Gym_1' },
        ['gym2']     = { label = 'Gym Pump & Run',              resource = 'vms_gym',           id = 'Gym_2' },
    },
}

-- vms_barber / vms_tattooshop / vms_stores default shops (ids as in vms_cityhall;
-- check them against those scripts' own configs)
for i = 1, 7 do
    Config.BusinessTaxes.accounts['barber' .. i] = { label = ('Barber Shop [%d]'):format(i), resource = 'vms_barber', id = 'HS_Barber_' .. i }
end
for i = 1, 6 do
    Config.BusinessTaxes.accounts['tattoo' .. i] = { label = ('Tattoo Shop [%d]'):format(i), resource = 'vms_tattooshop', id = 'Tattooshop_' .. i }
end
for i = 1, 5 do
    Config.BusinessTaxes.accounts['ltd' .. i] = { label = ('LTD Gasoline [%d]'):format(i), resource = 'vms_stores', id = 'LTDGasoline_' .. i }
end
for i = 1, 4 do
    Config.BusinessTaxes.accounts['robsliquor' .. i] = { label = ("Rob's Liquor [%d]"):format(i), resource = 'vms_stores', id = 'RobsLiquor_' .. i }
end
for i = 1, 9 do
    Config.BusinessTaxes.accounts['twentyfourseven' .. i] = { label = ('Twenty Four Seven [%d]'):format(i), resource = 'vms_stores', id = 'TwentyFourSeven_' .. i }
end

-- ─────────────────────────────────────────────
--  Recurring taxes
--  Added to every owner as a personal tax once per period (week / month).
--
--  vehicle   percent of the vehicle's catalog price, per vehicle
--    exemptCategories    catalog categories that are not taxed
--    exemptJobVehicles   vehicles with a job (Config.Business.vehicles.jobColumn)
--                        and Business Register vehicles are not taxed
--
--  property  percent of the property's price
--    system  'auto' | 'esx_property' | 'qb-houses' | 'ps-housing' | 'vms_housing'
-- ─────────────────────────────────────────────
Config.RecurringTaxes = {
    vehicle = {
        enabled           = false,
        interval          = 'week',   -- 'week' | 'month'
        percent           = 0.5,
        min               = 50,
        max               = 5000,
        exemptCategories  = { 'cycles' },
        exemptJobVehicles = true,
        title             = 'Vehicle tax',
    },
    property = {
        enabled  = false,
        system   = 'auto',
        interval = 'month',
        percent  = 1.0,
        min      = 100,
        max      = 20000,
        title    = 'Property tax',
    },
}

-- ─────────────────────────────────────────────
--  Scheduler — how often City Hall checks for due work (minutes):
--  recurring taxes, automatic tax collection, expired penalty points.
--  Each job runs once per period, also across restarts.
-- ─────────────────────────────────────────────
Config.Scheduler = {
    interval = 10,
}
```


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