Billing Rail

Usage metering and invoicing endpoints.

Overview

The Billing rail provides:

• Usage metering
• Invoice generation
• Payment processing
• Subscription management

Integrated with Stripe for payment processing.

Endpoints

Record Usage

POST /v1/billing/usage

const usage = await iof.billing.recordUsage({
  workspaceId: "ws_123",
  metric: "api_calls",
  quantity: 1000,
  timestamp: new Date(),
});

Get Usage

GET /v1/billing/usage

const usage = await iof.billing.getUsage({
  workspaceId: "ws_123",
  metric: "api_calls",
  startDate: "2024-01-01",
  endDate: "2024-01-31",
});

Response:

{
  "metric": "api_calls",
  "total": 45000,
  "breakdown": [
    { "date": "2024-01-15", "quantity": 1500 },
    { "date": "2024-01-16", "quantity": 2000 }
  ]
}

Create Invoice

POST /v1/billing/invoices

const invoice = await iof.billing.createInvoice({
  workspaceId: "ws_123",
  period: {
    start: "2024-01-01",
    end: "2024-01-31",
  },
});

Response:

{
  "id": "inv_abc",
  "workspaceId": "ws_123",
  "status": "draft",
  "subtotal": 500,
  "tax": 50,
  "total": 550,
  "lineItems": [
    { "description": "API Calls (45,000)", "amount": 450 },
    { "description": "Contracts (100)", "amount": 50 }
  ]
}

Get Invoice

GET /v1/billing/invoices/:id

const invoice = await iof.billing.getInvoice("inv_abc");

Pay Invoice

POST /v1/billing/invoices/:id/pay

const payment = await iof.billing.payInvoice("inv_abc", {
  paymentMethod: "pm_card_123",
});

Metrics

Metric	Description	Unit
api_calls	API requests	Count
contracts	Contracts created	Count
kyc_checks	KYC verifications	Count
storage	Data storage	GB

Invoice Status

Status	Description
draft	Not yet sent
open	Awaiting payment
paid	Successfully paid
void	Cancelled
overdue	Past due date

Webhooks

Event	Description
billing.usage.recorded	Usage recorded
billing.invoice.created	Invoice created
billing.invoice.paid	Invoice paid
billing.invoice.overdue	Invoice overdue

Next Steps

• Ledger Rail - Accounting entries
• API Overview - All endpoints