Billing API

Manage subscriptions, check usage, enable BYOK, and purchase credits

Billing API

Retrieve billing information and perform subscription actions such as creating a checkout session, enabling bring-your-own-key (BYOK) mode, checking usage, and purchasing credit packs.

All billing endpoints require session authentication.

Get billing info

GET /api/billing

Returns the available plans, the authenticated user’s current plan, subscription status, BYOK status, and daily usage.

Response

{
  "plans": {
    "solo": {
      "name": "Solo",
      "price": 29,
      "agents": 1,
      "features": ["1 AI Agent", "2GB RAM", "Telegram"]
    },
    "collective": {
      "name": "Collective",
      "price": 69,
      "agents": 3,
      "features": ["3 AI Agents", "4GB RAM", "Telegram + WhatsApp"]
    },
    "label": {
      "name": "Label",
      "price": 149,
      "agents": 10,
      "features": ["10 AI Agents", "8GB RAM", "All channels", "White-label emails"]
    },
    "network": {
      "name": "Network",
      "price": 499,
      "agents": -1,
      "features": ["Unlimited agents", "16GB RAM", "White-label reselling"]
    }
  },
  "currentPlan": "solo",
  "subscriptionStatus": "active",
  "byokEnabled": false,
  "usage": {
    "dailyUnits": 600,
    "used": 245,
    "remaining": 355
  }
}

Response fields

Field	Type	Description
plans	object	Map of available plans with pricing and features
currentPlan	string	User’s current plan. One of solo, collective, label, or network. Users who subscribed via the Stripe checkout flow have plans like solo, collective, label, or network.
subscriptionStatus	string	Stripe subscription status (active, inactive, etc.)
byokEnabled	boolean	Whether BYOK mode is active
usage.dailyUnits	number	Daily unit allowance for the current plan
usage.used	number	Units used today
usage.remaining	number	Units remaining today

The currentPlan value is set by the Stripe webhook when a checkout completes. Plans created through the primary checkout flow (/api/stripe/checkout) use solo, collective, label, or network. The billing dashboard displays these with their plan names: solo appears as “Solo”, collective as “Collective”, and label as “Label”.

Errors

Code	Description
401	Unauthorized — no valid session
500	Failed to fetch billing info

Billing actions

POST /api/billing

Performs a billing action. The action field in the request body determines which operation is executed.

Create checkout session

Creates a Stripe checkout session for subscribing to a plan.

Request body

Field	Type	Required	Description
action	string	Yes	Must be create-checkout
plan	string	Yes	Plan to subscribe to: solo, collective, label, or network

Response

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

Redirect the user to the returned url to complete payment.

Errors

Code	Description
400	Invalid plan

Enable BYOK

Enables bring-your-own-key mode with an external AI provider. When BYOK is active, AI requests are billed directly by the provider rather than consuming platform credits.

Request body

Field	Type	Required	Description
action	string	Yes	Must be enable-byok
apiKey	string	Yes	Your API key for the external provider
provider	string	Yes	Provider name (for example, openai, anthropic)

Response

{
  "success": true,
  "message": "BYOK enabled with openai. You'll pay openai directly for AI usage."
}

Errors

Code	Description
400	API key and provider are required

Disable BYOK

Disables BYOK mode and reverts to platform credits.

Request body

Field	Type	Required	Description
action	string	Yes	Must be disable-byok

Response

{
  "success": true,
  "message": "BYOK disabled. Using platform credits."
}

Get usage

Returns the current day’s unit consumption.

Request body

Field	Type	Required	Description
action	string	Yes	Must be get-usage

Response

{
  "dailyUnits": 600,
  "used": 245,
  "remaining": 355,
  "resetsAt": "midnight UTC"
}

Buy credits

Purchases a credit pack.

Request body

Field	Type	Required	Description
action	string	Yes	Must be buy-credits
pack	string	Yes	Pack size: 50, 200, or 500

Response

{
  "success": true,
  "credits": 15,
  "price": "$15"
}

Pack size	Credits
50	5
200	15
500	30

Errors

Code	Description
400	Invalid pack

Common errors

These apply to all billing POST actions:

Code	Description
400	Invalid action
401	Unauthorized — no valid session
500	Internal error

Stripe checkout

GET /api/stripe/checkout

Redirects to a Stripe checkout session for subscribing to a plan. This endpoint uses the solo, collective, label, and network plan names with GBP pricing. Admin users (configured via ADMIN_EMAILS) bypass Stripe and are redirected directly to the onboarding page.

The checkout plans (solo, collective, label, network) are the primary subscription path for agent provisioning. Admin users (configured via ADMIN_EMAILS) bypass Stripe entirely.

Query parameters

Parameter	Type	Required	Description
plan	string	Yes	Plan to subscribe to: solo, collective, label, or network

Checkout plan pricing

Plan	Price (GBP)
solo	£29/mo
collective	£69/mo
label	£149/mo
network	£499/mo

Response

On success, redirects (303) to the Stripe checkout URL. After payment completes, Stripe redirects the user to /checkout/success?session_id={CHECKOUT_SESSION_ID}&plan={plan}. On error, redirects to the pricing page with an error query parameter.

Redirect	Description
Stripe checkout URL	Successful session creation — user completes payment on Stripe
/checkout/success?session_id=...&plan=...	Post-payment redirect from Stripe after successful checkout
/pricing?cancelled=1	User cancelled the Stripe checkout
/pricing?error=invalid_plan	Unrecognized plan name
/pricing?error=stripe_not_configured	Stripe secret key not set
/pricing?error=checkout_failed	Stripe API error
/onboard?plan=...&paid=1&admin=1	Admin bypass (no payment required)

Subscription deploy

POST /api/subscriptions/deploy

Records a subscription-to-plan mapping so the next agent deployment uses the correct resource tier. This endpoint is called by the Stripe webhook after a checkout completes.

This is a backend-only endpoint that requires bearer token (API key) authentication.

Request body

Field	Type	Required	Description
tier	string	Yes	Plan tier. One of: solo, collective, label, network, underground, starter, pro, scale, enterprise, white_glove
customerId	string	Conditional	Customer identifier. Either customerId or stripeCustomerId must be provided.
stripeCustomerId	string	Conditional	Stripe customer ID. Either customerId or stripeCustomerId must be provided.
subscriptionId	string	No	Stripe subscription ID

Response

{
  "success": true,
  "customerId": "cus_abc123",
  "subscriptionId": "sub_xyz",
  "tier": "solo",
  "resources": {
    "memory": "2g",
    "cpus": "1"
  }
}

Plan resource allocations

Tier	Memory	CPUs	Notes
solo	2 GB	1
collective	4 GB	2
label	8 GB	4
network	16 GB	4
underground	2 GB	1	Legacy alias
starter	2 GB	1	Legacy alias
pro	4 GB	2	Legacy alias
scale	8 GB	4	Legacy alias
enterprise	16 GB	4	Legacy alias
white_glove	32 GB	8	Legacy alias

Errors

Code	Description
400	customerId is required (when neither customer ID field is provided)
400	tier is required
400	Invalid tier
401	Unauthorized — missing or invalid bearer token
500	Subscription activation failed