Card expenses above a spending threshold

# Card expenses above an amount threshold

## Pattern: compound AND filter [payableType + grossAmount]

This compound filter **works correctly** in `get_payables` (unlike the [payableType + bookkeepingStatus] filter — see skill S11 for the bug).

```json
{
  "companyId": "<companyId>",
  "filters": {
    "operator": "and",
    "subfilters": [
      {
        "field": "payableType",
        "operator": "=",
        "value": ["singleCardPurchase", "physicalCardPurchase"]
      },
      {
        "field": "grossAmount",
        "operator": ">",
        "value": 500
      }
    ]
  },
  "pageSize": 20
}
```

## ⚠️ Format of the grossAmount filter: DECIMAL value in EUR

- `value: 500` = 500 EUR — decimal format
- **Not** `50000` (integer coefficient as in the `amount` fields of the response)
- The filter applies to `functionalAmount` (EUR) — USD expenses are converted before comparison

| Desired filter | Correct value | Incorrect value |
|-----------------|-----------------|-------------------|
| > 500 EUR | `value: 500` | `value: 50000` |
| > 1,000 EUR | `value: 1000` | `value: 100000` |
| > 2,500 EUR | `value: 2500` | `value: 250000` |

Reminder: in the response, `amount.amount = 50000` with `precision: 2` = 500 EUR.

## Types of card payables

| Type | Description |
|------|-------------|
| `singleCardPurchase` | Purchase on a single-use virtual card |
| `physicalCardPurchase` | Purchase on a physical card (in-store / terminal payment) |
| `subscriptionPurchase` | Recurring purchase on a subscription card |

→ To capture ALL card purchases: include all 3 types in `value`.

## Available operators on grossAmount

| Operator | Meaning |
|-----------|---------------|
| `>` | Strictly greater than |
| `>=` | Greater than or equal |
| `<` | Strictly less than |
| `<=` | Less than or equal |
| `=` | Exactly equal |

## spendingAmount ≠ amount (pitfall)

On card expenses, `spendingAmount` is the **card limit**, not the amount actually spent:

```json
{
  "amount": { "amount": 329700, "currency": "EUR", "precision": 2 },        // 3,297 EUR actual
  "spendingAmount": { "amount": 450000, "currency": "EUR", "precision": 2 } // 4,500 EUR = card limit
}
```

→ Always use `amount` (or `functionalAmount` for multi-currency) to analyze amounts spent.
→ `spendingAmount` = authorized limit — useful only for analyzing limit usage.

## Multi-currency case

Card expenses can be in USD (e.g. foreign SaaS, subscriptions):

```json
{
  "currency": "USD",
  "functionalCurrency": "EUR",
  "functionalExchangeRate": 0.9295,
  "amount": { "amount": 98692, "currency": "USD", "precision": 2 },
  "functionalAmount": { "amount": 91827, "currency": "EUR", "precision": 2 }
}
```

→ The `grossAmount > 500` filter filters on `functionalAmount` (EUR) — an expense of 900 USD = 837 EUR is therefore included in `grossAmount > 500`.

## Useful fields for analyzing results

| Field | Usage |
|-------|-------------|
| `description` | Label of the expense |
| `amount` / `functionalAmount` | Amount (local currency / EUR) — coefficient / 10^precision |
| `counterparty.supplierId` | Supplier ID — resolve with `get_suppliers(ids=[...])` |
| `memberId` | ID of the employee who made the expense |
| `creationDate` | Date of the expense |
| `payableType` | Type of card used |
| `itemLines[].analyticalFieldAssociations` | Cost center, analytical fields |

## Adding a period filter

```json
{
  "companyId": "<companyId>",
  "filters": {
    "operator": "and",
    "subfilters": [
      { "field": "payableType", "operator": "=", "value": ["singleCardPurchase", "physicalCardPurchase"] },
      { "field": "grossAmount", "operator": ">", "value": 1000 }
    ]
  },
  "fromDate": "2026-01-01",
  "toDate": "2026-06-30",
  "pageSize": 20
}
```

## Example prompts

- "List card purchases above 1,000 EUR this quarter"
- "Which physical card expenses are above 200 EUR in June?"
- "Identify exceptional purchases (> 2,000 EUR) over the last 3 months"
- "Show all virtual card expenses > 500 EUR for March"