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

# Invoices

> List and get company invoices on the public API under /v1/invoices.

## Overview

Partners read invoices under `/v1/invoices` with scope `invoices:read`. The public contract is a lean profile by default (amounts, status, customer id, dates). Pass `expand` to add related fields. Office `/api/v2/invoices` remains the internal surface and may return richer fields.

## Endpoints

| Method | Path | Scope |
| - | - | - |
| `GET` | `/v1/invoices` | `invoices:read` |
| `GET` | `/v1/invoices/billing-queue` | `invoices:read` |
| `GET` | `/v1/invoices/open-for-match` | `invoices:read` |
| `GET` | `/v1/invoices/{id}` | `invoices:read` |

## List filters

`GET /v1/invoices` supports:

* `page`, `limit` — pagination (default page 1, limit 25, max 100)
* `open=true` — only OPEN / OVERDUE / PARTIAL\_PAID invoices with billing queue status POSTED
* `customerIds` — comma-separated customer UUIDs
* `invoiceNumbers` — comma-separated invoice numbers
* `status` — comma-separated status values (ignored when `open=true`)
* `invoiceDateFrom` / `invoiceDateTo` — ISO date-time bounds on `invoiceDate`
* `expand` — allowlisted tokens below; unknown tokens return `400`

## Billing queue

`GET /v1/invoices/billing-queue` calls the same LoopBack billing-queue controller the office uses (`Company.getPosted`). Query args match that controller (`q`, `billingQueueStatus`, `status`, `customers`, date ranges, delivery, sales/accounting filters, haulers, labels, `sort`, `pageNo`, `limit`). Default tab is `POSTED`. The response is projected onto the public invoice list shape. Pass `expand=customer,order,location` to include those fields from the queue row.

## Open for match

`GET /v1/invoices/open-for-match` shares the Nest open-for-match reader used by `GET /api/v2/invoices/open-for-match`. Query params: `customerIds`, `invoiceNumbers`, `limit` (default 50, max 100). With neither customer nor invoice number filter, the response is an empty list. Pass `expand=customer` for `{ id, displayName }` on each row.

## Get by id

`GET /v1/invoices/{id}` returns `{ data: PublicInvoice }`. Cross-company ids return `404 NOT_FOUND`. Pass detail expands (`items`, `payments`, `creditNotes`, `paymentPolicy`) to include those fields.

## Expand

Pass `expand` as a comma-separated list. Default responses stay lean; expand only *adds* fields. Allowlists differ by route.

### `GET /v1/invoices` and `GET /v1/invoices/open-for-match`

| Token | Adds |
| - | - |
| `customer` | `{ id, displayName }` when present on the source row |

### `GET /v1/invoices/billing-queue`

| Token | Adds |
| - | - |
| `customer` | `{ id, displayName }` |
| `order` | `{ number, type }` |
| `location` | `{ name, address, zipcode }` |

### `GET /v1/invoices/{id}`

| Token | Adds |
| - | - |
| `customer` | `{ id, displayName }` |
| `items` | finalized line items |
| `payments` | `{ id, reference, amount, paymentDate }` |
| `creditNotes` | `{ id, description, currency, amount, creditNoteNumber }` |
| `paymentPolicy` | term, method, mode, surcharges, delivery |

Unknown expand values fail closed with `400 BAD_REQUEST`. A token valid on one route and invalid on another is rejected on the wrong route (for example `items` on billing-queue, or `order` on get).

## Related

* [API Reference overview](https://docs.curbwaste.com/api-reference/overview.md)
* [Errors](https://docs.curbwaste.com/api-reference/errors.md)
* [MCP](https://docs.curbwaste.com/concepts/mcp.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.