See what is unpaid for one supplier

# Instructions

## Use case

Identify all overdue invoices for a given supplier, broken down by aging bucket (1-30, 31-60, 61-90, 90+ days).

## Step 1 — Find the supplier ID

`spendesk_get_due_invoices` returns invoices with `supplier: "Supplier name"` (a name, not an ID). To filter by supplier, you must first resolve the name to an ID:

```json
// get_suppliers
{
  "companyId": "<COMPANY_ID>",
  "search": "Vaultspeed"
}
```

→ Retrieve `data[0].id` → e.g. `"t0tiu752i9bms9"`

## Step 2 — Aging filtered by supplier

```json
// spendesk_get_due_invoices
{
  "companyId": "<COMPANY_ID>",
  "filters": {
    "supplierIds": ["t0tiu752i9bms9"]
  },
  "includeUpcoming": true,
  "limit": 20
}
```

### Parameters available in filters

| Parameter | Type | Description |
|-----------|------|-------------|
| `supplierIds` | `string[]` | Filter by one or more suppliers |
| `costCenterIds` | `string[]` | Filter by cost center |
| `currencies` | `string[]` | Filter by currency (e.g. `["EUR", "GBP"]`) |
| `minAmount` | `number` | Minimum amount (decimal) in the functional currency, compared against the invoice's gross amount, not its outstanding balance |

### Options

- `includeUpcoming: true` → adds a "Not yet due" bucket (invoices not yet due)
- `limit` → maximum number of invoices per bucket (default 10, max 50)
- `asOfDate` → reference date (default = today, format `YYYY-MM-DD`)

## Result structure

```json
{
  "summary": {
    "asOfDate": "2026-07-06",
    "totalOverdueAmount": { "amount": 81986, "currency": "EUR", "precision": 2 },
    "totalOverdueCount": 2,
    "oldestInvoiceDaysOverdue": 301
  },
  "data": {
    "upcoming": { "label": "Not yet due", "count": 0, "invoices": [] },
    "buckets": [
      { "label": "1-30 days",  "count": 0, "invoices": [] },
      { "label": "31-60 days", "count": 0, "invoices": [] },
      { "label": "61-90 days", "count": 0, "invoices": [] },
      { "label": "90+ days",   "count": 2, "invoices": [
        {
          "id": "a7f1c327-...",
          "supplier": "Vaultspeed",
          "amount": { "amount": 13548, "currency": "GBP", "precision": 2 },
          "currency": "GBP",
          "invoiceNumber": "CB-CN-202509-1142",
          "invoiceDueDate": "2025-09-08",
          "costCenter": "Revenue",
          "daysOverdue": 301
        }
      ]}
    ]
  }
}
```

## Pitfall 1 — The summary is in EUR, invoices in native currency

`summary.totalOverdueAmount` is expressed in the functional currency, to be read from `summary.currency` (EUR in this example, never assume it), but each `invoice.amount` is in the invoice's original currency. In this example:
- Vaultspeed: 135.48 GBP (invoice in pounds)
- eau de paris: 663.79 EUR (invoice in euros)

→ Do not sum `invoice.amount` across invoices in different currencies. Use `summary.totalOverdueAmount` for the converted total.

## Pitfall 2 — Reverse name → ID lookup is mandatory

`spendesk_get_due_invoices` does not return supplier IDs in the response — only the name (`supplier: "Vaultspeed"`). To use the `supplierIds` filter, you **must necessarily** go through `get_suppliers(search=name)` first.

## Pitfall 3 — Only invoicePurchase toPay

`spendesk_get_due_invoices` only covers **supplier invoices** (`invoicePurchase`) with `paymentStatus = toPay`. Excluded:
- Expense reports
- Card purchases
- Fully paid invoices (partially paid invoices are still included), credit notes, and invoices with no due date

## Advanced use cases

**Several suppliers at once:**
```json
{ "filters": { "supplierIds": ["t0tiu752i9bms9", "b3E3B8t2s5"] } }
```

**Overdue + upcoming invoices for a supplier:**
```json
{ "filters": { "supplierIds": ["t0tiu752i9bms9"] }, "includeUpcoming": true }
```

**⚠️ A past `asOfDate` is not a historical aging**
```json
{ "asOfDate": "2026-06-30" }
```
A past date does not reproduce a month-end aging: the tool ages, against that date, the invoices that still have an outstanding balance **today**, at today's balances. Invoices paid (or part-paid) since then are excluded or reduced, and invoices recorded after that date with an earlier due date are included. Do not present the result as the month-end aging.

## Example user prompts

- "Which invoices from Vaultspeed are overdue?"
- "Show me unpaid invoices older than 60 days for our Marketing suppliers"
- "Are there any invoices overdue by more than 90 days for eau de paris?"