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

# BILL

> Vendors, bills, the approval gate and the payments that clear them

An accounts payable ledger over BILL's v3 API: vendors, bills with server-computed amounts, the approval policy a bill has to clear, the payments that settle it, and the receivable side beside it. BILL publishes no Python client, so the conformance suite pins the OpenAPI document BILL serves and validates every response the twin gives against it.

**Slug:** `bill`

## What it models

| Area           | Modelled                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Organization   | One organization with a user, a chart of accounts, one verified bank account default for payables and receivables, an approval policy for bills of one hundred dollars or more, and a live session, because a caller handed an environment has to be able to make a call                                                                                                                                            |
| Authentication | BILL's pair of headers — the `devKey` an environment mints and the `sessionId` `POST /v3/login` opens — with logout, session introspection, the 35 minute idle window as its own failure, the rate limit, and every failure in BILL's `BdcError` envelope, which is a list rather than an object                                                                                                                    |
| Vendors        | List, create, retrieve, update, archive and restore, with BILL's required address, a bank account that starts unverified, and no uniqueness rule, because BILL documents none                                                                                                                                                                                                                                       |
| Bills          | Bills with line items whose totals BILL computes, `paidAmount`, `scheduledAmount` and `dueAmount` moving with every payment, `paymentStatus` and `approvalStatus` as projections rather than fields, `PATCH` that keeps line item ids and `PUT` that replaces them, duplicate invoice numbers allowed by default and refused on request, archive and restore, and the edits refused once a bill is approved or paid |
| Bill approvals | The organization's policy, the queue of bills waiting on the signed-in user, approving and denying in the array BILL declares, ordered approvers, and a two-step policy a single approval no longer clears                                                                                                                                                                                                          |
| Payments       | Paying an approved bill in full or in part, cancelling one that is still scheduled, the funding options for a vendor and an amount, and payments recorded from outside BILL, which settle the bill without BILL processing anything                                                                                                                                                                                 |
| Receivables    | Customers, invoices with computed totals and the dates BILL defaults, and payments recorded against them with the overpayment reported as an unapplied amount                                                                                                                                                                                                                                                       |
| Peripheral     | The chart of accounts, and the organization's bank accounts as read-only                                                                                                                                                                                                                                                                                                                                            |

Advancing moves every lifecycle one step: a vendor bank account from unverified to verified, which closes BILL's two business day window and is what makes its `BDC_1402` refusal reachable; a session past its idle window; a scheduled payment into process and then to paid — or to failed, when a directive seeded that outcome, which puts the bill back in debt; and a bill past its due date, which an aging report reads as BILL gives it, through `dueDate` and `dueAmount`.

## Scenarios

`busy-payables`, `awaiting-approval`, `failed-payment`, `expired-session`, `open-receivables`.

## Not modelled

Every Spend & Expense operation — the `apiToken` surface BILL ships in the same document, which was Divvy — so the twin never implies it covers it. Budgets, cards, credit memos, vendor credits, reimbursements, recurring bills and invoices, mass and bulk payments, exports and reports, risk verifications, the BILL network, user roles, custom fields, documents and attachments, and international payment configuration. Voiding a payment, creating an organization bank account, the vendor bank account endpoints, non-USD amounts, the accounting classifications BILL filters bills and invoices by, and MFA, which this organization has switched off at the developer key level. BILL declares no idempotency header, so the twin reads none: a retried create makes a second bill, and refusing a duplicate invoice number is the protection BILL actually offers.

The twin was built from BILL's OpenAPI document and developer documentation without a sandbox account, so the per-code HTTP statuses, the developer key and session id formats, and the payment lifecycle's exact order are choices rather than observations. Its README lists every one of them.