Measure supplier payment times

# Supplier payment times

## Purpose

Measure how many days supplier invoices actually take to be paid, and whether they are paid before or after their due date. Spot suppliers consistently paid late, and those paid well before the due date.

## Where the payment date comes from

An expense carries **no** payment date. The real date is on the **settlement**: `clearedAt`. The accounting export date is not a payment date and must not be used as a substitute.

The link goes this way: settlement → `allocations[].payableId` → expense.

## Step 1 — List the period's payments

State the exact period (for example the last 3 months).

```json
{
  "tool": "get_settlements",
  "params": {
    "clearedFrom": "2026-07-01T00:00:00.000Z", "clearedTo": "2026-09-30T23:59:59.999Z",
    "types": ["payment"], "pageSize": 1000
  }
}
```

`types: ["payment"]` keeps payments to suppliers and leaves out employee reimbursements, advances and refunds. Page with `page` while `hasNextPage` is `true`.

For each settlement, note `clearedAt`, `billingAmount`, and the `payableId` of its `allocations`. A settlement with no allocation cannot be tied to an invoice: count it separately.

## Step 2 — Read the invoice that was paid

```json
{ "tool": "get_payable_by_id", "params": { "id": "<payableId>" } }
```

Read `payableDate` (invoice date), `invoiceDueDate` (due date, can be missing), `payableType` and `counterparty.name`. Keep only `invoicePurchase`.

One call per invoice: bound the period to keep the volume reasonable, and say how many payments were analysed.

## Step 3 — Calculate

For each payment:

- **payment time** = `clearedAt` − `payableDate`, in days;
- **gap to due date** = `clearedAt` − `invoiceDueDate`: positive = paid late, negative = paid early. Cannot be computed without a due date.

An invoice paid in several instalments has several settlements: take the last one's date for the payment time, and say so.

Then, overall:

- average payment time, and the amount-weighted average;
- share of invoices paid after the due date;
- per supplier: average time, number of invoices, average gap to due date.

## Report

```
Payment times — settlements from <date> to <date> (N payments analysed)

Average time: X days (amount-weighted: Y days)
Paid after the due date: N out of M (Z%)

| Supplier | Invoices | Average time | Average gap to due date |

🔴 Repeatedly paid late: …
💡 Paid well before the due date on large amounts: …
```

## Limits to state

- This measures invoice → payment. It is not DPO in the accounting sense (payables relative to purchases): do not call it that without saying so.
- Contractual payment terms are not in Spendesk: only the due date entered on the invoice serves as reference.
- Payments made outside Spendesk do not appear.

## Observed result (demo account, 5 October 2026)

Two payments in September 2026 for EUR 10,613.50. One settled on 16 September an invoice dated 12 September and due 12 October: paid 4 days after issue, i.e. 26 days before the due date.

## Example prompts
- "How many days do we take on average to pay our suppliers?"
- "Which suppliers do we consistently pay after the due date?"
- "Are we paying some suppliers well before the due date?"