Skip to main content

Problem

You want to show usage dashboards, generate billing summaries, compare feature costs, or forecast monthly spend using aggregated data.

Solution

Use usage.retrieve() for daily rollups. It returns per-day breakdowns and period totals for tokens, requests, and costs.

Customer Dashboard

import { Lava } from '@lavapayments/nodejs';

const lava = new Lava();

async function getCustomerDashboard(connectionId: string) {
  const thirtyDaysAgo = new Date();
  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

  const usage = await lava.usage.retrieve({
    start: thirtyDaysAgo.toISOString(),
    connection_id: connectionId,
  });

  return {
    totalRequests: usage.totals.total_requests,
    totalTokens: usage.totals.total_usage_tokens,
    totalSpent: parseFloat(usage.totals.total_wallet_cost).toFixed(2),
    dailyData: usage.items.map((day) => ({
      date: day.date,
      requests: day.total_requests,
      tokens: day.total_usage_tokens,
      cost: parseFloat(day.total_wallet_cost),
    })),
  };
}

Revenue Report (Merchant)

async function getRevenueReport(days: number = 30) {
  const startDate = new Date();
  startDate.setDate(startDate.getDate() - days);

  const usage = await lava.usage.retrieve({
    start: startDate.toISOString(),
  });

  return {
    totalRevenue: parseFloat(usage.totals.total_merchant_cost).toFixed(2),
    totalRequests: usage.totals.total_requests,
    avgRevenuePerRequest: (
      parseFloat(usage.totals.total_merchant_cost) / usage.totals.total_requests
    ).toFixed(4),
    providerCosts: parseFloat(usage.totals.total_usage_cost).toFixed(2),
    margin: parseFloat(usage.totals.total_fee_amount).toFixed(2),
  };
}

Compare Feature Costs

Tag requests with X-Lava-Metadata-Feature headers, then compare usage across features:
async function compareFeatures(features: string[]) {
  const startDate = new Date();
  startDate.setDate(startDate.getDate() - 30);

  const results = await Promise.all(
    features.map(async (feature) => {
      const usage = await lava.usage.retrieve({
        start: startDate.toISOString(),
        metadata_filters: { feature },
      });
      return {
        feature,
        requests: usage.totals.total_requests,
        tokens: usage.totals.total_usage_tokens,
        cost: parseFloat(usage.totals.total_request_cost).toFixed(2),
      };
    })
  );

  return results.sort((a, b) => b.requests - a.requests);
}

// Example
const comparison = await compareFeatures(['chat', 'search', 'code-gen']);

Cost Forecasting

async function forecastMonthlyCost(connectionId: string) {
  const startOfMonth = new Date();
  startOfMonth.setDate(1);
  startOfMonth.setHours(0, 0, 0, 0);

  const usage = await lava.usage.retrieve({
    start: startOfMonth.toISOString(),
    connection_id: connectionId,
  });

  const daysElapsed = new Date().getDate();
  const daysInMonth = new Date(
    new Date().getFullYear(),
    new Date().getMonth() + 1,
    0
  ).getDate();

  const currentSpend = parseFloat(usage.totals.total_wallet_cost);

  return {
    currentSpend: currentSpend.toFixed(2),
    forecastedMonthly: ((currentSpend / daysElapsed) * daysInMonth).toFixed(2),
    daysRemaining: daysInMonth - daysElapsed,
  };
}

Next Steps