Build with BillAI

How BillAI Works

BillAI is a microservices-based billing and metering platform that handles the entire billing lifecycle for B2B SaaS companies. At its core, BillAI ingests usage data from your application, aggregates it into billable metrics, applies sophisticated pricing models, generates invoices, and processes payments — all automatically.

Core Architecture

Key Infrastructure

API Quickstart

All API requests require authentication. BillAI supports two authentication methods.

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "admin@yourcompany.com",
  "password": "your-password"
}

API keys are provisioned per-company through
the Admin Service and are cached in Dragonfly
for fast lookups.

Response Format

{
  "success": true,
  "error": null,
  "payload": [ ... ],
  "input": { ... }
}

{
  "success": false,
  "error": {
    "code": "VAL_001",
    "msg": "Validation error: field 'name' is required"
  },
  "payload": null,
  "input": { ... }
}

Your First API Call

GET /health

Response:
{
  "status": "healthy",
  "dependencies": {
    "database": "ok",
    "cache": "ok",
    "message_broker": "ok"
  }
}

Plan Your Billing Architecture

Before integrating BillAI, plan how your billing model maps to BillAI's core concepts. Walk through each building block.

Billing Models

BillAI supports multiple billing models that can be combined within a single plan.

Invoicing

BillAI generates invoices automatically at the end of each billing period.

Invoice Lifecycle

Draft ──> Issued ──> Paid
             |
             ├──> Partially Paid
             ├──> Overdue
             ├──> Written Off
             └──> Canceled

What Goes Into an Invoice

• Line items — Aggregated charges from the subscription period (flat fees + usage charges)
• Tax calculation — Automatic tax computation via Avalara based on product tax classification and customer location
• Credits — Any credit memos or adjustments applied
• Accounting entries — Every invoice posts double-entry records to TigerBeetle

Credit Memos

POST /api/v1/invoicing/credit-memos
Content-Type: application/json
Authorization: Bearer <token>

{
  "invoice_id": "inv_abc",
  "amount": 25.00,
  "reason": "Service disruption credit"
}

Payments

BillAI integrates with multiple payment processors out of the box. Payment processing is abstracted behind a unified interface.

Spend Controls

Enforce spending limits to prevent unexpected charges and provide cost transparency to your customers.

• Set budget limits per customer or subscription
• Automatic suspension when limits are exceeded
• Automatic resumption when limits are increased or reset
• Real-time spend tracking via TigerBeetle
• Alert configuration for approaching limits

POST /api/v1/spend-control/limits
Content-Type: application/json
Authorization: Bearer <token>

{
  "customer_id": "cust_abc",
  "subscription_id": "sub_xyz",
  "monthly_limit": 5000.00,
  "alert_thresholds": [50, 80, 95],
  "action_on_exceed": "suspend"
}

Customer Portal

BillAI includes a built-in customer portal API that you can integrate into your application to give customers self-service access.

• Profile management — View and update billing profile
• Subscriptions — View active subscriptions and plan details
• Invoices — View, download, and track invoice history
• Usage dashboards — Real-time usage visibility
• Payment history — View past payments and receipts
• Credit balances — Check remaining credits
• Contracts — View active contracts and agreements

The Customer Portal uses a separate JWT authentication realm, keeping customer access isolated from admin operations.

POST /api/v1/portal/auth/login
Content-Type: application/json

{
  "email": "user@globex.com",
  "password": "customer-password"
}

Administration

The BillAI Admin Service provides operational tools for managing your billing platform.

• Health monitoring — Real-time system health across all services
• Tenant management — Multi-tenant administration
• Global search — Search across customers, subscriptions, invoices
• Orphan event management — View and recover events outside billing periods
• Audit logging — Complete audit trail with configurable retention
• User management — Admin user and role management with RBAC
• Invoice simulation — Run what-if scenarios to preview billing outcomes

Invoice Simulation

POST /api/v1/admin/simulation/invoice
Content-Type: application/json
Authorization: Bearer <token>

{
  "customer_id": "cust_abc",
  "plan_id": "plan_pro",
  "period_start": "2026-02-01T00:00:00Z",
  "period_end": "2026-03-01T00:00:00Z",
  "simulated_events": [
    { "event_type": "api_call", "count": 150000 },
    { "event_type": "storage", "gb": 250 }
  ]
}

Notifications

BillAI sends notifications through multiple channels. Notifications are dispatched asynchronously through AWS SQS and Lambda for reliable delivery.

Orchestration & Reliability

BillAI uses an internal orchestration engine to coordinate long-running workflows (renewals, invoice generation, payment processing) without tight coupling between services.

How It Works

1. 1.A service submits a task with a target URL, payload, and scheduled time
2. 2.The Orchestrator holds the task until it's due
3. 3.At the scheduled time, the Orchestrator sends an HTTP POST to the target service
4. 4.The target service processes the work asynchronously and sends a callback
5. 5.The Orchestrator triggers the next step in the workflow chain

Reliability Features

• Outbox pattern — Tasks are persisted to the database before dispatch, ensuring no tasks are lost
• Retry with exponential backoff — Failed tasks are retried automatically
• Stalled task detection — Alerts are sent when tasks remain unprocessed
• Dependency chains — Tasks can be chained so downstream work only starts after upstream tasks complete

Integration Checklist

Use this checklist to track your BillAI integration progress.

Reference

Service Ports

Error Codes