Billing & Subscriptions

Overview

The Billing API manages subscriptions via Stripe, tracks usage per workspace, and handles compute boost pack purchases. Subscriptions determine plan limits (sources, credits, documents, integrations).

---

Get Plans

GET /api/billing/plans

Get all plan information for the pricing page.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	No	If provided, marks the current plan

Response (200 OK)

{
  "plans": [
    {
      "tier": "pro",
      "display_name": "Pro",
      "price_monthly": 29,
      "price_yearly": 290,
      "limits": { ... },
      "is_current": false,
      "is_popular": false
    },
    {
      "tier": "growth",
      "display_name": "Growth",
      "price_monthly": 79,
      "price_yearly": 790,
      "limits": { ... },
      "is_current": true,
      "is_popular": true
    }
  ],
  "current_plan": "growth"
}

---

Get Subscription

GET /api/billing/subscription

Get current subscription details and plan limits.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Response (200 OK)

{
  "id": "a1b2c3d4-...",
  "workspace_id": "550e8400-...",
  "plan": "growth",
  "status": "active",
  "trial_ends_at": null,
  "current_period_start": "2026-03-01T00:00:00Z",
  "current_period_end": "2026-04-01T00:00:00Z",
  "cancel_at_period_end": false,
  "limits": {
    "tier": "growth",
    "max_workspaces": 10,
    "max_seats_per_workspace": 10,
    "max_research_sources": 500,
    "max_agent_runs": 500,
    "max_documents": 200,
    "has_integrations": true,
    "has_github": true,
    "has_api_access": true
  }
}

---

Get Credit Balance

GET /api/billing/credits

Get credit balance breakdown for a workspace, including monthly quota and bonus credits from boost packs.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Response (200 OK)

{
  "workspace_id": "550e8400-...",
  "plan": "growth",
  "monthly_quota": 500,
  "monthly_used": 123,
  "monthly_remaining": 377,
  "bonus_credits": 50,
  "total_available": 550,
  "total_used": 123,
  "total_remaining": 427,
  "percentage": 22.4,
  "is_blocked": false
}

---

Get Usage Dashboard

GET /api/billing/usage

Get detailed usage breakdown for the current billing period.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Response (200 OK)

{
  "workspace_id": "550e8400-...",
  "plan": "growth",
  "period_start": "2026-03-01T00:00:00Z",
  "period_end": "2026-04-01T00:00:00Z",
  "items": [
    {
      "usage_type": "file_upload",
      "display_name": "Research Sources",
      "current": 25,
      "limit": 500,
      "percentage": 5.0,
      "period": "monthly"
    },
    {
      "usage_type": "agent_run",
      "display_name": "Credits",
      "current": 123,
      "limit": 500,
      "percentage": 24.6,
      "period": "monthly"
    },
    {
      "usage_type": "document_draft",
      "display_name": "Documents",
      "current": 8,
      "limit": 200,
      "percentage": 4.0,
      "period": "monthly"
    }
  ]
}

---

Create Checkout Session

POST /api/billing/checkout

Create a Stripe Checkout session for plan upgrade.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
plan	string	Yes	Target plan: "pro" or "growth"
interval	string	Yes	"monthly" or "yearly"
success_url	string	No	Redirect URL on success
cancel_url	string	No	Redirect URL on cancel

Response (200 OK)

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

---

Create Portal Session

POST /api/billing/portal

Create a Stripe Customer Portal session for self-service subscription management (plan changes, cancellation, payment method updates).

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
return_url	string	No	URL to return to after portal

Response (200 OK)

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

---

Sync Subscription

POST /api/billing/sync

Sync workspace subscription with Stripe. Called after checkout redirect to ensure the plan shows correctly before the webhook fires.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

---

Purchase Boost Pack

POST /api/billing/boost/checkout

Purchase a compute boost pack via Stripe Checkout. Adds extra agent run credits to the workspace.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
pack_type	string	Yes	Boost pack type (e.g., "starter", "pro", "enterprise")
success_url	string	No	Redirect URL on success
cancel_url	string	No	Redirect URL on cancel

---

List Boost Packs

GET /api/billing/boosts

List active boost packs for a workspace.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Response (200 OK)

{
  "boosts": [
    {
      "id": "b2c3d4e5-...",
      "pack_type": "starter",
      "agent_runs_added": 50,
      "agent_runs_used": 12,
      "agent_runs_remaining": 38,
      "tokens_added": 0,
      "tokens_used": 0,
      "tokens_remaining": 0,
      "purchased_at": "2026-03-15T10:00:00Z",
      "expires_at": "2026-06-15T10:00:00Z",
      "is_active": true
    }
  ]
}

---

Get Compute Status

GET /api/billing/compute

Get internal compute envelope status for a workspace. Shows token/cost consumption relative to plan budget.

Query Parameters

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID

Response (200 OK)

{
  "workspace_id": "550e8400-...",
  "plan": "growth",
  "tokens_used": 450000,
  "token_budget": 2000000,
  "token_percentage": 22.5,
  "cost_usd": 1.35,
  "cost_budget_usd": 10.0,
  "cost_percentage": 13.5,
  "boost_tokens_remaining": 50000,
  "boost_runs_remaining": 38,
  "level": "normal",
  "should_throttle": false,
  "should_block": false,
  "message": "Usage is within normal limits."
}