Unexported settlements (get_settlements)

# Settlements not exported — get_settlements

## The 3 states of a settlement

| State | Meaning | exportedAt |
|------|--------------|-----------|
| `created` | Cleared in Spendesk, not yet exported to the ERP | null |
| `exported` | Successfully sent to the ERP | ISO date |
| `failedToExport` | Export attempted but failed | null |

## Important reminder

"Cleared in Spendesk" ≠ "ready for GL export". The accounting workflow (GL export) is based on the **payables**' `bookkeepingStatus`, not on settlements. Settlements are used for **bank reconciliation** — they represent actual cash movements.

## Call — settlements not exported (created)

```json
{
  "tool": "get_settlements",
  "params": {
    "companyId": "<companyId>",
    "state": ["created"],
    "pageSize": 50
  }
}
```

## Call — export failures (failedToExport)

```json
{
  "tool": "get_settlements",
  "params": {
    "companyId": "<companyId>",
    "state": ["failedToExport"],
    "pageSize": 50
  }
}
```

## Discovery: "created" settlements dating back to 2017

On this account, settlements in `state: "created"` go back as far as **May 2017** — i.e. 9 years of unexported settlements. This can mean:
1. GL export via settlements was never enabled on this account (it uses the payables `bookkeepingStatus` export instead)
2. These old settlements predate the ERP integration setup

→ `state: "created"` doesn't necessarily mean "pending action" — it can be a permanent state for accounts without a settlements ERP integration.

## Discovery: failedToExport with statusUpdatedAt = null

`failedToExport` settlements all have `statusUpdatedAt: null`. It's impossible to know **when** the export failed from the returned data. The failures date back to 2020.

```json
{
  "exportedAt": null,
  "statusUpdatedAt": null,
  "state": "failedToExport"
}
```

→ To audit recent failures, use the date filter `clearedFrom`/`clearedTo` to isolate a period.

## Returned fields

```json
{
  "id": "uuid",
  "type": "payment | reimbursement | refund | cashReturn",
  "medium": "card | wiretransfer",
  "paidFrom": "spendeskAccount | externalAccount",
  "transactionDescription": "description",
  "clearedAt": "2024-01-15T00:00:00.000Z",
  "currency": "EUR",
  "billingCurrency": "EUR",
  "billingExchangeRate": 1,
  "state": "created | exported | failedToExport",
  "exportedAt": null,
  "statusUpdatedAt": null,
  "amount": { "amount": 21146, "currency": "EUR", "precision": 2 },
  "billingAmount": { "amount": 21146, "currency": "EUR", "precision": 2 },
  "allocations": [
    {
      "amount": { "amount": 21146, "currency": "EUR", "precision": 2 },
      "currency": "EUR",
      "payableId": "uuid-of-the-payable"
    }
  ]
}
```

## Negative amounts

A settlement can have a negative amount (`amount: -175780`) — this is a **reimbursement** or **refund** (e.g. booking cancellation, supplier credit note). The observed example: 3 MWC Barcelona refunds following the event's COVID cancellation.

## Filter by clearing period

```json
{
  "state": ["created"],
  "clearedFrom": "2026-01-01",
  "clearedTo": "2026-06-30"
}
```

→ For monthly reconciliation, always filter by `clearedFrom`/`clearedTo` — without a filter, you get the entire history.

## paidFrom: externalAccount vs spendeskAccount

| Value | Meaning |
|--------|--------------|
| `spendeskAccount` | Paid from the Spendesk wallet (cards, Spendesk transfers) |
| `externalAccount` | Paid from an external bank account (manual reimbursements) |

## Example user prompts

- "Which settlements haven't been exported to our ERP yet?"
- "Are there any export failures to fix?"
- "Give me all the movements cleared in June 2026 for bank reconciliation"