Skip to main content
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)}`);

​
Understand the data model

Each benefit has a period — a time window during which it can be used:
FieldDescription
benefit_nameThe perk name, e.g. “Uber Credit” or “Airline Fee Credit”
benefit_typeCategory: statement_credit, lounge_access, free_checked_bag, etc.
reset_cadenceHow often the benefit resets: calendar_month, calendar_year, card_anniversary, etc.
value_limit_centsMaximum value for this period
value_used_centsHow much has been used
value_remaining_centsHow much is left
usage_pctUsage as a percentage (0–100)
days_remainingDays until this period expires
statusavailable, 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`
  );
}
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}%`);

​
What’s next

Data models

Understand how financial data is structured.

Webhooks

Get notified when new transactions match benefits.
Last modified on April 17, 2026