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

# Bills & requests

> One 'money you owe' inbox with two kinds of entry - one-off payment requests players and shops raise, and recurring official bills your scripts push in.

Awoken Banking gives every player a single **money you owe** inbox, shown in the **Bills** tab of the app (and on the phone). It holds two kinds of entry, and the difference is who's in control of paying. Everything here is in `config/bills.lua`.

<CardGroup cols={2}>
  <Card title="Request" icon="hand-holding-dollar">
    A **one-off invoice** a player or script raises against someone - a shop billing a repair, a landlord billing rent, a player splitting a cost. The payer can **pay or decline**.
  </Card>

  <Card title="Bill" icon="file-invoice">
    A **recurring or official obligation** a script pushes in - utilities, subscriptions, fines. Not declinable, can carry a due date, go **overdue**, and recur. Always fee-free.
  </Card>
</CardGroup>

Both are paid from the payer's selected account into the issuer's account (or a sink if none was named). Turn the whole system off with `Config.Bills.enabled = false`.

## Requests

Requests are the peer / shop billing side. `Config.Bills.requests` controls what players may do from the UI and the caps on it.

```lua config/bills.lua theme={"dark"}
requests = {
    allowPlayerBilling = true,
    maxAmount          = 1000000,
    expiryHours        = 48,
    nearbyDistance     = 8.0,
    chargeFee          = true,
},
```

| Setting              | What it does                                                                         | Default   |
| -------------------- | ------------------------------------------------------------------------------------ | --------- |
| `allowPlayerBilling` | Let players raise requests from the app. `false` = export-only (scripts still bill). | `true`    |
| `maxAmount`          | Largest single request (`0` = no cap).                                               | `1000000` |
| `expiryHours`        | Auto-expire an unpaid request after N hours (`0` = never).                           | `48`      |
| `nearbyDistance`     | Range, in metres, for the "bill a nearby player" picker.                             | `8.0`     |
| `chargeFee`          | Apply the transfer fee when a request is paid (`false` = fee-free).                  | `true`    |

## Bills and overdue

Bills come in through scripts (rent, utilities, fines) and can carry a due date. When that date passes the bill is marked **overdue**; you can optionally add a one-time late fee and dock the player's credit score.

```lua config/bills.lua theme={"dark"}
overdue = {
    lateFeePct         = 0.0,
    creditScorePenalty = 0,
},
```

| Setting              | What it does                                                                                 | Default |
| -------------------- | -------------------------------------------------------------------------------------------- | ------- |
| `lateFeePct`         | Fraction of the bill added once when it turns overdue (`0` = none).                          | `0.0`   |
| `creditScorePenalty` | Credit points lost once when it turns overdue (`0` = none). Needs the loans / credit module. | `0`     |

<Note>
  `creditScorePenalty` only does anything when [Loans & credit](/resources/awoken-banking/configuration/loans) is enabled - that's where the score lives.
</Note>

## Categories

Bills are grouped and iconed in the UI by category. The set is fixed; an export may pass any of them, and anything else falls back to `other`.

```
utility | rent | insurance | subscription | fine | tax | other
```

## Raising bills from your scripts

Shops, landlords, and utility scripts bill players through the [bills exports](/resources/awoken-banking/exports#bills-and-requests). A **request** is declinable; a **bill** is not.

```lua server-side only theme={"dark"}
-- A mechanic shop bills a customer for a repair (they can pay or decline)
exports.awoken_banking:createInvoice({
    to     = repairCustomerSrc,     -- server id or citizenid
    from   = 'job:mechanic',        -- where the payment lands
    amount = 2500,
    reason = 'Engine repair',
})

-- A utilities script pushes a recurring power bill, due in 3 days
exports.awoken_banking:createBill({
    owner     = citizenid,
    name      = 'Power & Water',
    amount    = 800,
    category  = 'utility',
    to        = 'job:government',
    dueIn     = 3 * 86400,
    recurring = true,
    everyDays = 7,
})
```

React to what players do with them through the [bills events](/resources/awoken-banking/events#bills-and-requests) - `onInvoicePaid`, `onInvoiceDeclined`, `onBillPaid`, `onBillOverdue`, and more.