# Bill

URL: /business/nouns/bill · Id: `noun:bill`

> A Bill is an amount a Startup owes an outside Organization, coded to an account, approved within a Mandate, and paid by its due date.

A Bill is an amount a [Startup](/business/nouns/startup) owes an outside [Organization](/business/nouns/organization), coded to an account, approved within a [Mandate](/business/nouns/mandate), and paid by its due date.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `organization` | [Organization](/business/nouns/organization) | Yes | The Organization the Startup owes. |
| `amount` | `money` | Yes | What the Bill asks for, in its currency. |
| `dueOn` | `date` | Yes | The date payment is due; an approved Bill is paid on it. |
| `account` | `string` | No | The chart-of-accounts code it is coded to, such as `expense.hosting`. |
| `status` | `string` | Yes | Where the Bill stands; only an `approved` Bill is paid. |
| `file` | [File](/business/nouns/file) | No | The File the Bill arrived as: an email attachment or an upload. |

## Object
```json
{
  "$id": "https://api.sb/routewise.dev/bills/bill_1",
  "$type": "Bill",
  "organization": "organization_1",
  "amount": {
    "amount": 25,
    "currency": "USD"
  },
  "dueOn": "2026-10-22",
  "account": "expense.hosting",
  "status": "received",
  "file": "file_1"
}
```

## Relationships
- <a id="rel-owed-to"></a>A Bill **is owed to** one [Organization](/business/nouns/organization): a Bill is owed to one outside [Organization](/business/nouns/organization), whose page lists every Bill the [Startup](/business/nouns/startup) owes it. `owedTo`, inverse [`bills`](/business/nouns/organization#rel-bills).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `received` (first) | It arrived and is coded to an account, waiting for approval. | `approved` by [Bill.approve](/business/nouns/bill/approve) |
| `approved` | Accepted within the approver’s Mandate and scheduled for its due date. | `paid` by [Bill.pay](/business/nouns/bill/pay) |
| `paid` | Its amount is sent to the Organization and reconciled to Entries. | `approved` on [`Transaction.failed`](/business/nouns/transaction#transactionfailed) when the rail refused the Transaction that paid this Bill |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Bill.approve](/business/nouns/bill/approve) | Approve accepts a coded Bill for payment within the approver’s Mandate and schedules it for its due date. | [Finance Lead](/agents/finance/finance-lead) | [`Bill.approved`](/business/events/Bill.approved) | One-way (money): `send`, `do` |
| [Bill.pay](/business/nouns/bill/pay) | Pay sends an approved Bill’s amount to its Organization on the due date and reconciles the payment to Entries. | [Treasurer](/agents/finance/treasurer) | [`Bill.paid`](/business/events/Bill.paid) | One-way (money): `send`, `do` |
| <a id="create"></a>[Bill.create](/business/nouns/bill/create) | Creates a Bill. Inherited from [Noun](/business/nouns/noun). | None. | `Bill.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Bill.get](/business/nouns/bill/get) | Returns one Bill by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Bill.list](/business/nouns/bill/list) | Returns Bills, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Bill.update](/business/nouns/bill/update) | Changes the given properties of a Bill. Inherited from [Noun](/business/nouns/noun). | None. | `Bill.updated` | Two-way: `try`, `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Bill.create` | Yes | Yes | Yes | No |
| `Bill.get` | Yes | Yes | Yes | Yes |
| `Bill.list` | Yes | Yes | Yes | Yes |
| `Bill.update` | Yes | Yes | Yes | No |
| `Bill.approve` | Yes | No | No | No |
| `Bill.pay` | Yes | No | No | No |

## Call it

**Ask**

```text
Approve the latest bill.
```

**API**

```bash
curl -X POST https://api.sb/quietcopy.com/bills/bill_1/approve \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/quietcopy.com",
  "bill": {
    "$id": "https://api.sb/quietcopy.com/bills/bill_1",
    "$type": "Bill",
    "organization": "organization_1",
    "amount": {
      "amount": 39,
      "currency": "USD"
    },
    "dueOn": "2026-10-22",
    "status": "received"
  },
  "action": {
    "$id": "https://api.sb/quietcopy.com/actions/action_1",
    "operation": "Bill.approve",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/quietcopy.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const bill = await $.Bill.approve({ bill: 'bill_1' })
```

**CLI**

```bash
npx startup-builder do Bill.approve --json '{"bill":"bill_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Bill.approve({ bill: 'bill_1' })"
  }
}
```

## Example
A hosting invoice for $640 arrives by email at a pet-supply store. It becomes a Bill coded to `expense.hosting`, the [Finance Lead](/agents/finance/finance-lead) approves it within its [Mandate](/business/nouns/mandate), and the [Treasurer](/agents/finance/treasurer) pays it on the 30th.