Billing

The Majestix AI Inference Hub uses a credits-based billing system powered by Stripe. 1 credit equals $0.001 USD. All model usage is billed identically regardless of client (web, VSCode, CLI).

---

Plans

Plan	Monthly Price	Credits Included	Notes
Free	$0	500	No payment method required
Guru	$10/mo	10,000	Stripe subscription
Pro	$50/mo	55,000	Stripe subscription (best value)

Additional credits can be purchased as one-time top-ups at any time.

---

GET /usage/me

Returns the authenticated user's current plan, credit balances, and usage breakdown. Responses are cached for 60 seconds.

GET /usage/me

Authentication

Requires one of:

• X-Api-Key header with a valid API key

• Authorization and X-Firebase-AppCheck headers for browser-based auth

Parameters

This endpoint takes no parameters.

Request Example

curl -X GET https://inference-api-611798501438.us-central1.run.app/usage/me \
  -H "X-Api-Key: inf_your_api_key_here"

Response

{
  "plan": "guru",
  "monthly_credits_total": 10000,
  "monthly_credits_remaining": 7450,
  "topup_balance": 2500,
  "billing_cycle_start": "2026-02-01T00:00:00Z",
  "billing_cycle_end": "2026-03-01T00:00:00Z",
  "usage": {
    "total_credits_used": 5050,
    "total_requests": 142,
    "breakdown_by_model": [
      {
        "model": "claude-sonnet",
        "credits_used": 3200,
        "requests": 45
      },
      {
        "model": "gpt-5.2",
        "credits_used": 1200,
        "requests": 67
      },
      {
        "model": "gemini-3-flash",
        "credits_used": 650,
        "requests": 30
      }
    ]
  }
}

Response Fields

Field	Type	Description
plan	string	Current subscription plan: free, guru, or pro.
monthly_credits_total	integer	Total monthly credits included in the plan.
monthly_credits_remaining	integer	Remaining monthly credits for the current billing cycle.
topup_balance	integer	Credits from one-time top-up purchases (do not expire monthly).
billing_cycle_start	string	ISO 8601 start of the current billing cycle.
billing_cycle_end	string	ISO 8601 end of the current billing cycle.
usage.total_credits_used	integer	Total credits consumed this billing cycle (monthly + top-up).
usage.total_requests	integer	Total API requests this billing cycle.
usage.breakdown_by_model	array	Per-model usage with model, credits_used, and requests.

Error Responses

Status	Description
401	Missing or invalid authentication
500	Internal server error

---

POST /billing/checkout

Creates a Stripe Checkout session for subscribing to a plan.

POST /billing/checkout

Authentication

Requires Firebase Auth (Authorization + X-Firebase-AppCheck headers).

Request Body

Parameter	Type	Required	Description
plan	string	Yes	The plan to subscribe to: guru or pro.

Request Example

curl -X POST https://inference-api-611798501438.us-central1.run.app/billing/checkout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "X-Firebase-AppCheck: <app_check_token>" \
  -d '{
    "plan": "guru"
  }'

Response

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "session_id": "cs_live_abc123"
}

Redirect the user to checkout_url to complete payment. Stripe Checkout supports credit/debit cards, Google Pay, Apple Pay, and Link.

Error Responses

Status	Description
400	Invalid plan specified
401	Missing or invalid Firebase authentication
409	User already has an active subscription
500	Internal server error

---

POST /billing/topup

Creates a Stripe Checkout session for a one-time credit purchase. Top-up credits do not expire at the end of the billing cycle.

POST /billing/topup

Authentication

Requires Firebase Auth (Authorization + X-Firebase-AppCheck headers).

Request Body

Parameter	Type	Required	Description
amount	string	Yes	Top-up tier: small, medium, or large.

Top-Up Tiers

Tier	Price	Credits
small	$5	5,000
medium	$25	27,500
large	$100	120,000

Request Example

curl -X POST https://inference-api-611798501438.us-central1.run.app/billing/topup \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "X-Firebase-AppCheck: <app_check_token>" \
  -d '{
    "amount": "medium"
  }'

Response

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "session_id": "cs_live_def456"
}

Error Responses

Status	Description
400	Invalid top-up tier specified
401	Missing or invalid Firebase authentication
500	Internal server error

---

POST /billing/portal

Returns a URL to the Stripe Customer Portal where users can manage their subscription, update payment methods, and view invoices.

POST /billing/portal

Authentication

Requires Firebase Auth (Authorization + X-Firebase-AppCheck headers).

Request Body

No request body required.

Request Example

curl -X POST https://inference-api-611798501438.us-central1.run.app/billing/portal \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "X-Firebase-AppCheck: <app_check_token>"

