> For the complete documentation index, see [llms.txt](https://fantasy-scripts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fantasy-scripts.gitbook.io/docs/advanced-government-v2/exports.md).

# Exports

## fs-governmentv2 Taxation Exports

Easy-to-use exports for integrating the government taxation system into any FiveM resource.

***

### Quick Start

Add tax to any transaction in your resource with just **one line of code**:

```lua
-- Example: Tax a vehicle purchase of $50,000
exports['fs-governmentv2']:ApplyTax(source, 50000, 'vehicle', 'Vehicle purchase')
```

That's it! This automatically:

* Calculates the tax based on current rates
* Deducts the tax from the player's bank
* Records the tax in the government database
* Notifies the player of the deduction
* Logs it as government revenue

***

### Primary Exports

#### `ApplyTax(source, amount, taxType, description)`

**The recommended export for most integrations.** Calculates tax, deducts from player, and records everything in one call.

| Parameter   | Type   | Required | Description                                                                  |
| ----------- | ------ | -------- | ---------------------------------------------------------------------------- |
| source      | number | Yes      | Player server ID                                                             |
| amount      | number | Yes      | Base amount to calculate tax on (e.g. item price)                            |
| taxType     | string | Yes      | Tax type key (e.g. `'vehicle'`, `'property'`, `'salary'`, or any custom key) |
| description | string | No       | Description for the tax record                                               |

**Returns:** `taxAmount` (number), `success` (boolean)

```lua
-- Vehicle dealership: tax a $50,000 car purchase
local taxAmount, success = exports['fs-governmentv2']:ApplyTax(source, 50000, 'vehicle', 'Vehicle purchase - Elegy RH8')

if success then
    print('Tax of $' .. taxAmount .. ' collected')
else
    print('Could not collect tax (insufficient funds or rate is 0)')
end
```

```lua
-- Property system: tax a house purchase
exports['fs-governmentv2']:ApplyTax(source, 250000, 'property', 'House purchase - Grove Street')
```

```lua
-- Paycheck system: tax a salary payment
exports['fs-governmentv2']:ApplyTax(source, 5000, 'salary', 'Weekly paycheck - Police')
```

```lua
-- Custom shop: tax an item purchase with a custom tax type
exports['fs-governmentv2']:ApplyTax(source, 1200, 'luxury_goods', 'Jewelry purchase')
```

***

#### `CalculateTax(amount, taxType)`

Calculate the tax amount without applying it. Useful for showing tax previews in shop UIs.

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| amount    | number | Yes      | Base amount  |
| taxType   | string | Yes      | Tax type key |

**Returns:** `taxAmount` (number)

```lua
-- Show player how much tax they'll pay before confirming purchase
local price = 50000
local tax = exports['fs-governmentv2']:CalculateTax(price, 'vehicle')
local total = price + tax

-- Display to player: "Vehicle: $50,000 + $4,000 tax = $54,000 total"
```

***

#### `GetTaxRate(taxType)`

Get the current tax rate for a specific type.

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| taxType   | string | Yes      | Tax type key |

**Returns:** Rate as decimal (e.g. `0.15` for 15%)

```lua
local rate = exports['fs-governmentv2']:GetTaxRate('vehicle')
-- Returns: 0.08 (8%)

-- Display as percentage:
local percent = rate * 100  -- 8
```

***

#### `GetTaxRates()`

Get all current tax rates as a key-value table.

**Returns:** Table of all rates

```lua
local rates = exports['fs-governmentv2']:GetTaxRates()
-- Returns: { salary = 0.15, business = 0.12, vehicle = 0.08, property = 0.10, ... }

for taxType, rate in pairs(rates) do
    print(taxType .. ': ' .. (rate * 100) .. '%')
end
```

***

### Advanced Exports

#### `AddTaxRecord(taxType, amount, payerIdentifier, payerName, originalAmount, metadata)`

Record a tax entry without deducting money. Use this when you handle the money deduction yourself.

| Parameter       | Type   | Required | Description                                |
| --------------- | ------ | -------- | ------------------------------------------ |
| taxType         | string | Yes      | Tax type key                               |
| amount          | number | Yes      | Tax amount collected                       |
| payerIdentifier | string | Yes      | Player identifier (steam:xxx, license:xxx) |
| payerName       | string | No       | Display name (defaults to 'Unknown')       |
| originalAmount  | number | No       | Pre-tax base amount                        |
| metadata        | table  | No       | Additional data to store                   |

```lua
-- You already deducted $500 tax from the player yourself
-- Just record it in the government system
exports['fs-governmentv2']:AddTaxRecord(
    'import_duty',       -- tax type
    500,                 -- tax amount
    playerIdentifier,    -- e.g. "steam:110000xxxxxxx"
    playerName,          -- e.g. "John Doe"
    10000,              -- original amount ($10,000 import)
    { item = 'luxury_watch', origin = 'overseas' }  -- optional metadata
)
```

***

#### `SetTaxRate(taxType, rate, updatedBy)`

Programmatically change a tax rate. Persists to database.

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| taxType   | string | Yes      | Tax type key                     |
| rate      | number | Yes      | New rate as decimal (0.15 = 15%) |
| updatedBy | string | No       | Identifier of who changed it     |

```lua
-- Set vehicle tax to 10%
exports['fs-governmentv2']:SetTaxRate('vehicle', 0.10, 'system')

-- Create a new tax type by setting its rate
exports['fs-governmentv2']:SetTaxRate('import_duty', 0.07, 'system')
```

***

#### `GetTaxRevenue(days, taxType)`

Get revenue summary for a period.

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| days      | number | No       | Days to look back (default: 30) |
| taxType   | string | No       | Filter by tax type              |

**Returns:** `{ total, breakdown, period_days }`

```lua
-- Get total tax revenue for last 30 days
local revenue = exports['fs-governmentv2']:GetTaxRevenue(30)
print('Total: $' .. revenue.total)
-- revenue.breakdown = { salary = { amount = 50000, count = 120 }, ... }

-- Get vehicle tax revenue for last 7 days
local vehicleRev = exports['fs-governmentv2']:GetTaxRevenue(7, 'vehicle')
print('Vehicle tax (7d): $' .. vehicleRev.total)
```

***

#### `GetTaxRecords(filters)`

Query detailed tax records with filters.

| Parameter               | Type   | Description                |
| ----------------------- | ------ | -------------------------- |
| filters.taxType         | string | Filter by tax type         |
| filters.payerIdentifier | string | Filter by payer            |
| filters.days            | number | Records from last N days   |
| filters.search          | string | Search payer name          |
| filters.limit           | number | Max records (default: 100) |
| filters.offset          | number | Pagination offset          |

**Returns:** `{ records, total, limit, offset }`

```lua
-- Get last 50 salary tax records
local result = exports['fs-governmentv2']:GetTaxRecords({
    taxType = 'salary',
    limit = 50
})

for _, record in ipairs(result.records) do
    print(record.payer_name .. ' paid $' .. record.amount)
end
```

***

### Event-Based Integration

If you prefer events over exports:

```lua
-- Record a tax (server-side)
TriggerEvent('fs-governmentv2:server:addTax', 'vehicle', 4000, playerIdentifier, playerName, { item = 'Elegy RH8' })

-- Apply tax to a player (server-side, from another server script)
TriggerEvent('fs-governmentv2:server:applyTax', targetSource, 50000, 'vehicle', 'Vehicle purchase')

-- Listen for tax collections (server-side)
AddEventHandler('fs-governmentv2:server:taxRecorded', function(data)
    print('Tax collected: $' .. data.amount .. ' type: ' .. data.taxType .. ' from: ' .. data.payerName)
end)

-- Listen for rate changes (server-side)
AddEventHandler('fs-governmentv2:server:taxRatesUpdated', function(newRates)
    print('Tax rates updated!')
    for k, v in pairs(newRates) do
        print('  ' .. k .. ': ' .. (v * 100) .. '%')
    end
end)
```

***

### Integration Examples

#### Vehicle Dealership

```lua
-- In your dealership purchase function:
local function PurchaseVehicle(source, model, price)
    -- Calculate total with tax
    local tax = exports['fs-governmentv2']:CalculateTax(price, 'vehicle')
    local total = price + tax

    -- Check if player can afford total
    if not CanAfford(source, total) then
        Notify(source, 'You need $' .. total .. ' ($' .. price .. ' + $' .. tax .. ' tax)')
        return
    end

    -- Deduct vehicle price
    RemoveMoney(source, price)

    -- Apply tax (deducts and records automatically)
    exports['fs-governmentv2']:ApplyTax(source, price, 'vehicle', 'Vehicle purchase - ' .. model)

    -- Give vehicle
    GiveVehicle(source, model)
end
```

#### Property System

```lua
-- When a player buys a house:
local function BuyProperty(source, propertyId, price)
    RemoveMoney(source, price)
    exports['fs-governmentv2']:ApplyTax(source, price, 'property', 'Property purchase #' .. propertyId)
    TransferProperty(source, propertyId)
end
```

#### Custom Shop with Tax Preview

```lua
-- Show price with tax in shop UI
RegisterNetEvent('myshop:server:getPrice', function(itemId)
    local source = source
    local price = GetItemPrice(itemId)
    local tax = exports['fs-governmentv2']:CalculateTax(price, 'business')
    TriggerClientEvent('myshop:client:showPrice', source, {
        price = price,
        tax = tax,
        total = price + tax,
        taxRate = exports['fs-governmentv2']:GetTaxRate('business') * 100
    })
end)
```

#### Paycheck System

```lua
-- Automatic salary taxation on paychecks
RegisterNetEvent('paycheck:give', function(source, salary, jobName)
    -- Option 1: Use ApplyTax (deducts tax from player)
    local taxAmount, success = exports['fs-governmentv2']:ApplyTax(source, salary, 'salary', jobName .. ' salary')
    local netPay = salary - taxAmount
    AddMoney(source, netPay)

    -- Option 2: Just record it (if you already handle deduction)
    -- local taxAmount = exports['fs-governmentv2']:CalculateTax(salary, 'salary')
    -- AddMoney(source, salary - taxAmount)
    -- exports['fs-governmentv2']:AddTaxRecord('salary', taxAmount, GetIdentifier(source), GetName(source), salary)
end)
```

#### DMV / License System

```lua
-- Tax on license purchases
local function IssueLicense(source, licenseType, fee)
    RemoveMoney(source, fee)
    exports['fs-governmentv2']:ApplyTax(source, fee, 'dmv_fee', 'License issued: ' .. licenseType)
    GiveLicense(source, licenseType)
end
```

***

### Available Tax Types (Default)

| Key            | Label        | Default Rate |
| -------------- | ------------ | ------------ |
| `salary`       | Salary Tax   | 15%          |
| `business`     | Business Tax | 12%          |
| `vehicle`      | Vehicle Tax  | 8%           |
| `property`     | Property Tax | 10%          |
| `dmv_fee`      | DMV Fee      | 5%           |
| `parking_fine` | Parking Fine | 2%           |

Custom tax types can be added from the government tablet or via `SetTaxRate()`.

Tax rates are configurable in `config.lua` under `Config.Taxation.rates` and can be changed at runtime from the government tablet by authorized officials.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://fantasy-scripts.gitbook.io/docs/advanced-government-v2/exports.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.