Skip to main content

SDK: Billing

The Billing client provides methods for managing cost items, categories, and generating financial reports.

Access it via client.billing.

Items​

// Create a billing item
const item = await client.billing.items.create({
  amount: 12.50,
  currency: "USD",
  description: "API usage - March",
  categoryId: "cat_infra",
  provider: "openai",
  date: "2026-03-01",
});

// List items
const items = await client.billing.items.list({
  category: "cat_infra",
  since: "2026-03-01",
});

// Get an item
const detail = await client.billing.items.get(item.id);

// Update an item
await client.billing.items.update(item.id, { amount: 15.00 });

// Delete an item
await client.billing.items.remove(item.id);

Categories​

// List categories
const categories = await client.billing.categories.list();

// Create a category
const cat = await client.billing.categories.create({
  name: "infrastructure",
});

Reports​

// Generate a summary report
const report = await client.billing.report({
  since: "2026-03-01",
  until: "2026-03-31",
  groupBy: "category",
});

console.log(report.total);
console.log(report.groups);

Notes​

  • Billing items support optional fields for recurring tracking (recurring, period) and external provider references (provider, providerRef).
  • Reports group by category, provider, or time period.