// open source billing infrastructure

bxb

Usage-based metering and billing for SaaS. Self-hosted on your infra. Any pricing model. Python/FastAPI. 100% test coverage.

> Demo / API ? Docs GitHub
~/bxb
$ curl -X POST /v1/events
-H "Authorization: Bearer sk_live_..."
-d '
"customer_id": "cus_9a4b2",
"code": "api_requests",
"properties": { "tokens": 1847 }
'
200 event ingested • 3ms
WIP

Currently being built with AI. Join the waitlist to get notified when we launch.

// tech stack

Built on proven infrastructure

Every component chosen for production reliability, async performance, and developer experience.

Language Python 3.12+ Modern async, type hints
Framework FastAPI Async, OpenAPI native
S
ORM SQLAlchemy 2.0 Async support
Main Database PostgreSQL Primary data store
Streamed Events ClickHouse Columnar analytics engine
Validation Pydantic v2 Rust-powered data validation
Migrations Alembic Schema version control
Background Jobs arq Redis-based async workers
Package Manager uv Blazing-fast Python toolchain
01

Bill by Usage

Pure pay-as-you-go. Define a metric, create a plan with usage charges, subscribe a customer, and start sending events. bxb meters everything and generates invoices automatically.

1 Define a billable metric
POST /v1/billable_metrics 
$ curl -X POST https://api.boxbilling.com/v1/billable_metrics \
  -H "Authorization: Bearer $BXB_API_KEY" \
  -d '{
    "name": "API Requests",
    "code": "api_requests",
    "aggregation_type": "sum",
    "field_name": "tokens"
  }'
201 metric created
2 Create a usage-only plan
POST /v1/plans 
$ curl -X POST https://api.boxbilling.com/v1/plans \
  -H "Authorization: Bearer $BXB_API_KEY" \
  -d '{
    "name": "Pay As You Go",
    "code": "payg",
    "interval": "monthly",
    "amount_cents": 0,
    "charges": [{
      "billable_metric_code": "api_requests",
      "charge_model": "standard",
      "properties": { "amount": "0.001" }
    }]
  }'
201 plan created — $0.001 per token
3 Subscribe a customer
POST /v1/subscriptions 
$ curl -X POST https://api.boxbilling.com/v1/subscriptions \
  -H "Authorization: Bearer $BXB_API_KEY" \
  -d '{
    "customer_id": "cus_9a4b2",
    "plan_code": "payg"
  }'
201 subscription active
4 Send usage events
POST /v1/events 
$ curl -X POST https://api.boxbilling.com/v1/events \
  -H "Authorization: Bearer $BXB_API_KEY" \
  -d '{
    "transaction_id": "txn_8f3a1",
    "customer_id": "cus_9a4b2",
    "code": "api_requests",
    "properties": { "tokens": 2340 }
  }'
200 event ingested — 3ms
5 Invoice generated at end of billing period
GET /v1/customers/cus_9a4b2/invoices 
$ curl https://api.boxbilling.com/v1/customers/cus_9a4b2/invoices \
  -H "Authorization: Bearer $BXB_API_KEY"
200 
{
  "total_amount_cents": 2340,    // 2,340,000 tokens × $0.001
  "currency": "USD",
  "status": "finalized"
}
02

Bill by Subscription + Usage

Charge a recurring base fee plus metered usage on top. The most common model for SaaS — a monthly platform fee with overage charges when usage exceeds included amounts.

1 Create a hybrid plan — $49/mo base + usage
POST /v1/plans 
$ curl -X POST https://api.boxbilling.com/v1/plans \
  -H "Authorization: Bearer $BXB_API_KEY" \
  -d '{
    "name": "Pro",
    "code": "pro",
    "interval": "monthly",
    "amount_cents": 4900,
    "charges": [{
      "billable_metric_code": "api_requests",
      "charge_model": "graduated",
      "properties": {
        "graduated_ranges": [
          { "from": 0, "to": 100000, "per_unit": "0" },
          { "from": 100001, "to": null, "per_unit": "0.0005" }
        ]
      }
    }]
  }'
