List subscriptions and their cost

# SaaS subscriptions — payableType=subscription

## Base query

```json
{
  "companyId": "<companyId>",
  "filters": {
    "field": "payableType",
    "operator": "=",
    "value": ["subscription"]
  },
  "pageSize": 20
}
```

→ `hasNextPage: true` if more than 20 results — paginate with the cursor to retrieve everything.

## ⚠️ spendingAmount ≠ subscription amount

This is the main pitfall on subscriptions. `spendingAmount` is described by the server as the amount in the card currency; on subscriptions it has been observed far above the billed amount, so do not treat it as the billed amount:

| Description | amount (actual) | spendingAmount (card limit) |
|-------------|---------------|---------------------------------|
| Google Apps subscription | 32.26 EUR | 4,500 EUR |
| Auto-recharge on Twilio | 14.65 EUR | 50 EUR |
| MessageBird | 27.36 EUR | 5,000 EUR |
| CRM 5 users | 276.25 USD → 257 EUR | 400 USD |

→ **NEVER sum `spendingAmount`** to calculate the total subscription cost — the result would be 10 to 200x higher than reality.
→ Always use `amount` (local currency) or `functionalAmount` (EUR) for actual amounts.

```json
// Good practice
const totalEUR = payables.reduce((sum, p) => sum + p.functionalAmount.amount / Math.pow(10, p.functionalAmount.precision), 0)

// Do not do this
const wrongTotal = payables.reduce((sum, p) => sum + p.spendingAmount.amount / ..., 0)  // can be 100x too high
```

## Currencies: majority in USD (international SaaS)

SaaS subscriptions are mostly billed in USD. Use `functionalAmount` for the EUR total:

```json
{
  "currency": "USD",
  "functionalCurrency": "EUR",
  "functionalExchangeRate": 0.9315,
  "amount": { "amount": 27625, "currency": "USD", "precision": 2 },
  "functionalAmount": { "amount": 25722, "currency": "EUR", "precision": 2 }
}
```

→ Sum `functionalAmount` to get the consolidated EUR total across all currencies.

## Filtering by period

For subscriptions in a given period:

```json
{
  "companyId": "<companyId>",
  "filters": { "operator": "and", "subfilters": [
    { "field": "payableType", "operator": "=", "value": ["subscription"] },
    { "field": "payableDate", "operator": "between", "value": { "from": "2026-01-01T00:00:00.000Z", "to": "2026-06-30T23:59:59.999Z" } }
  ] },
  "pageSize": 20
}
```

## Linking subscription → supplier

Each payable exposes `counterparty.supplierId` (no name):

```json
{ "counterparty": { "type": "supplier", "supplierId": "S1mrHIIp" } }
```

→ `get_supplier_by_id("S1mrHIIp")` to get the name (`legalName`), IBAN, VAT number.

## Aggregated analysis with spendesk_analyze_spend

For a quick total grouped by supplier:

```json
{
  "companyId": "<companyId>",
  "fromDate": "2026-01-01",
  "toDate": "2026-06-30",
  "groupBy": ["supplier"],
  "filters": { "payableTypes": ["subscription"] }
}
```

`groupBy=supplier` returns the supplier name in `key` and its ID in `id`. Raw IDs only show up in `key` when the token lacks the supplier read scope; `summary.limitations` then flags it (type `unresolved-names`).

## Useful fields

| Field | Description |
|-------|-------------|
| `description` | Subscription label |
| `amount` / `functionalAmount` | Actual amount in local currency / EUR (integer coefficient / 10^precision) |
| `spendingAmount` | Card limit — do not use for totals |
| `counterparty.supplierId` | ID of the SaaS supplier |
| `currency` | Billing currency (often USD) |
| `functionalExchangeRate` | Exchange rate applied |
| `creationDate` | Date of the payable |
| `bookkeepingStatus` | Accounting status (`exported`, `toExport`, `toPrepare`) |

## Example prompts

- "What are our SaaS subscriptions and their monthly cost?"
- "Show me the total spent on subscriptions in Q1"
- "Which subscriptions are still active?" (filter by recent `fromDate`)
- "List all subscriptions billed in USD"
- "What is the average monthly cost of our Google Apps subscription?"