# invoices.list

List invoices with number, customer, project, dates, totals, balance due, and status. Filter by status (including open, unpaid, upcoming and needs_action: awaiting approval, ready to send by hand, or late), overdue, customer, project (or none), currency, source (manual, duplicate, recurring, plan, import), schedule, issue or due date range, or search text. Archived invoices are left out unless archived is only or include. Sort by issued, due, amount, number, updated or created. Overdue is derived from the due date and remaining balance.

`GET | POST /api/v1/accounting/invoices.list`

Permissions: `accounting:read` · Roles: admin, finance

MCP tool: `accounting_invoices_list`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `status` | enum |  | Only include records with this status. One of: `draft`, `scheduled`, `awaiting_approval`, `approved`, `sent`, `partially_paid`, `paid`, `overdue`, `void`, `uncollectible`, `open`, `upcoming`, `unpaid`, `needs_action`. |
| `partyId` | string (ID) |  | The ID of a customer or vendor account, from parties.list. |
| `scheduleId` | string (ID) |  | The ID of the related record. |
| `projectId` | string (ID) or "none" |  | One of: `none`. |
| `currency` | string |  | Three-letter currency code, such as CAD or USD. |
| `source` | enum |  | Where the record came from. One of: `manual`, `duplicate`, `recurring`, `plan`, `import`. |
| `archived` | enum |  | Whether the record is archived. One of: `exclude`, `only`, `include`. Default `"exclude"`. |
| `from` | string |  | The first date to include, as YYYY-MM-DD. |
| `to` | string |  | The last date to include, as YYYY-MM-DD. |
| `dueFrom` | string |  |  |
| `dueTo` | string |  |  |
| `search` | string |  | Text to search for. at most 200 characters. |
| `overdue` | boolean |  |  |
| `sort` | enum |  | One of: `issued`, `due`, `amount`, `number`, `updated`, `created`. |
| `direction` | enum |  | One of: `asc`, `desc`. |
| `limit` | integer |  | How many results to return at most. 1 to 200. Default `50`. |
| `offset` | integer |  | How many results to skip, for the next page of a list. 0 to 100000. Default `0`. |

## Example request

```bash
curl https://app.getoatmilk.com/api/v1/accounting/invoices.list \
  -H "Authorization: Bearer $OATMILK_API_KEY"
```

Reference page: https://app.getoatmilk.com/docs/api/invoices.list