Credits and billing - ai-cmo.dev

ai-cmo.dev uses a micro-USD credit system. 1,000,000 µUSD = $1.00. Every metered operation (measurement run, SEO refresh, chat, research) reserves credits up front and settles the actual cost after completion.

Endpoints

Method	Path	Scope	Description
GET	`/api/v1/workspaces/{workspace}/credits/balance`	`credits:read`	Current balance (posted, held, available)
GET	`/api/v1/workspaces/{workspace}/credits/usage`	`credits:read`	Usage ledger (limit param, default 100, max 500)
POST	`/api/v1/workspaces/{workspace}/credits/top-up`	Session-only	Mock top-up (local/test only)
POST	`/api/v1/workspaces/{workspace}/billing/checkout`	Session-only	Create Stripe checkout session
GET	`/api/v1/workspaces/{workspace}/billing/status`	Session	Billing status

Credit model

Free grant: New workspaces receive 1,000,000 µUSD ($1.00), expiring in 30 days. One grant per user.
Reserve-then-settle: An operation reserves an estimated amount. As the operation runs, incremental leases are authorized against the reservation. When complete, the actual cost is settled.
Insufficient credits: If the balance cannot cover a reservation, the operation fails with 402 insufficient_credits including requiredMicrousd and availableMicrousd in details.

Read balance

curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://ai-cmo.dev/api/v1/workspaces/{workspace}/credits/balance

Response:

{
  "workspace": "acme",
  "state": "active",
  "postedMicrousd": 1000000,
  "heldMicrousd": 250000,
  "availableMicrousd": 750000,
  "nextExpiryAt": "2026-09-09T10:00:00.000Z"
}

Read usage

curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     "https://ai-cmo.dev/api/v1/workspaces/{workspace}/credits/usage?limit=100"

Returns minimal ledger and metered-operation data. The limit parameter defaults to 100 and has a maximum of 500.

Stripe checkout

Session-only. Creates a Stripe Checkout Session for a credit top-up.

curl -X POST https://ai-cmo.dev/api/v1/workspaces/{workspace}/billing/checkout \
  -H "Cookie: geo.session=..." \
  -H "Content-Type: application/json" \
  -d '{"amountMicrousd": 10000000}'

Request body: Response:

{
  "url": "https://checkout.stripe.com/pay/cs_test_...",
  "checkoutSessionId": "cs_test_abc123"
}

Mock top-up

Available only in local/test mode (when STRIPE_SECRET_KEY is not set or GEO_OPERATOR_MODE=local). Session-only.

curl -X POST https://ai-cmo.dev/api/v1/workspaces/{workspace}/credits/top-up \
  -H "Cookie: geo.session=..." \
  -H "Content-Type: application/json" \
  -d '{"amountMicrousd": 500000, "idempotencyKey": "topup-unique-01"}'

When Stripe is configured, mock top-ups return 409 mock_topup_disabled.

Reservation amounts

Operation	Current reservation
Measurement (standard)	From pricing config + workspace prompts
Measurement (lite)	From pricing config + workspace prompts
Measurement (smoke)	From pricing config + workspace prompts
Measurement (exa)	From pricing config + workspace prompts
SEO refresh	From pricing config
Chat	720,000 µUSD per turn (6 steps, 120,000 per step)
Prompt generation	250,000 µUSD per call, max 100 calls
Research	80 provider calls with provider-specific caps

Billing status

curl -H "Cookie: geo.session=..." \
     https://ai-cmo.dev/api/v1/workspaces/{workspace}/billing/status

Returns receipts for the latest 20 checkout sessions with their status (pending, succeeded, failed).

Stripe webhook

POST /api/v1/webhooks/stripe (public route) Stripe sends checkout.session.completed and checkout.session.expired events to this endpoint. The server verifies the signature against STRIPE_WEBHOOK_SECRET. If the secret is unset, the webhook fails closed with 503 billing_unavailable. The webhook is idempotent: a replayed checkout.session.completed event never double-credits.

​Endpoints

​Credit model

​Read balance

​Read usage

​Stripe checkout

​Mock top-up

​Reservation amounts

​Billing status

​Stripe webhook