Spend type

curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "spend_type",
    "input": { "mcc": "5411" }
  }'

const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = { decision: "spend_type", input: { mcc: "5411" } };

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();

import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {"decision": "spend_type", "input": {"mcc": "5411"}}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()

{
  "decision": "spend_type",
  "type": "choice",
  "answer": "essential",
  "probability": 0.97,
  "reasons": ["mcc_5411"],
  "abstain": false
}

# Spend type

Is spending in this category essential, discretionary or neutral? Decision id `spend_type`, a choice. Answers: `essential`, `discretionary` or `neutral`.

Built and tested, not yet deployed. Early access.

## Example

The request in cURL:

```bash
curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "spend_type",
    "input": { "mcc": "5411" }
  }'
```

The request in TypeScript:

```typescript
const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = { decision: "spend_type", input: { mcc: "5411" } };

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();
```

The request in Python:

```python
import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {"decision": "spend_type", "input": {"mcc": "5411"}}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()
```

Response: 200 OK (the probability is a stand-in)

```json
{
  "decision": "spend_type",
  "type": "choice",
  "answer": "essential",
  "probability": 0.97,
  "reasons": ["mcc_5411"],
  "abstain": false
}
```

## Input

- `mcc` (string, required): The four-digit merchant category code, as a string. Also accepts `merchantCategoryCode`.
- `merchant` (string, optional): The statement descriptor, 1 to 200 characters. Also accepts `merchantName`.

## What our engine adds

- The category’s description from our table, or “unknown” (then the reasons include `mcc_unlisted`).

## What the model is asked

- By the ISO 18245 category, is this spending essential, discretionary or neutral? Essential follows the US Bureau of Labor Statistics Consumer Expenditure Surveys’ necessities (food at home, utilities, fuel and public transit, health care, insurance, child care). Discretionary covers restaurants, apparel, entertainment, travel and the like. Neutral is everything else, such as business services, government and repair.

No rule settles this decision: every answer comes from the model.

## Reason codes

| Code | When |
| --- | --- |
| `mcc_<code>` | Always. |
| `mcc_unlisted` | The code isn’t in our table of 981 descriptions, so the model saw “unknown”. |
| `model_declined` | The model declined the question. |

## Errors

Each is a 400 with `field` naming the part at fault.

- `input.mcc is required`
- `input.mcc must be a four-digit merchant category code`
- `input.merchant must be text of 1 to 200 characters`

## Evaluation

On the eval this task is scored as agreement with a rule we wrote, not accuracy. The Understanding API hasn’t been run on our eval yet. [Evaluation](/api/docs/evaluation)

Source: /api/docs/decisions/spend-type