Track card rewards and expiring benefits

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:

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)}`);

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}")

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:

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:

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`
  );
}

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"
    )

Set days=30 to get a monthly view, or days=7 for urgent alerts only.

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:

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:

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}%`);

Getting Started

Reference

SDKs

Concepts

Webhooks

Use Cases

Tools

Resources

Track card rewards and expiring benefits

Get your benefits summary

Understand the data model

Display benefits by card

Surface expiring benefits

Separate trackable vs always-on benefits

Calculate annual fee ROI

What’s next

Data models

Webhooks

​Get your benefits summary

​Understand the data model

​Display benefits by card

​Surface expiring benefits

​Separate trackable vs always-on benefits

​Calculate annual fee ROI

​What’s next

Data models

Webhooks

Get your benefits summary

Understand the data model

Display benefits by card

Surface expiring benefits

Separate trackable vs always-on benefits

Calculate annual fee ROI

What’s next