---
title: Books
description: "Invoices and what customers owe, read live from the owner's QuickBooks. 2 tools."
group: books
tools: [books.invoices, books.invoice]
source: [packages/agents/src/tools/books.ts]
generated: true
---

> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt

The owner's QuickBooks, read live as them: invoices, what each customer owes, and what was paid. Nothing here changes QuickBooks.

Chasing a payment is an email: find the invoice here, then write with [mail](/tools/mail/). A routine can wake an agent when an invoice falls overdue, with the key `kind:invoice.overdue`. See [routines and skills](/how-it-works/routines-and-skills/).

## How to use it

What `find_tools` sends with these tools, word for word:

> The owner's own QuickBooks: invoices, what each customer owes and what was paid, read live as them. Amounts are in the invoice's currency.

## Tools

| Tool | What it does | Owner's yes |
| --- | --- | --- |
| [books.invoices](#invoices) | Invoices, newest first, with customer, email, total, balance and due date. status is "open" (money owed), "overdue" (owed past its due date) or "paid"; customer matches part of a name | No |
| [books.invoice](#invoice) | One invoice's lines, amounts, tax, due date, customer email, whether it was emailed, and its link | No |

## invoices

`books.invoices` · Invoices, newest first, with customer, email, total, balance and due date. status is "open" (money owed), "overdue" (owed past its due date) or "paid"; customer matches part of a name.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `status` | one of `open`, `overdue`, `paid` | no |  |
| `customer` | text | no | 1–200 characters |
| `limit` | whole number | no | 1–50, default 20 |

Returns:

```ts
{
  invoices: {
    url: string;
    daysLate?: number;
    id: string;
    number: string | null;
    customer: string | null;
    email: string | null;
    date: string | null;
    due: string | null;
    total: number;
    balance: number;
    currency: string | null;
    status: string;
  }[];
  more: boolean;
}
```

## invoice

`books.invoice` · One invoice's lines, amounts, tax, due date, customer email, whether it was emailed, and its link.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `id` | text | yes | up to 30 characters, matches `^\d+$` |

Returns:

```ts
{
  tax: number;
  memo: string | null;
  emailed: boolean;
  lines: {
    unitPrice?: number;
    quantity?: number;
    item?: string;
    description: string;
    amount: number;
  }[];
  url: string;
  daysLate?: number;
  id: string;
  number: string | null;
  customer: string | null;
  email: string | null;
  date: string | null;
  due: string | null;
  total: number;
  balance: number;
  currency: string | null;
  status: string;
}
```