Billing & usage

This page is the contract reference for the billing surface. For a task-oriented walkthrough (choosing a tier, wiring up Checkout, switching to PAYG), read the Billing and usage guide. The per-endpoint generated pages live under API reference.

Base URL: https://api.cognitivx.io. Endpoints here are mounted under /api/billing, /api/costs, and /api/admin/analytics.

Auth model

Every endpoint requires Authorization: Bearer <key> or X-API-Key: <key>, with two exceptions:

• GET /api/billing/tiers is public (no auth).
• POST /api/billing/webhooks/stripe authenticates with a Stripe signature, not a bearer key. Do not call it yourself.

Create keys at developers.cognitivx.io/keys. The /api/costs/admin/* and /api/admin/analytics/* endpoints additionally require an admin account.

Error responses are { "detail": "<message>" } with a 4xx/5xx status, except topup and payg-cap validation failures, which return { "error": "...", "message": "..." } (noted per endpoint).

Endpoints at a glance

Tiers

These numbers are illustrative. The live catalog is served by GET /api/billing/tiers; read it for current values.

Subscriptions

Get billing status

Read the caller's current tier, subscription state, and PAYG summary.

GET /api/billing/me · Auth required.

No request body. Returns the tier, Stripe-derived subscription status, trial and renewal dates, the live billing interval, and a PAYG snapshot so a client can render a "Switch to PAYG" CTA without a second call.

curl https://api.cognitivx.io/api/billing/me \
  -H "Authorization: Bearer icog_xxx"

import { configureApiClient, billing } from '@cognitivx/sdk';

configureApiClient({ apiKey: process.env.ICOG_API_KEY });

const status = await billing.me();
// status.tier, status.payg_eligible, status.payg_balance_usd

{
  "tier": "awakened",
  "subscription_status": "active",
  "trial_ends_at": null,
  "renewal_date": "2026-07-16",
  "subscription_interval": "monthly",
  "payg_eligible": true,
  "payg_balance_usd": 0.0,
  "payg_transactions_30d": 0
}

subscription_interval is "monthly", "annual", or null (for amnesiac and payg, which have no subscription) and is resolved live from Stripe. payg_balance_usd is null when the user has never held a credit balance.

Get the tier catalog

Fetch the tier configuration for a pricing page.

GET /api/billing/tiers · No auth required (public).

This is the only public billing endpoint. It returns the tier configuration object (display names, monthly and annual prices, per-month recall-credit caps, and memory caps per tier).

curl https://api.cognitivx.io/api/billing/tiers

{
  "amnesiac": { "display_name": "Free", "price_monthly": 0, "...": "..." },
  "awakened": { "display_name": "Awakened", "price_monthly": 20, "price_annual": 199, "...": "..." },
  "conscious": { "display_name": "Conscious", "price_monthly": 200, "price_annual": 1999, "...": "..." },
  "payg": { "display_name": "Pay-as-You-Go", "price_monthly": 0, "...": "..." }
}

Start a subscription checkout

Create a Stripe Checkout session and redirect the user to pay.

POST /api/billing/create-checkout · Auth required.

The response url is a Stripe-hosted Checkout page. Redirect the browser there; on success Stripe sends the user back to your app and a webhook activates the subscription. If the webhook lags, call verify-checkout to close the gap.

curl -X POST https://api.cognitivx.io/api/billing/create-checkout \
  -H "Authorization: Bearer icog_xxx" \
  -H "Content-Type: application/json" \
  -d '{"tier": "awakened", "interval": "monthly"}'

import { configureApiClient, billing } from '@cognitivx/sdk';

const { url } = await billing.createCheckout({
  tier: 'awakened',
  interval: 'monthly',
});
// redirect the browser to `url`

{ "url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3..." }

Errors

Verify a checkout

Poll Stripe to confirm a just-completed checkout activated the plan.

POST /api/billing/verify-checkout · Auth required.

Call this from your success page (the redirect URL carries the session id). It checks Stripe's payment_status and, when paid, flips the user to the purchased tier. Idempotent with the webhook; returns activated: false if the session is not yet paid.

curl -X POST https://api.cognitivx.io/api/billing/verify-checkout \
  -H "Authorization: Bearer icog_xxx" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "cs_test_a1B2c3..."}'

const { activated } = await billing.verifyCheckout({
  session_id: 'cs_test_a1B2c3...',
});

{ "activated": true }

Errors

Switch monthly and annual

Change an active subscription's billing interval mid-cycle.

POST /api/billing/change-interval · Auth required.

Stripe applies a proration (create_prorations): the unused portion of the current interval is credited against the new interval's invoice. There is no cash refund; the credit or debit lands on the next invoice. If the user is already on the requested interval, the call is a no-op.

curl -X POST https://api.cognitivx.io/api/billing/change-interval \
  -H "Authorization: Bearer icog_xxx" \
  -H "Content-Type: application/json" \
  -d '{"interval": "annual"}'

const res = await billing.changeInterval({ interval: 'annual' });
// res.status is "switched" or "noop"

{
  "status": "switched",
  "message": "Switched to annual. Stripe proration applied; see next invoice.",
  "subscription_id": "sub_1Nxyz...",
  "new_price_id": "price_annual_awakened",
  "previous_price_id": "price_monthly_awakened"
}

When already on the target interval, status is "noop" and previous_price_id is omitted.

Errors

Open the billing portal

Create a Stripe customer-portal session for self-service management.

POST /api/billing/create-portal · Auth required.

No request body. The portal is where customers update cards, view invoices, and cancel. Redirect the browser to the returned url.

curl -X POST https://api.cognitivx.io/api/billing/create-portal \
  -H "Authorization: Bearer icog_xxx"

const { url } = await billing.createPortal();
// redirect the browser to `url`

{ "url": "https://billing.stripe.com/p/session/test_a1B2c3..." }

Errors

Pay-as-you-go (PAYG)

PAYG bills metered spend against a prepaid credit balance instead of a flat monthly subscription. Users top up a dollar balance, spend it down, and can cap their monthly spend. Top-ups are whole dollars ($5–$500); spend caps range $1–$10,000.

Switch to PAYG

Cancel any active subscription and move the user to metered billing.

POST /api/billing/switch-to-payg · Auth required.

Behavior depends on the current tier. amnesiac just flips the tier (no subscription to cancel). awakened/conscious cancels the active subscription immediately with proration. payg is idempotent and returns already_payg: true.

curl -X POST https://api.cognitivx.io/api/billing/switch-to-payg \
  -H "Authorization: Bearer icog_xxx" \
  -H "Content-Type: application/json" \
  -d '{"refund_method": "credit"}'

const res = await billing.switchToPayg({ refund_method: 'credit' });
// res.new_tier === "payg"; res.requires_topup tells you whether to prompt

{
  "already_payg": false,
  "refunded_usd": 12.33,
  "refund_method": "credit",
  "new_tier": "payg",
  "requires_topup": true
}

requires_topup is true when the credit balance is <= 0 after switching, so the client knows to prompt for a top-up before the user can spend. refund_method in the response is credit, card, or none.

Errors

Top up credits

Create a Stripe PaymentIntent to add credit to the PAYG balance.

POST /api/billing/topup · Auth required.

Returns a Stripe client_secret and the PaymentIntent id. Confirm the payment client-side with Stripe.js; the credit lands on the balance once the payment succeeds (handled by webhook). amount_usd is converted to credits at 10,000 credits per dollar.

curl -X POST https://api.cognitivx.io/api/billing/topup \
  -H "Authorization: Bearer icog_xxx" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 25}'

const { client_secret } = await billing.topup({ amount_usd: 25 });
// confirm `client_secret` with Stripe.js

{
  "client_secret": "pi_3Nxyz..._secret_abc",
  "payment_intent_id": "pi_3Nxyz..."
}

Errors

Get balance

Read the current PAYG credit balance and low-balance flags.

GET /api/billing/balance · Auth required.

No request body. balance_credits is canonical; balance_usd is the same value times 0.0001 and is kept for back-compat. low_balance is true when the balance drops below 20,000 credits ($2). A user with no credit row gets all-zero defaults.

curl https://api.cognitivx.io/api/billing/balance \
  -H "Authorization: Bearer icog_xxx"

const { balance_credits, low_balance, depleted } = await billing.balance();

{
  "balance_credits": 245000,
  "balance_usd": 24.5,
  "low_balance": false,
  "depleted": false
}

PAYG estimate

Project the last 30 days of usage as a PAYG cost and compare it to the current tier price.

GET /api/billing/payg-estimate · Auth required.

No request body. Use this to show a "would PAYG be cheaper?" panel. The markup multiplier (default 1.3) and a per-model breakdown are included.

curl https://api.cognitivx.io/api/billing/payg-estimate \
  -H "Authorization: Bearer icog_xxx"

{
  "raw_spend_30d_usd": 8.42,
  "projected_payg_30d_usd": 10.95,
  "current_tier": "awakened",
  "current_tier_price_usd": 20.0,
  "effective_current_price_usd": 20.0,
  "savings_vs_current_usd": 9.05,
  "markup_multiplier": 1.3,
  "model_breakdown": [
    {
      "model": "gemini-2.5-flash",
      "tokens_in": 412000,
      "tokens_out": 88000,
      "cost_raw_usd": 6.10,
      "cost_payg_usd": 7.93
    }
  ]
}

effective_current_price_usd is 0 while the user is on a trial, on the free tier, or canceled.

Set the PAYG spend cap

Set or clear a monthly PAYG spend cap. Requests hard-block once the cap is reached.

PUT /api/billing/payg-cap · Auth required.

Stored internally as credits and enforced at request time. When the month-to-date spend reaches the cap, further metered requests are blocked (monthly_cap_reached).

curl -X PUT https://api.cognitivx.io/api/billing/payg-cap \
  -H "Authorization: Bearer icog_xxx" \
  -H "Content-Type: application/json" \
  -d '{"monthly_cap_usd": 50}'

await billing.setPaygCap({ monthly_cap_usd: 50 });
// clear it with: await billing.setPaygCap({ monthly_cap_usd: null });

{ "monthly_cap_usd": 50.0, "spent_this_month_usd": 12.4 }

Errors

Get the PAYG spend cap

Read the current monthly cap and month-to-date spend.

GET /api/billing/payg-cap · Auth required.

No request body. monthly_cap_usd is null when no cap is set.

curl https://api.cognitivx.io/api/billing/payg-cap \
  -H "Authorization: Bearer icog_xxx"

const { monthly_cap_usd, spent_this_month_usd } = await billing.getPaygCap();

{ "monthly_cap_usd": 50.0, "spent_this_month_usd": 12.4 }

List PAYG transactions

Read recent PAYG ledger rows for a transaction list.

GET /api/billing/payg-transactions · Auth required.

event_type is spend, topup, proration_credit, and similar. Spend rows carry a negative amount_usd and a model; non-spend rows have model: null.

curl 'https://api.cognitivx.io/api/billing/payg-transactions?limit=10' \
  -H "Authorization: Bearer icog_xxx"

const { transactions } = await billing.paygTransactions(10);

{
  "transactions": [
    {
      "id": 4821,
      "event_type": "spend",
      "amount_usd": -0.0123,
      "balance_after": 24.4877,
      "model": "gemini-2.5-flash",
      "created_at": "2026-06-16T14:02:11.481000+00:00"
    },
    {
      "id": 4795,
      "event_type": "topup",
      "amount_usd": 25.0,
      "balance_after": 24.5,
      "model": null,
      "created_at": "2026-06-15T09:10:00.000000+00:00"
    }
  ]
}

Export PAYG receipts

Download a month of PAYG ledger rows as CSV.

GET /api/billing/payg-receipts.csv · Auth required.

Returns text/csv with a Content-Disposition: attachment header. Columns: timestamp_utc, event_type, amount_usd, balance_after_usd, model, stripe_id.

curl 'https://api.cognitivx.io/api/billing/payg-receipts.csv?month=2026-06' \
  -H "Authorization: Bearer icog_xxx" -OJ

timestamp_utc,event_type,amount_usd,balance_after_usd,model,stripe_id
2026-06-15T09:10:00+00:00,topup,25.000000,25.0000,,pi_3Nxyz...
2026-06-16T14:02:11.481000+00:00,spend,-0.012300,24.4877,gemini-2.5-flash,

Errors

Usage reporting

Current-month usage

This month's usage counters, recall-credit breakdown, tier cap, and display helpers.

GET /api/billing/usage · Auth required.

No request body. recall_credits_per_month is null for PAYG. recall_credit_breakdown always carries all five recall modes. show_onboarding_explainer is a one-shot flag (cleared after it is read once).

curl https://api.cognitivx.io/api/billing/usage \
  -H "Authorization: Bearer icog_xxx"

const usage = await billing.usage();

{
  "message": 312,
  "memory_write": 47,
  "image_gen": 3,
  "recall_credit_count": 18420,
  "recall_credits_per_month": 500000,
  "recall_credit_breakdown": {
    "foundational": 1200,
    "quick": 4100,
    "standard": 9800,
    "deep": 3000,
    "identity": 320
  },
  "cap_reset_at": "2026-07-01T00:00:00Z",
  "memories_saved_this_month": 47,
  "show_onboarding_explainer": false
}

Daily usage history

Daily usage buckets for billing charts.

GET /api/billing/usage-history · Auth required.

curl 'https://api.cognitivx.io/api/billing/usage-history?days=7' \
  -H "Authorization: Bearer icog_xxx"

const { days, history } = await billing.usageHistory(7);

{
  "days": 7,
  "history": [
    {
      "date": "2026-06-16",
      "messages": 42,
      "memory_writes": 6,
      "images": 1,
      "recalls": 88,
      "chats": 42,
      "dreams": 1,
      "insights": 0,
      "lens_regens": 0,
      "mcp_calls": 12,
      "other_actions": 3,
      "credits": 2640
    }
  ]
}

Memory capacity

Total stored-memory count vs. the tier cap.

GET /api/billing/memory-capacity · Auth required.

No request body. conscious and payg are uncapped (the cap field is null).

curl https://api.cognitivx.io/api/billing/memory-capacity \
  -H "Authorization: Bearer icog_xxx"

const capacity = await billing.memoryCapacity();

My LLM cost breakdown

The caller's own raw (un-marked-up) LLM cost for a month.

GET /api/costs/me · Auth required.

This is the raw OpenRouter cost, not the marked-up PAYG price. To project what PAYG would charge, use payg-estimate.

curl 'https://api.cognitivx.io/api/costs/me?month=2026-06' \
  -H "Authorization: Bearer icog_xxx"

Errors

Stripe webhook

Stripe-to-server event ingestion: subscription activation, top-up credit, and cancellation. Not caller-facing.

POST /api/billing/webhooks/stripe · Stripe signature auth (no bearer).

Authenticated by the stripe-signature header against the raw event body. The endpoint claims each event idempotently and processes it in the background.

{ "received": true }

Errors

Admin: cost analytics

These endpoints require an admin account (require_admin). They are documented for completeness and are not part of the normal developer surface.

All-users cost summary

GET /api/costs/admin/users · Admin.

Cost summary for all users with emails, sorted by cost descending. Returns 503 if the cost tracker is not initialized.

One user's cost detail

GET /api/costs/admin/user/{user_id} · Admin.

Detailed cost breakdown for one user. Returns 503 if the cost tracker is not initialized.

Cost by task

GET /api/costs/admin/by_task · Admin.

Per-task and per-model aggregate cost: count, mean, standard deviation, min/max, token means, p50/p95 latency, fallback rate, and cumulative totals.

Set a user's tier

POST /api/costs/admin/set-tier/{user_id}/{tier} · Admin.

Force a user's tier. PAYG is not a settable target here.

curl -X POST 'https://api.cognitivx.io/api/costs/admin/set-tier/me/awakened' \
  -H "Authorization: Bearer icog_admin_xxx"

{
  "user_id": "<uuid>",
  "tier": "awakened",
  "message": "Tier set to awakened"
}

Errors

Monthly cost breakdown

GET /api/admin/analytics/costs · Admin.

Monthly cost by model, user, and role, with budget status. budget_status is null unless a monthly budget is configured server-side. If the cost tracker is missing, this endpoint returns zeros with a "Cost tracking not enabled" message (not a 503).

{
  "month": "2026-06",
  "total_usd": 0,
  "system_usd": 0,
  "user_count": 0,
  "by_model": {},
  "by_user": [],
  "by_role": {},
  "budget_status": null
}

Cost trends

GET /api/admin/analytics/costs/trends · Admin.

Cost time series for trend charts.

{
  "period": "daily",
  "months": 3,
  "data": [
    { "date": "2026-06-16", "cost_usd": 0, "tokens_in": 0, "tokens_out": 0 }
  ]
}

PAYG overflow cohort

GET /api/admin/analytics/payg-overflow · Admin.

No params. Conscious subscribers who also buy PAYG top-ups (active Conscious plus at least $5 in top-ups over a trailing 90 days): counts, MRR, M1/M3 retention, and top spenders. Retention fields can be null.

{
  "active_overflow_count": 0,
  "conscious_total": 0,
  "overflow_pct": 0,
  "avg_topup_mrr": 0,
  "avg_total_mrr": 0,
  "retention_m1_overflow": null,
  "top_spenders": [
    {
      "user_id_prefix": "a1b2c3d4",
      "recent_topup_total_usd": 0,
      "estimated_total_mrr": 0
    }
  ]
}

Related

• Billing and usage guide — the task-oriented walkthrough.
• Authentication & keys — how to authenticate every request.
• API reference — the full generated endpoint index.