Billing & usage API

HTTP reference for subscriptions, the Stripe portal, invoices, trials, tiers and AI usage tracking for individuals and teams.

All paths are relative to https://api.aleex-rank.ai/api/v2 and authenticate with X-API-Key: rk_... (see REST API). Stripe is the source of truth for subscriptions, invoices and payment methods; the platform keeps your tier in sync via Stripe webhooks. For the model, read Billing and Teams & tiers.

Tiers

GET /tiers

Public. Lists the individual and team tiers with their limits and prices.

{
  "success": true,
  "data": {
    "individual": [
      {"id": 1, "name": "Casual", "price_monthly": 0.00, "max_pentests_per_month": 5, "monthly_usage_budget_usd": 5.00},
      {"id": 2, "name": "Pro", "price_monthly": 29.99, "max_pentests_per_month": 50, "monthly_usage_budget_usd": 50.00}
    ],
    "team": [
      {"id": 4, "name": "Business", "price_monthly": 199.99, "monthly_usage_budget_usd": 50.00, "team_member_usage_budget_usd": 20.00}
    ]
  }
}

null on a limit means unlimited; 0 means not available (e.g. max_api_tokens: 0 for Casual).

Individual billing

POST /billing/checkout
POST /billing/portal
GET  /billing/status
GET  /billing/invoices

Checkout

{"tier_id": 2, "interval": "month"}

tier_id is 2 (Pro) or 3 (Ultra); interval is month or year. Returns a Stripe Checkout URL:

{
  "success": true,
  "data": {"checkout_url": "https://checkout.stripe.com/c/pay/cs_...", "session_id": "cs_..."}
}

Portal, status, invoices

POST /billing/portal returns a Stripe Customer Portal URL for changing plan, updating the card, cancelling and viewing invoices. GET /billing/status reports the current subscription (queried live from Stripe), including a trial-aware tier and any active trial:

{
  "success": true,
  "data": {
    "has_subscription": true,
    "tier": {"id": 2, "name": "Pro", "price_monthly": 29.99},
    "trial": null,
    "subscription": {
      "id": "sub_...",
      "status": "active",
      "billing_interval": "month",
      "current_period_end": "2026-03-25 00:00:00",
      "cancel_at_period_end": false
    }
  }
}

GET /billing/invoices lists invoices with status, amounts, period and links to the hosted invoice and PDF.

Individual trials

POST /billing/trial
GET  /billing/trial/status

Activate a one-time free trial of a higher tier (2 Pro or 3 Ultra). It must be higher than your current tier and can only be used once.

{"tier_id": 2}

{
  "success": true,
  "data": {
    "active": true,
    "trial_tier": {"id": 2, "name": "Pro", "price_monthly": 29.99},
    "starts_at": "2026-03-11 10:00:00",
    "ends_at": "2026-04-10 10:00:00",
    "days_remaining": 28,
    "trial_used": true
  }
}

Team billing

The team owner manages the subscription; members can read status.

POST /billing/teams/{id}/checkout
POST /billing/teams/{id}/portal
GET  /billing/teams/{id}/status
GET  /billing/teams/{id}/invoices
POST /billing/teams/{id}/reactivate
POST /billing/teams/{id}/trial
GET  /billing/teams/{id}/trial/status

Checkout and reactivate take tier_id: 4 (Business) and an interval. reactivate revives a suspended or grace_period team. GET /billing/teams/{id}/status is readable by any member; the rest are owner-only and return 403 otherwise.

{"tier_id": 4, "interval": "month"}

Stripe webhook

POST /webhooks/stripe

Public endpoint that Stripe calls directly; authenticated by the Stripe-Signature header rather than your API key. It keeps your tier and team billing status in sync (checkout completion, plan changes, payment success/failure, cancellation) and always responds 200. You do not call this yourself.

Personal usage

Every AI operation is costed and compared against your tier’s monthly budget.

GET   /usage/summary
GET   /usage/daily
GET   /usage/history
PATCH /usage/on-demand

Summary

Query parameters: ?month=2026-02, ?from=2026-02-01&to=2026-02-15, ?date=2026-02-15, ?model_id=7.

{
  "billing_period": {"start": "2026-02-01 00:00:00", "end": "2026-02-28 23:59:59"},
  "tier": {"name": "Pro", "monthly_usage_budget_usd": 50.00},
  "on_demand": {"enabled": false, "limit_usd": null},
  "usage": {
    "total_cost_usd": 32.50,
    "included_cost_usd": 32.50,
    "on_demand_cost_usd": 0.00,
    "budget_remaining_usd": 17.50,
    "total_operations": 85,
    "pentests": {"cost_usd": 20.00, "operations_count": 60, "pentests_count": 3},
    "chat": {"cost_usd": 12.50, "operations_count": 25}
  },
  "by_model": []
}

budget_remaining_usd may be a number, "Unlimited", "Custom", or null for a past month. The on_demand block only appears for the current month.

Daily and history

GET /usage/daily accepts ?period=30d|7d|1d (a per-day breakdown) or ?date=2026-02-15 (a per-hour breakdown). GET /usage/history is a paginated list of individual operations, each labelled Included or On-Demand:

{
  "items": [
    {
      "id": 1234,
      "date": "2026-02-15 14:30:00",
      "type": "Included",
      "model_name": "Aleex GPT-4.1",
      "agent_name": "Scanner",
      "input_tokens": 1500,
      "output_tokens": 800,
      "cost_usd": 0.0234
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 20
}

On-demand

PATCH /usage/on-demand

{"enabled": true, "limit_usd": 50.00}

enabled is required; limit_usd caps overage spend (null = no cap). With on-demand off, usage is blocked once the budget is spent; with it on, overage is billed on the next invoice up to the cap.

Team usage

Team usage lives under the team resource (owner only): GET /teams/{id}/usage/summary, daily, members, members/{memberId}, history, and PATCH /teams/{id}/usage/on-demand. See Teams API.