Invoice payment lifecycle tracker

# Tracking invoice payment status

## Purpose

Provide a clear, instant view of invoices according to their progress in the payment cycle: approved but not yet exported, scheduled for payment, exported, settled. Typical use case: **daily cash flow planning**, verification before accounting export, or answering "where does [supplier]'s invoice stand?"

---

## MCP scope — what is visible

> ⚠️ The Spendesk MCP gives access to invoices **starting from the "approved" stage**. Invoices still under validation (inbox, review, pending_approval) are not accessible.

| Stage | Accessible? | Via which tool |
|-------|:----------:|---------------|
| Submitted / awaiting approval | ❌ | Not available in the MCP |
| **Approved — awaiting payment** | ✅ | `get_payables` (status=approved) |
| **Overdue — payment due** | ✅ | `spendesk_get_due_invoices` |
| **Exported / scheduled** | ✅ | `get_payables` (status=exported/scheduled) |
| **Settled** | ✅ | `get_settlements` |

---

## Instructions

### Step 1 — Identify the precise question

Determine what the user wants:
- **Global view**: all invoices awaiting payment → go to Step 2
- **Status of a specific invoice**: invoice from a specific supplier → go to Step 3
- **Cash flow**: approved invoices to pay today/this week → go to Step 4
- **Export verification**: which invoices have already been exported → go to Step 5

---

### Step 2 — Global view of invoices awaiting payment

```
Call get_payables with:
  - limit: 50 (maximum recommended to avoid timeouts)
  - If possible, filter by status to only retrieve post-approval invoices

For each returned invoice, note:
  - id, supplierName (or supplierId → resolve via get_supplier_by_id if needed)
  - amount + currency
  - status (approved / scheduled / exported / paid)
  - dueDate or paymentDate if available
  - createdAt

Then call spendesk_get_due_invoices to retrieve invoices whose payment is overdue.

Build a summary table grouped by status:
```

**Expected response format:**

```
📋 Invoices awaiting payment — [today's date]

✅ APPROVED — AWAITING EXPORT ([N] invoices, [total] €)
┌─────────────────────┬──────────┬──────────┬─────────────┐
│ Supplier            │ Amount   │ Status   │ Date        │
├─────────────────────┼──────────┼──────────┼─────────────┤
│ Supplier A          │ X,XXX €  │ approved │ DD/MM/YYYY  │
│ Supplier B          │ X,XXX €  │ approved │ DD/MM/YYYY  │
└─────────────────────┴──────────┴──────────┴─────────────┘

⏰ OVERDUE — LATE PAYMENT ([N] invoices, [total] €)
[list of invoices whose due date has passed]

📤 SCHEDULED / IN PROGRESS ([N] invoices, [total] €)
[list of invoices with payment scheduled or processing]
```

---

### Step 3 — Status of a specific supplier invoice

```
Use get_payables with a filter on the supplier name or amount.
If you have a supplierId, use it directly.
If you only have the name, first call get_suppliers to find the ID.

Return the full invoice detail:
```

**Expected response format:**

```
📄 [Supplier] invoice — Detailed status

Supplier: [name]
Amount: [X,XXX €]
Creation date: [DD/MM/YYYY]
Due date: [DD/MM/YYYY] (or "not specified")
Current status: [status]

📍 Position in the cycle:
[Submitted] → [Under approval] → ✅ [Approved] → [Scheduled] → [Exported] → [Settled]
                                     ↑ current position

ℹ️ [Explanation of the status in plain language]
```

---

### Step 4 — Cash flow: approved invoices to pay

**Bragi use case** — skill to run daily to feed cash flow planning.

```
1. Call get_payables to retrieve all approved invoices
   - Limit: 50 per call (if you think you have more than 50 invoices, make several calls
     with date filters to segment)
   - Sort by dueDate or amount

2. Call spendesk_get_due_invoices to identify overdue invoices as a priority

3. If you need to compare with the previous day (delta mode):
   - Compare the IDs returned today with those from the last run
   - "New" = in today's list but not yesterday's
   - "Removed" = in yesterday's list but no longer today's (= exported/paid)

Build the cash flow report:
```

**Expected response format:**

```
💰 Cash flow — Invoices to pay — [today's date]

🆕 NEW approved invoices since yesterday: [N]
[list with amount and supplier]

📤 TOTAL to pay today:
• Overdue invoices: [N] — [total] €  ← pay as a priority
• Approved invoices (not overdue): [N] — [total] €
• GRAND TOTAL: [N] invoices — [TOTAL] €

✅ REMOVED since yesterday (exported/paid): [N] invoices — [total] €

---
💡 Tip: [e.g. "3 Stripe invoices overdue for +7 days — handle as a priority"]
```

---

### Step 5 — Verification before accounting export

```
1. Call get_settlements to retrieve recent settlements (last 48 hours or since the
   last close)
2. Call get_payables to cross-reference with "exported" or "paid" invoices
3. Identify approved invoices NOT yet in settlements = to be exported

Build the checklist:
```

**Expected response format:**

```
✅ Export verification — [date]

ALREADY EXPORTED/SETTLED: [N] invoices
[quick list: supplier + amount + settlement date]

🔴 APPROVED BUT NOT YET EXPORTED: [N] invoices
[list: supplier + amount + approval date]
→ These invoices are ready to export to your accounting tool.

⚠️ OUT OF MCP SCOPE (invoices under approval):
The MCP cannot see invoices still under validation — check Spendesk directly
for invoices in inbox/review.
```

---

## Important limitations to communicate

1. **Pre-approval invoices invisible** — If the user is looking for a recently submitted invoice that hasn't been approved yet, it will not appear in the MCP results. State this explicitly.

2. **50-invoice limit per call** — At month-end with many invoices, segment by period (week by week) to stay under the limit.

3. **Approval from Claude not possible** (for now) — If the user asks to approve an invoice, explain that write operations are coming in Q3 2026.

---

## Example prompts

- "Which invoices are approved and awaiting payment?"
- "Where does [supplier]'s invoice stand?"
- "Show me the invoices to pay this week for my cash flow"
- "Which invoices have been settled since Monday?"
- "Are there overdue invoices not yet paid?"
- "New approved invoices since yesterday?" (delta mode — automated skill)