Usage-based billing

import { betterIam } from 'better-iam';
import { postgresAdapter } from 'better-iam/adapter-postgres';

export const iam = betterIam({
  database: postgresAdapter({ connectionString: process.env.DATABASE_URL! }),
  secret: process.env.BETTER_IAM_SECRET,
  baseURL: process.env.BETTER_IAM_BASE_URL,
  billing: {
    currency: 'EUR',
    timeZone: 'Europe/Berlin',
    paymentTermsDays: 30,
    statementPrefix: 'INV', // invoice numbers read INV-202611-0001
    issuer: {
      name: 'Acme Cloud Ltd',
      address: '1 Main Street, London',
      taxId: 'GB123456789',
      paymentInstructions: 'Pay by card from the link in the invoice email, or by bank transfer to IBAN ...',
    },
    autoFinalize: true,
  },
});

import { iam } from '../src/iam.js';

const root = { token: process.env.ROOT_TOKEN! };
const rootTenantId = process.env.ROOT_TENANT_ID!;

await iam.api.billing.createMeter(root, {
  tenantId: rootTenantId,
  key: 'api-calls',
  name: 'API calls',
  unit: 'request',
  aggregation: 'sum',
});

await iam.api.billing.setPrice(root, {
  tenantId: rootTenantId,
  meter: 'api-calls',
  price: {
    model: 'graduated',
    includedQuantity: 10_000,
    tiers: [
      { upTo: 1_000_000, unitAmount: 0.0004 },
      { upTo: null, unitAmount: 0.0002 },
    ],
  },
});

// A negotiated price for one organization and its projects, from December.
await iam.api.billing.setPrice(root, {
  tenantId: rootTenantId,
  meter: 'api-calls',
  targetTenantId: process.env.ACME_TENANT_ID!,
  effectiveFrom: '2026-12',
  price: { model: 'per-unit', unitAmount: 0.0003 },
  note: 'Enterprise agreement',
});

// What would 2.5 million calls cost Acme this month?
const quote = await iam.api.billing.quote(root, {
  tenantId: process.env.ACME_TENANT_ID!,
  meter: 'api-calls',
  quantity: 2_500_000,
});
console.log(quote);

await iam.api.billing.createPlan(root, {
  tenantId: rootTenantId,
  key: 'pro',
  name: 'Pro',
  selfServe: true,
  trialDays: 14,
  items: [
    { id: 'platform', kind: 'fee', name: 'Platform fee', amount: 99 },
    { id: 'seats', kind: 'seat', name: 'Seats', unitAmount: 12, includedSeats: 3 },
  ],
});

const orgAdmin = { token: process.env.ACME_ADMIN_TOKEN! };
const { subscription } = await iam.api.billing.subscribe(orgAdmin, {
  tenantId: process.env.ACME_TENANT_ID!,
  plan: 'pro',
  seats: 8,
});
console.log(subscription.id);

import { IamError } from 'better-iam';
import { iam } from './iam.js';

type Handler = (request: Request) => Promise<Response>;

/** Wraps an API handler: authenticates the caller, refuses spent budgets, and records one api-calls event. */
export function metered(endpoint: string, handler: Handler): Handler {
  return async (request) => {
    const { identity, session } = await iam.authenticate({ headers: request.headers });
    const requestId = request.headers.get('x-request-id') ?? crypto.randomUUID();
    try {
      await iam.billing.record({
        tenantId: session.tenantId,
        meter: 'api-calls',
        quantity: 1,
        identityId: identity.id,
        tags: { endpoint },
        idempotencyKey: requestId,
        enforceBudgets: true,
      });
    } catch (error) {
      if (error instanceof IamError && error.code === 'SPEND_LIMIT_REACHED')
        return Response.json({ error: 'Monthly budget reached' }, { status: 402 });
      throw error;
    }
    return handler(request);
  };
}

import { metered } from '../metering.js';

export const POST = metered('search', async (request) => {
  const { query } = await request.json();
  return Response.json({ results: await runSearch(query) });
});

async function runSearch(query: string) {
  return [{ id: 'doc-1', title: `Result for ${query}` }];
}

import { iam } from '../src/iam.js';

const orgAdmin = { token: process.env.ACME_ADMIN_TOKEN! };
const tenantId = process.env.ACME_TENANT_ID!;

await iam.api.billing.createBudget(orgAdmin, {
  tenantId,
  name: 'Acme monthly API spend',
  amount: 2_000,
  period: 'month',
  meters: ['api-calls'],
  thresholds: [50, 80, 100],
  forecastAlerts: true,
  notify: { owners: true, emails: ['finance@acme.test'] },
  enforce: true,
});

for (const budget of await iam.api.billing.listBudgets(orgAdmin, { tenantId })) {
  console.log(budget.name, `${budget.percent}%`, budget.exceeded ? 'exceeded' : 'within budget');
}

# Daily
better-iam billing-close --config better-iam.config.mjs
better-iam billing-reminders --config better-iam.config.mjs
better-iam billing-anomalies --config better-iam.config.mjs
# Hourly
better-iam billing-alerts --config better-iam.config.mjs

import Stripe from 'stripe';
import { iam } from '../iam.js';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const root = { token: process.env.ROOT_TOKEN! };

export async function createPaymentIntents(tenantId: string) {
  const invoices = await iam.api.billing.listStatements(root, { tenantId, status: 'finalized' });
  for (const invoice of invoices) {
    if (invoice.amountDueMicros <= 0) continue;
    await stripe.paymentIntents.create(
      {
        amount: Math.round(invoice.amountDueMicros / 10_000), // micros to cents
        currency: invoice.currency.toLowerCase(),
        metadata: { invoiceNumber: invoice.number },
      },
      { idempotencyKey: `invoice-${invoice.number}` },
    );
  }
}

import Stripe from 'stripe';
import { iam } from '../iam.js';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(request: Request): Promise<Response> {
  const event = stripe.webhooks.constructEvent(
    await request.text(),
    request.headers.get('stripe-signature') ?? '',
    process.env.STRIPE_WEBHOOK_SECRET!,
  );
  if (event.type === 'payment_intent.succeeded') {
    const intent = event.data.object;
    const number = intent.metadata.invoiceNumber;
    if (number) {
      await iam.billing.recordPayment({
        number,
        amount: intent.amount_received / 100, // cents to currency units
        method: 'card',
        idempotencyKey: intent.id,
      });
    }
  }
  return new Response(null, { status: 200 });
}

import { iam } from '../src/iam.js';

const root = { token: process.env.ROOT_TOKEN! };

await iam.api.billing.createCreditNote(root, {
  tenantId: process.env.ACME_TENANT_ID!,
  statementId: process.env.STATEMENT_ID!,
  amount: 25,
  reason: 'product_unsatisfactory',
  memo: 'Latency incident on 3 November',
});