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

Each billable operation is priced under the active rate policy (a versioned rate card managed by superadmins under Platform Billing → Rate Card), not a single global multiplier:

The event is matched to a rate-card rule by provider and operation (for example openrouter/chat_completion*).
The rule’s margin is applied to the provider’s raw cost, and the result is converted to credits at the policy’s fixed credit value.
A per-conversation ceiling (capPerSubject) can cap the charge; a capped charge is recorded as such in the ledger entry’s pricing trace.
The organization’s wallet is debited by credits_burned, and the ledger entry records the policy_version it was priced under.

Live numbers (credit value, per-rule margins, caps) are read from the active rate card, never from this page. See the credits guide for the customer-facing explanation.

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.

Get Organization Billing Account

Returns the caller’s organization billing account: plan terms, credit balances, resource usage/limits, and when plan credits next reset. Requires authentication.

Response (200)

object

Show BillingAccount

string

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

string

Human-readable plan name.

number

The plan allowance THIS org is entitled to — its own frozen terms, not the current catalog price for the plan.

number

Denormalized total. Prefer planCreditsBalance + addonCreditsBalance for the available balance.

number

Remaining plan-allowance credits for the current cycle. Resets at nextResetAt.

number

Remaining top-up / admin-grant / referral-bonus credits. Never expires.

number

Lifetime total granted into the add-on pool — top-ups, admin grants, and referral bonuses, whichever of the three funded it. This is the denominator shown next to the add-on balance; it replaced a totalAddonCreditsPurchased field that only counted top-ups (a referral- or admin-granted org used to see its balance measured against zero).

string | null

ISO 8601 instant the plan portion of the balance next resets, or null if nothing on this deployment will reset it on a schedule (e.g. a custom/enterprise account granted by hand, or a canceled subscription). Computed server-side — see resetKind. Never derive this from billingCycleStart; it is not a schedule.

string

One of subscription_renewal (the date above is the Stripe subscription’s current_period_end), monthly_free_reset (the 1st of next month, UTC), or none (no scheduled reset — nextResetAt is null).

boolean

Whether the org has an active/attached Stripe subscription.

string

When the current cycle’s credits were provisioned. Not a forward-looking schedule — use nextResetAt for that.

number | null

Agent seat limit, or null for unlimited (always null for a superadmin caller).

number | null

Knowledge base limit, or null for unlimited.

number | null

Member seat limit, or null for unlimited.

number

Current agent count.

number

Current knowledge base count.

number

Current org member count.

billingCycleEnd was removed from this response — it was a stored column with no writer (dead schema; see docs/architecture/CREDIT_BALANCE_MODEL.md). Use nextResetAt / resetKind for the renewal date.

"Authorization: Bearer $TOKEN" ```
</CodeGroup>

---

## Get Credit Ledger

<ParamField method="GET" path="/api/auth/billing/ledger" />

Returns a page of the organization's immutable credit transaction history.
Requires authentication.

### Query Parameters

<ParamField query="limit" type="integer" default="50" />
<ParamField query="offset" type="integer" default="0" />
<ParamField query="sourceType" type="string">
Filter to one source type, e.g. `topup`, `admin_grant`, `referral_bonus`,
`debit_external_cost`.
</ParamField>
<ParamField query="sourceId" type="string">
Filter to one source id (e.g. a conversation UUID).
</ParamField>

### Response (200) — ledger entry

<ResponseField name="transactionType" type="string">
`credit`, `credit_initial_provision`, or a debit type.
</ResponseField>
<ResponseField name="creditsDelta" type="number">
Signed credit change.
</ResponseField>
<ResponseField name="balanceBefore" type="number" />
<ResponseField name="balanceAfter" type="number" />
<ResponseField name="sourceType" type="string | null" />
<ResponseField name="sourceId" type="string | null" />
<ResponseField name="policyVersion" type="number | null">
Which rate-card version priced this row. **Superadmin-only** — the field is
entirely absent from a non-superadmin response, not `null`, because the
rate-card version is a superadmin abstraction; a present-but-null value would
read as "there isn't one" rather than "you cannot see this".
</ResponseField>
<ResponseField name="metadata" type="object">
Includes `narration`: a human-readable description of the entry, e.g.
`"Monthly plan renewal · Growth plan · 35,000 credits"` or `"Credit top-up ·
10,000 credits"`. Every grant, renewal and burn writes one; historical rows
were backfilled.
</ResponseField>
<ResponseField name="createdAt" type="string" />

<CodeGroup>
```bash curl curl "https://your-domain.com/api/auth/billing/ledger?limit=20" \
-H "Authorization: Bearer $TOKEN" ```
</CodeGroup>

---

## List Public Billing Plans

<ParamField method="GET" path="/api/auth/billing/plans" />

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

### Response (200)

<ResponseField name="success" type="boolean" />

<ResponseField name="data.plans" type="object[]">
Array of active plans.
<Expandable title="Plan entry">
  <ResponseField name="code" type="string">
    Plan code, e.g. `free`, `starter`, `growth`, `enterprise`.
  </ResponseField>
  <ResponseField name="name" type="string">
    Human-readable plan name.
  </ResponseField>
  <ResponseField name="description" type="string | null">
    Short description shown on the signup card.
  </ResponseField>
  <ResponseField name="monthlyPriceUsd" type="number">
    Monthly price in USD.
  </ResponseField>
  <ResponseField name="monthlyCredits" type="number">
    Monthly credit allocation.
  </ResponseField>
  <ResponseField name="maxAgents" type="number | null">
    Maximum agents allowed, or `null` for unlimited.
  </ResponseField>
  <ResponseField name="maxKbs" type="number | null">
    Maximum knowledge bases allowed, or `null` for unlimited.
  </ResponseField>
  <ResponseField name="features" type="string[]">
    Marketing bullets. Used as-is for the enterprise plan.
  </ResponseField>
  <ResponseField name="sortOrder" type="number">
    Display order on the signup page.
  </ResponseField>
</Expandable>
</ResponseField>

<CodeGroup>
```bash curl
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

Get Organization Billing Account

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

​Get Organization Billing Account

​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

Get Organization Billing Account

Response (200)

List Admin Billing Plans

Response (200)

Update a Billing Plan

Body

Response (200)