201 plan created — $49/mo + $0.0005/token over 100k
2 Subscribe and send events (same as before)
POST /v1/subscriptions 
$ curl -X POST https://api.boxbilling.com/v1/subscriptions \
  -H "Authorization: Bearer $BXB_API_KEY" \
  -d '{ "customer_id": "cus_9a4b2", "plan_code": "pro" }'
201 subscription active 
# Send events exactly as before — bxb tracks everything
$ curl -X POST https://api.boxbilling.com/v1/events \
  -d '{ "customer_id": "cus_9a4b2", "code": "api_requests", "properties": { "tokens": 250000 } }'
200 event ingested
3 Invoice: base fee + overage
GET /v1/customers/cus_9a4b2/invoices
200 
{
  "fees": [
    { "type": "subscription", "amount_cents": 4900 },
    { "type": "charge",        "amount_cents": 7500,
      "units": "150k tokens over 100k free tier" }
  ],
  "total_amount_cents": 12400,   // $49 + $75 overage
  "currency": "USD"
}
03

Bill by Subscription + Usage + Free Trial + Coupon

The full picture. Start with a free trial, apply a coupon code for a discount, charge a subscription base, and meter usage on top. All managed through the API.

1 Create a coupon — 20% off for 3 months
POST /v1/coupons 
$ curl -X POST https://api.boxbilling.com/v1/coupons \
  -H "Authorization: Bearer $BXB_API_KEY" \
  -d '{
    "name": "Launch20",
    "code": "LAUNCH20",
    "discount_type": "percentage",
    "discount_value": 20,
    "duration": "recurring",
    "duration_in_months": 3
  }'
201 coupon created
2 Apply coupon to customer
POST /v1/applied_coupons 
$ curl -X POST https://api.boxbilling.com/v1/applied_coupons \
  -H "Authorization: Bearer $BXB_API_KEY" \
  -d '{
    "customer_id": "cus_9a4b2",
    "coupon_code": "LAUNCH20"
  }'
201 coupon applied — 20% off for 3 months
3 Subscribe with a 14-day free trial
POST /v1/subscriptions 
$ curl -X POST https://api.boxbilling.com/v1/subscriptions \
  -H "Authorization: Bearer $BXB_API_KEY" \
  -d '{
    "customer_id": "cus_9a4b2",
    "plan_code": "pro",
    "trial_period_days": 14
  }'
201 subscription active — trial ends 2025-02-24 
# Customer can use the product during trial.
# Usage events are tracked but not billed until trial ends.
4 First invoice after trial — with coupon applied
GET /v1/customers/cus_9a4b2/invoices
200 
{
  "fees": [
    { "type": "subscription", "amount_cents": 4900 },
    { "type": "charge",        "amount_cents": 7500 }
  ],
  "subtotal_cents": 12400,
  "coupons": [
    { "code": "LAUNCH20", "discount_cents": -2480 }
  ],
  "total_amount_cents": 9920,    // $124 - 20% = $99.20
  "currency": "USD"
}
// integrations

Push billing data to your reporting stack

Automatic, zero-config syncing. bxb pushes customers, subscriptions, invoices, and revenue events to the analytics tools your finance team already uses.

ChartMogul

Subscription analytics and revenue reporting. Customer, subscription, and invoice data is pushed to ChartMogul automatically for MRR, churn, LTV, and cohort analysis.

  • ✓ Customers synced on create/update
  • ✓ Subscriptions synced in real-time
  • ✓ Invoices pushed on finalization

Baremetrics

Real-time revenue dashboards and forecasting. bxb pushes billing events automatically so Baremetrics can calculate MRR, ARR, trial conversions, and revenue forecasts.

  • ✓ Revenue events streamed via webhook
  • ✓ Trial start/convert/cancel tracked
  • ✓ Refunds and credit notes synced

ProfitWell

Subscription financial metrics and retention analytics. bxb automatically syncs revenue recognition, churn analysis, and benchmarking data against industry peers.

  • ✓ Subscription lifecycle events synced
  • ✓ Revenue recognized per GAAP rules
  • ✓ Churn and retention data exported