Billing

Brainstormer uses a credit-based billing system. All external provider costs (AI completions, embeddings, vector operations, voice, storage) are converted to credits and deducted from the organization’s wallet.

All API requests require a valid JWT token in the Authorization: Bearer <token> header. The API Gateway decodes the JWT and forwards auth context (user-id, organization-id, user-email, x-platform-role, x-org-role) as headers to downstream services.

This endpoint incurs provider cost and records a billing event via record_external_cost_event(). Credits are deducted from the organization’s wallet based on the configured margin multiplier.

Pricing Model

Parameter	Default Value	Description
`credit_value_usd`	$0.50	1 credit = $0.50
`margin_multiplier`	2.0x	Charged cost = raw provider cost x 2

For each billable operation:

charged_usd = raw_cost_usd * margin_multiplier
credits_burned = charged_usd / credit_value_usd
Organization wallet is debited by credits_burned

Example: A chat completion with raw cost of

0.01 results in

0.02 charged, burning 0.04 credits.

Platform Billing Summary (Superadmin)

Get platform-wide billing summary with cost vs. revenue analysis.

This endpoint requires superadmin access. Non-superadmin requests receive 403 Forbidden.

Query Parameters

string

Start of reporting period (ISO 8601 datetime). Optional.

string

End of reporting period (ISO 8601 datetime). Optional.

string

Filter to a specific organization UUID. Optional.

Response (200)

object

Aggregate totals for the period.

Show Totals

number

Total raw provider costs.

number

Total charged to organizations (with margin).

number

Total credits consumed.

number

Revenue margin (charged - raw).

object[]

Day-by-day breakdown for charting.

Show Daily entry

string

Date (YYYY-MM-DD).

number

Raw cost for the day.

number

Charged amount for the day.

number

Credits burned for the day.

object[]

Breakdown by provider (OpenRouter, Pinecone, ElevenLabs, etc.).

Show Provider entry

string

Provider name.

number

Raw cost for this provider.

number

Number of billable events.

object[]

Breakdown by organization.

Show Organization entry

string

Organization UUID.

string

Organization name.

number

Credits consumed.

number

Amount charged.

object[]

Distribution of organizations across billing plans.

curl "https://your-domain.com/api/billing/summary?\
startDate=2026-03-01T00:00:00Z&\
endDate=2026-04-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

const params = new URLSearchParams({
  startDate: "2026-03-01T00:00:00Z",
  endDate: "2026-04-01T00:00:00Z",
});

const response = await fetch(
  `https://your-domain.com/api/billing/summary?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
);

const summary = await response.json();

Billable Operations

The following operations are currently billed:

Operation	Provider	Description
`chat_completion`	`openrouter`	AI chat responses
`welcome_message_generation`	`openrouter`	Generated welcome messages
`embedding_generate`	`openai_embeddings` / `openrouter_embeddings`	Text and multimodal embeddings
`vector_upsert`	`pinecone`	Vector storage writes
`vector_query`	`pinecone`	Vector search queries
`vector_delete`	`pinecone`	Vector deletions
`voice_clone`	`elevenlabs`	Voice cloning
`voice_tts`	`elevenlabs`	Text-to-speech synthesis
`voice_stt_transcription`	`openai_whisper`	Speech-to-text
`file_store_put`	`aws_s3`	File uploads
`file_store_get`	`aws_s3`	File downloads
`file_egress`	`aws_s3`	File egress bandwidth

Data Model

Core Tables

Table	Purpose
`platform_billing_config`	Single-row global pricing defaults
`platform_billing_plans`	Plan catalog (starter, growth, scale)
`organization_billing_accounts`	Per-org plan + credit wallet
`organization_credit_ledger`	Immutable credit transaction history
`external_cost_events`	All billable provider events with raw/charged/credits

Atomic Billing Function

All billing writes happen through the record_external_cost_event() PostgreSQL function, which performs the entire flow in a single transaction:

Load billing defaults
Ensure org billing account exists
Lock wallet row
Calculate charged USD and credits burned
Update wallet balance
Insert cost event record
Insert ledger entry
Return billing result

This ensures wallet balances are always consistent under concurrent load.

List Public Billing Plans

Returns the active billing plan catalog shown on the signup page. No authentication required.

Response (200)

boolean

object[]

Array of active plans.

Show Plan entry

string

Plan code, e.g. free, starter, growth, enterprise.

string

Human-readable plan name.

string | null

Short description shown on the signup card.

number

Monthly price in USD.

number

Monthly credit allocation.

number | null

Maximum agents allowed, or null for unlimited.

number | null

Maximum knowledge bases allowed, or null for unlimited.

string[]

Marketing bullets. Used as-is for the enterprise plan.

number

Display order on the signup page.

curl "https://your-domain.com/api/auth/billing/plans"

const response = await fetch("https://your-domain.com/api/auth/billing/plans");
const plans = (await response.json()).data.plans;

List Admin Billing Plans

Returns all billing plans for superadmin management. Requires superadmin access.

Response (200)

object[]

Array of all plans.

Show Plan entry

string

Plan UUID.

string

Plan code.

string

Plan name.

string | null

Plan description.

number

Monthly credit allocation.

number

Monthly price in USD.

number | null

Maximum agents allowed.

number | null

Maximum knowledge bases allowed.

boolean

Whether the plan is active.

number

Display order.

Update a Billing Plan

Updates a billing plan. Requires superadmin access. The plan name is read-only.

Body

number

Monthly credit allocation.

number

Monthly price in USD.

number | null

Maximum agents allowed. Pass null for unlimited.

number | null

Maximum knowledge bases allowed. Pass null for unlimited.

string

Plan description shown on signup cards.

Response (200)

boolean

Getting Started

Agent Provisioning

Bot Service

Auth Service

Knowledge Service

Billing

Billing

Pricing Model

Platform Billing Summary (Superadmin)

Query Parameters

Response (200)

Billable Operations

Data Model

Core Tables

Atomic Billing Function

List Public Billing Plans

Response (200)

List Admin Billing Plans

Response (200)

Update a Billing Plan

Body

Response (200)

​Billing

​Pricing Model

​Platform Billing Summary (Superadmin)

​Query Parameters

​Response (200)

​Billable Operations

​Data Model

​Core Tables

​Atomic Billing Function

​List Public Billing Plans

​Response (200)

​List Admin Billing Plans

​Response (200)

​Update a Billing Plan

​Body

​Response (200)

Billing

Pricing Model

Platform Billing Summary (Superadmin)

Query Parameters

Response (200)

Billable Operations

Data Model

Core Tables

Atomic Billing Function

List Public Billing Plans

Response (200)

List Admin Billing Plans

Response (200)

Update a Billing Plan

Body

Response (200)