Response

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

Error Responses

Status	Description
401	Missing or invalid Firebase authentication
404	No Stripe customer record found for this user
500	Internal server error

---

POST /billing/sync-balance

Forces an immediate refresh of the user's cached credit balance. Use this after redeeming a voucher or promo code to reflect the updated balance without waiting for cache expiry.

POST /billing/sync-balance

Authentication

Requires one of:

• X-Api-Key header with a valid API key

• Authorization and X-Firebase-AppCheck headers for browser-based auth

Request Body

No request body required.

Request Example

curl -X POST https://inference-api-611798501438.us-central1.run.app/billing/sync-balance \
  -H "X-Api-Key: inf_your_api_key_here"

Response

{
  "monthly_credits_remaining": 8500,
  "topup_balance": 5000,
  "synced_at": "2026-02-25T10:45:00Z"
}

Error Responses

Status	Description
401	Missing or invalid authentication
500	Internal server error

---

POST /billing/webhook

Stripe webhook endpoint. This is called directly by Stripe and is not intended for client use. It requires a valid Stripe webhook signature in the Stripe-Signature header.

POST /billing/webhook

Handled Events

Event	Action
checkout.session.completed	Provision subscription or top-up credits
customer.subscription.created	Activate plan and allocate monthly credits
customer.subscription.updated	Handle plan upgrades/downgrades
customer.subscription.deleted	Revert to free plan
invoice.paid	Confirm payment and reset monthly credits
invoice.payment_failed	Flag account for follow-up
customer.subscription.trial_will_end	Send trial expiry notification
charge.refunded	Deduct refunded credits
payment_intent.succeeded	Log successful payment
payment_intent.payment_failed	Log failed payment
customer.created	Link Stripe customer to Firebase user

---

Admin Endpoints

The following endpoints require the authenticated user to have the admin role set in their Firestore user document.

GET /admin/usage

Returns platform-wide analytics including total requests, total credits consumed, active users, and usage trends.

GET /admin/usage

Authentication

Requires Firebase Auth with admin role.

Request Example

curl -X GET https://inference-api-611798501438.us-central1.run.app/admin/usage \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "X-Firebase-AppCheck: <app_check_token>"

Response

{
  "period": "2026-02",
  "total_requests": 48320,
  "total_credits_consumed": 1250000,
  "active_users": 312,
  "requests_by_day": [
    {"date": "2026-02-24", "requests": 1850, "credits": 52000},
    {"date": "2026-02-25", "requests": 2100, "credits": 58000}
  ],
  "top_models": [
    {"model": "claude-sonnet", "requests": 15200, "credits": 480000},
    {"model": "gpt-5.2", "requests": 12100, "credits": 320000}
  ]
}

Error Responses

Status	Description
401	Missing or invalid authentication
403	User does not have admin role
500	Internal server error

---

GET /admin/model-economics

Returns per-model cost versus revenue breakdown, showing the platform's margin on each model.

GET /admin/model-economics

Authentication

Requires Firebase Auth with admin role.

Request Example

curl -X GET https://inference-api-611798501438.us-central1.run.app/admin/model-economics \
  -H "Authorization: Bearer <firebase_id_token>" \
  -H "X-Firebase-AppCheck: <app_check_token>"

Response

{
  "period": "2026-02",
  "models": [
    {
      "model": "claude-sonnet",
      "provider": "anthropic",
      "total_requests": 15200,
      "total_input_tokens": 8500000,
      "total_output_tokens": 3200000,
      "provider_cost_usd": 34.20,
      "revenue_credits": 480000,
      "revenue_usd": 480.00,
      "margin_pct": 92.9
    },
    {
      "model": "gemini-3-flash",
      "provider": "vertex",
      "total_requests": 8400,
      "total_input_tokens": 12000000,
      "total_output_tokens": 4500000,
      "provider_cost_usd": 4.20,
      "revenue_credits": 85000,
      "revenue_usd": 85.00,
      "margin_pct": 95.1
    }
  ]
}

Model Economics Object

Field	Type	Description
model	string	Model identifier.
provider	string	Upstream provider name.
total_requests	integer	Total requests to this model in the period.
total_input_tokens	integer	Total input tokens processed.
total_output_tokens	integer	Total output tokens generated.
provider_cost_usd	float	Total cost paid to the upstream provider in USD.
revenue_credits	integer	Total credits charged to users.
revenue_usd	float	Total revenue in USD (credits / 1000).
margin_pct	float	Profit margin percentage: (revenue - cost) / revenue * 100.

Error Responses

Status	Description
401	Missing or invalid authentication
403	User does not have admin role
500	Internal server error