Open POs approaching or exceeding budget

# Instructions

## Use case

Retrieve active POs and compare the approved budget (`amount`) with the amount already invoiced (`billedAmount`) to identify overruns or POs with no invoicing.

## Basic call

```json
{
  "companyId": "<COMPANY_ID>",
  "status": ["open"],
  "pageSize": 100
}
```

Note: `status` is an **array** of strings (unlike `list_cards.status` which is a plain string).

## Financial fields of a PO

```json
{
  "amount":          { "amount": 2126789, "currency": "USD", "precision": 2 },  // approved budget: 21,267.89 USD
  "billedAmount":    { "amount": 1063384, "currency": "USD", "precision": 2 },  // total invoiced: 10,633.84 USD
  "deliveredAmount": { "amount": 0,       "currency": "USD", "precision": 2 }   // confirmed delivered amount
}
```

- `amount` = approved budget ceiling
- `billedAmount` = sum of attached invoices (all, including credit notes)
- `deliveredAmount` = amount whose receipt has been confirmed (often 0 if delivery tracking isn't used)
- `netAmount` = `billedAmount` - credit notes (documented in the tool description but **absent from the response** — calculate manually if needed)

## Calculating budget consumption

```
consumption (%) = billedAmount / amount × 100
overrun         = billedAmount > amount
remaining budget = amount - billedAmount
```

## billingStatus — invoicing status

| Value | Meaning |
|--------|---------------|
| `lateInvoice` | PO open but no invoice received (or PO late on invoicing) |
| `partiallyBilled` | Partial invoicing — invoices exist but < total budget |
| `fullyBilled` | Budget fully consumed by invoices |

## Pitfall 1 — "open" POs can have a past endDate

A PO stays in `status: "open"` even after its end date. The MCP does not automatically close expired POs. On the demo account, all open POs have an `endDate` in 2022 or 2023 — they've been open for 2-3 years.

```
PO-14 (Oracle subscription)  : endDate 2022-07-31 → still open in 2026
PO-22 (Coworking Lyon)     : endDate 2022-12-31 → still open in 2026
PO-82 (Banking offsite)    : endDate 2022-11-18 → still open in 2026
```

→ Always filter on `endDate` if you only want POs currently valid:
```json
{
  "status": ["open"],
  "endDateFrom": "2026-07-01"
}
```

## Pitfall 2 — netAmount absent from the response

The tool description mentions `netAmount = billedAmount - creditNotes` but this field **is not returned** in the API response. If credit notes have been issued, `billedAmount` already includes them. There is no separate field to distinguish gross and net amounts.

## Pitfall 3 — Multi-currency across POs

POs can be in EUR or USD (or any other currency). Do not sum `amount` across currencies to get a consolidated total budget. The `amount`, `billedAmount`, `deliveredAmount` fields are always in the PO's currency.

## billingOverDeliveryStatus

Field present on each PO: `"none"` / `"overBilled"` / `"underBilled"` — lets you spot at a glance POs where invoicing exceeds delivery. On the demo account: all set to `"none"`.

## deliveryStatus

| Value | Meaning |
|--------|---------------|
| `noDeliveryExpected` | Delivery receipt is not tracked for this PO |
| `partiallyDelivered` | Delivery partially confirmed |
| `fullyDelivered` | Delivery fully confirmed |

## invoices[] — linked invoices

Each PO exposes an `invoices[]` array with each associated invoice:
```json
{
  "invoiceRequestId": "...",
  "invoiceNumber": "INV6342",
  "amount": { "amount": 533578, "currency": "USD", "precision": 2 },
  "status": "paid",
  "payableId": "697e453d-..."  // can be null if the requestId→payableId mapping failed
}
```

To get the accounting detail of an invoice: `get_payable_by_id(payableId)` — see [[s20-detail-complet-facture]].

## Example user prompts

- "Show me the POs whose invoicing exceeds the approved budget"
- "Which open POs have late invoices (billingStatus = lateInvoice)?"
- "What is the consumption rate of active POs for Q3 2026?"