> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yoshi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Track card rewards and expiring benefits

> Use the benefits endpoints to track credit card perks, monitor usage against period limits, and surface expiring benefits before value goes to waste.

Yoshi automatically detects your credit cards and tracks the benefits they offer — statement credits, lounge access, travel perks, and more. Use the benefits endpoints to build a rewards dashboard that shows what you've used, what's remaining, and what's about to expire.

## Get your benefits summary

Fetch all active benefit periods with usage data:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import Yoshi from "@yoshi-ai/sdk";

  const yoshi = new Yoshi();

  const response = await fetch("https://api.yoshi.ai/benefits/summary", {
    headers: { Authorization: `Bearer ${process.env.YOSHI_API_KEY}` },
  });
  const { data } = await response.json();

  console.log(`Total annual value: $${(data.total_value_cents / 100).toFixed(2)}`);
  console.log(`Used: $${(data.total_used_cents / 100).toFixed(2)}`);
  console.log(`Remaining: $${(data.total_remaining_cents / 100).toFixed(2)}`);
  ```

  ```python Python theme={null}
  import httpx, os

  response = httpx.get(
      "https://api.yoshi.ai/benefits/summary",
      headers={"Authorization": f"Bearer {os.environ['YOSHI_API_KEY']}"},
  )
  data = response.json()["data"]

  print(f"Total annual value: ${data['total_value_cents'] / 100:.2f}")
  print(f"Used: ${data['total_used_cents'] / 100:.2f}")
  print(f"Remaining: ${data['total_remaining_cents'] / 100:.2f}")
  ```
</CodeGroup>

## Understand the data model

Each benefit has a **period** — a time window during which it can be used:

| Field                   | Description                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| `benefit_name`          | The perk name, e.g. "Uber Credit" or "Airline Fee Credit"                                 |
| `benefit_type`          | Category: `statement_credit`, `lounge_access`, `free_checked_bag`, etc.                   |
| `reset_cadence`         | How often the benefit resets: `calendar_month`, `calendar_year`, `card_anniversary`, etc. |
| `value_limit_cents`     | Maximum value for this period                                                             |
| `value_used_cents`      | How much has been used                                                                    |
| `value_remaining_cents` | How much is left                                                                          |
| `usage_pct`             | Usage as a percentage (0–100)                                                             |
| `days_remaining`        | Days until this period expires                                                            |
| `status`                | `available`, `partially_used`, `fully_used`, or `expired`                                 |

## Display benefits by card

Group periods by card to show a per-card breakdown:

```typescript theme={null}
const { data } = await response.json();

const byCard = {};
for (const period of data.periods) {
  const card = period.card_product_name;
  if (!byCard[card]) byCard[card] = [];
  byCard[card].push(period);
}

for (const [card, periods] of Object.entries(byCard)) {
  console.log(`\n${card}:`);
  for (const p of periods) {
    const used = (p.value_used_cents / 100).toFixed(2);
    const limit = (p.value_limit_cents / 100).toFixed(2);
    console.log(`  ${p.benefit_name}: $${used} / $${limit} (${p.usage_pct}%)`);
  }
}
```

## Surface expiring benefits

Check for benefits that are about to expire with unused value:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.yoshi.ai/benefits/expiring?days=14",
    { headers: { Authorization: `Bearer ${process.env.YOSHI_API_KEY}` } },
  );
  const { data } = await response.json();

  for (const benefit of data.expiring) {
    const remaining = (benefit.value_remaining_cents / 100).toFixed(2);
    console.log(
      `⚠️ ${benefit.benefit_name} (${benefit.card_product_name}): ` +
      `$${remaining} expires in ${benefit.days_remaining} days`
    );
  }
  ```

  ```python Python theme={null}
  response = httpx.get(
      "https://api.yoshi.ai/benefits/expiring",
      params={"days": 14},
      headers={"Authorization": f"Bearer {os.environ['YOSHI_API_KEY']}"},
  )
  data = response.json()["data"]

  for benefit in data["expiring"]:
      remaining = benefit["value_remaining_cents"] / 100
      print(
          f"⚠️ {benefit['benefit_name']} ({benefit['card_product_name']}): "
          f"${remaining:.2f} expires in {benefit['days_remaining']} days"
      )
  ```
</CodeGroup>

<Tip>
  Set `days=30` to get a monthly view, or `days=7` for urgent alerts only.
</Tip>

## Separate trackable vs always-on benefits

Some benefits like lounge access or travel insurance don't have a dollar value to track. Filter them by type:

```typescript theme={null}
const trackable = data.periods.filter((p) =>
  ["statement_credit", "membership_credit", "subscription_credit",
   "travel_bank_credit", "flight_discount"].includes(p.benefit_type)
);

const alwaysOn = data.periods.filter((p) =>
  ["lounge_access", "insurance_benefit", "status_benefit",
   "free_checked_bag", "companion_pass"].includes(p.benefit_type)
);
```

Display trackable benefits with progress bars and dollar amounts. Show always-on benefits as a simple checklist of perks your cards provide.

## Calculate annual fee ROI

Combine benefit usage with your card's annual fee to show return on investment:

```typescript theme={null}
const annualFee = 695_00; // $695.00 in cents
const totalUsed = data.total_used_cents;
const roi = ((totalUsed / annualFee) * 100).toFixed(0);

console.log(`Annual fee: $${(annualFee / 100).toFixed(2)}`);
console.log(`Benefits used: $${(totalUsed / 100).toFixed(2)}`);
console.log(`ROI: ${roi}%`);
```

## What's next

<CardGroup cols={2}>
  <Card title="Data models" icon="database" href="/concepts/data-models">
    Understand how financial data is structured.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks/overview">
    Get notified when new transactions match benefits.
  </Card>
</CardGroup>