Open POs approaching or exceeding budget

# Instructions

## Use case

Retrieve active POs and compare the current committed amount (`amount`) with the amount already invoiced (`billedAmount`) to track invoicing progress and spot POs with no invoicing. Budget overruns cannot be identified: the originally approved budget is not exposed, so say so rather than reporting "no overruns".

## 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 },  // current committed amount: 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` = the PO's CURRENT committed amount, not the originally approved budget: Spendesk rewrites it to `billedAmount` when the PO is closed and, depending on the entity's configuration, when an invoice exceeding it is approved
- `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` = the net-of-VAT counterpart of `amount`; present only on POs with a declared net amount (check it is present before deriving VAT or summing, never treat it as 0)

## Calculating budget consumption

```
consumption (%) = billedAmount / amount × 100
overrun         = not detectable (amount is realigned to billedAmount; the originally approved budget is not exposed)
left to invoice  = amount - billedAmount (against the current committed amount, not the originally approved budget)
```

## 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 |
| `billed` (value quoted in the tool description; `fullyBilled` does not appear there) | PO fully invoiced |

## 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

`netAmount` is the net-of-VAT counterpart of `amount`. It is returned only on POs with a declared net amount, and is realigned with `amount` only when the PO carries an initial VAT rate (otherwise it may no longer match `amount`). 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

- "Which open POs have late invoices (billingStatus = lateInvoice)?"
- "What is the consumption rate of active POs for Q3 2026?"