One backend for your money.

---

Quick start

Needs Docker with Compose v2 and openssl. Runs the released image (linux/amd64 and linux/arm64) with Postgres (pgvector) and Redis; no clone, no build.

mkdir inite-billing && cd inite-billing
curl -fsSLO https://raw.githubusercontent.com/inite-ai/inite-billing-service/main/docker-compose.quickstart.yml
cat > .env <<EOF
BILLING_VERSION=1.4
POSTGRES_PASSWORD=$(openssl rand -hex 24)
JWT_SECRET=$(openssl rand -hex 48)
KEY_SEAL_SECRET=$(openssl rand -base64 32)
EOF
docker compose -f docker-compose.quickstart.yml up -d --wait
curl http://localhost:3000/health/ready
open http://localhost:3000/api   # Swagger (xdg-open on Linux)

The container applies its migrations on boot. BILLING_VERSION takes X.Y (newest patch of that release) or vX.Y.Z; :latest follows the main-branch deploy, not a release. In this development setup billing checks HS256 tokens against JWT_SECRET and the issuer in JWT_ISSUER (default http://localhost:3002, the auth quick start); give both .env files the same JWT_SECRET to sign in through it. Production verifies RS256 against the JWKS at AUTH_SERVICE_URL. Add ANTHROPIC_API_KEY to .env for the assistant. Working on the code instead: Run from source.

Why not Lago, Stripe Billing or Kill Bill?

• Stripe Billing needs nothing to run, and it does tax (Stripe Tax), invoice documents and revenue recognition. INITE Billing does none of those: its invoice is a record per paid order with the provider's receipt link. Stripe Billing only charges through Stripe; here Stripe is one adapter beside crypto (ETH/SOL/TON/TRON), Apple and Google in-app purchases, ONE and Lava, all driving the same order state machine.
• Lago is also open source and AGPL, and is built for high-volume usage events and invoicing on top of them. It hands payment collection to Stripe, Adyen or GoCardless. INITE Billing collects payment through its own rail adapters, and grants entitlements and credits from the same state change. Its metering is a credit ledger (per-model-tier rates, windowed quotas, one consume call), not an event-aggregation pipeline.
• Kill Bill has run in production for over a decade, with a plugin system for payment gateways and a full invoicing engine. INITE Billing is a newer NestJS/TypeScript service with a smaller surface, and less history behind it.
• AI agents as payers. Every checkout session also answers x402, so an agent with a USDC wallet on Base pays by itself; people can let their agents spend from an INITE wallet within limits they approve with a passkey. See AI agents and money.
• Retention work in the same service. Affiliates with NET-15 payouts, promo codes, LLM-written dunning and win-back outreach, and an admin assistant with confirm-before-execute actions.

Part of the INITE Triad: INITE Auth issues the tokens that Billing and INITE Brain verify; the contract between them is the Triad contract. Run all three with one compose file: inite-ai/inite-triad.

Why INITE Billing

Most billing stacks make you choose: a SaaS gateway that owns your money flow (Stripe Billing, Chargebee) or a bare payments library that leaves subscriptions, entitlements and dunning to you. INITE Billing is a single self-hostable service that ships the entire money lifecycle — catalog, checkout, subscriptions, credits, entitlements, affiliate program, retention automation — behind one payment-agnostic state machine, with the payment provider reduced to a pluggable adapter.

• Rail-agnostic by design — Stripe, ONE, Lava, Apple IAP, Google Play RTDN, and native multi-chain crypto (ETH/SOL/TON/TRON) implement one PaymentRailAdapter interface; the orchestrator state machine (created → open → paid → refunded/failed/expired) doesn't know which rail paid.
• AI-first, not AI-bolted-on — an embedded Claude assistant with role-gated tools and a confirm-before-execute action layer; LLM-generated dunning / win-back / abandoned-checkout outreach; semantic catalog search (pgvector); next-best-offer recommendations; AI funnel insights for admins. See docs/ai-features.md.
• AI agents pay, both ways — every checkout also accepts x402, so an agent with a wallet pays in USDC on Base by itself; and people get an INITE wallet (their own USDC under their passkey) from which their AI agents pay any x402 site within limits they approve. See AI agents and money.
• Built to meter AI products — credits are not a flat bucket: a metered feature registry with per-model-tier rates (tokens/requests/generations), windowed quotas with soft-cap warnings, and a backwards-compatible service-to-service consume API.
• Platform hub — INITE modules (club/events/education/health/shop/studio/ estate) call it machine-to-machine with per-service API keys; domain events fan out via a transactional outbox to per-service webhooks.
• Complete revenue toolkit — multi-level affiliate program with NET-15 payouts, promo codes, conversion funnel tracking with churn detection, heuristic payment-risk scoring, full admin UI (19 pages) + user dashboard in Next.js, EN/RU localized.
• Operable and audited — append-only migrations, IDOR-hardened endpoints, webhook signature verification, SSRF-guarded outbox, idempotency at every boundary, secret scanning and CodeQL in CI. See SECURITY.md.

AI agents and money

Get paid by agents (x402). With the crypto rail taking USDC on Base and Turnkey set up in admin → Crypto, every checkout session also returns an x402Url. An agent asks it, gets 402 with the terms, signs a USDC transfer for the invoice, and billing settles the order like any crypto payment. Guide: docs/x402.md.

Let people's agents pay (INITE wallet).

1. A person opens a wallet in their INITE account with a passkey. It is a Turnkey wallet whose only key is that passkey; billing cannot move the money.
2. They top it up with USDC on Base, or by PIX (converted and delivered as USDC), and withdraw with the passkey.
3. An AI agent connects to /mcp/wallet with an INITE Auth token (wallet:pay, issued for this resource, naming the agent in act).
4. The person approves the agent and its limits with the wallet passkey. That makes the agent a Turnkey user whose policy caps each payment.
5. The agent's pay tool fetches a URL and, on 402, pays within its per-payment, daily and monthly limits.

Agents with a wallet of their own. An agent registers with INITE Auth by itself (its own P-256 key, client_credentials) and gets a did:web identity. It opens its own wallet at POST /v1/agent-wallet: the Turnkey owner is the agent's key, so only the agent can spend. Anyone funds the address with USDC on Base. To pay, billing prepares the Turnkey request for an x402 URL and the agent stamps it with its key (/v1/agent-wallet/payments, then /confirm). An agent that can't keep a key registers with a client secret, and INITE keeps the wallet key for it: paying is then one call. Agents use the same wallet over MCP (/mcp/wallet: wallet, pay, pay_confirm, withdraw), and hand a person /fund/<address> to top it up (QR, PIX). In ChatGPT and other MCP Apps clients the wallet tools show as a card with the balance, a QR and a Top up button.

Let sites charge the wallet in one step. A person allows a site once, with limits, on one page in INITE ID. After that the site calls POST /v1/checkout/sessions/:id/pay-from-wallet and the order is paid from the wallet; the first time, it gets an approveUrl to send the person to.

Guides: billing.inite.ai/docs/wallet · docs/wallet.md.

Run from source

git clone [email protected]:inite-ai/inite-billing-service.git
cd inite-billing-service
npm install

cp env.example .env           # fill in secrets (ANTHROPIC_API_KEY for the assistant)
docker compose up -d postgres redis

npm run prisma:migrate        # apply schema (pgvector image required)
npm run db:seed               # optional: demo catalog (service + products + prices)
npm run start:dev             # backend on :3000, Swagger at /api

cd frontend && npm install && npm run dev   # UI on :3001

Verify:

curl http://localhost:3000/health
open http://localhost:3000/api        # Swagger

Full walkthrough (test DB, docker profiles, troubleshooting): docs/getting-started.md.

What ships in the box

Surface	What you get
Catalog & checkout	Products/prices per service, 2-phase checkout (session → pay), promo codes, idempotency keys
Payments	6 rail adapters, provider-credential storage in DB, webhook validation (amount/currency), BullMQ processing
Subscriptions	Trials, grace periods, renewal/expiry crons, lifecycle webhooks (billing.subscription.*)
Credits & metering	Ledger (grant/consume/reset/refund), metered feature registry, model-tier rates, windowed quotas, usage analytics
Entitlements	Access rights granted on payment, revoked on refund/expiry, queryable per user
AI assistant	Claude chat (AI SDK v7 streaming) with 19 tools (14 read + 5 confirm-gated actions), tool telemetry, 👍/👎 feedback, eval harness
Retention automation	Funnel event tracking, abandoned-checkout / dunning (day 0-2-5) / win-back / trial-ending outreach: LLM-personalized email + in-app, EN/RU
Notifications	Resend email (delivery webhooks, unsubscribe, suppression) + in-app notification center with preferences
Affiliates	Multi-level referral program, configurable commission levels, NET-15 payouts, payout providers
Risk	Velocity / outlier / failed-burst heuristics, monitor-only by default, admin review queue
Admin UI	19 pages: funnel kanban + AI insights, outreach stats, metering, risk review, catalog/orders/subscriptions/credits CRUD

Documentation

Full rendered docs — with diagrams and integration guides — at billing.inite.ai/docs.

Guides: Sell your first subscription · Meter AI usage with credits · Gate access with entitlements · Receive billing events · Go to production · Agents pay: x402 and the INITE wallet

Reference (mirrored in-repo):

Doc	What's inside
docs/getting-started.md	Local setup, env variables, migrations, running tests
docs/architecture.md	Module map, payment state machine, event flows, data model
docs/api.md	Full REST surface, auth (JWT / service API keys), examples
docs/ai-features.md	Assistant, action layer, outreach, metering, RAG, risk, insights
docs/x402.md	Getting paid by AI agents over x402: setup in admin, limits, errors
docs/wallet.md	INITE wallet: who holds what, top-up, withdrawal, agents and their limits
docs/operations.md	Deploy, feature flags & rollout order, adding a payment rail
SECURITY.md	Threat ledger, known limitations, vulnerability reporting
CONTRIBUTING.md	Hard bars for PRs, conventions, release flow
AGENTS.md	Rules, zones, gates and module map for AI coding agents (and humans)

Contributing

Contribute with an AI agent

The Codespace comes up with Node 22, Postgres (pgvector), Redis, dependencies installed and migrations applied. Open the repo in your agent and say /contribute (Claude Code), or "read AGENTS.md and help me add …" (Cursor, Codex, Copilot, Gemini CLI, Windsurf). AGENTS.md holds the rules, the risky zones, and the exact CI gates the agent runs before opening a PR. Only want to propose something? /spec-idea, or the Product idea issue form. Looking for a first task: good first issue.

By hand

PRs land on main only through pull requests — CI (build-test) is a required check, titles follow Conventional Commits (release-please cuts versions and the changelog from them). Read CONTRIBUTING.md for the hard bars: tests for money paths, exact Decimal arithmetic, backwards-compatible public contracts, append-only migrations.

License

AGPL-3.0. Part of the INITE ecosystem — see also inite-auth-service (identity) and inite-brain-service (memory).