Billing & usage

Subscription plans, Stripe checkout, payment history, cancellation, and per-user LLM spend. Billing endpoints are only mounted on hosted deployments (ON_PREMISE_MODE off).

Endpoints

Method	Path	Purpose
GET	/subscriptions/plans/	Available plans
POST	/subscriptions/checkout-session/	Start a Stripe checkout
POST	/subscriptions/cancel/	Cancel my subscription
GET	/subscriptions/history/	Payment history
GET	/microservices/cost-tracker/users/{username}/costs	My LLM usage and cost

GET /subscriptions/plans/

Available plans

Auth: Session token · In the app: Plans page

Response 200 — Plans (hidden plans excluded).

Array of:

Field	Type	Description
id	integer
code	string	Stable key used for checkout and UI theming.
name	string
monthly_price	number
yearly_price	number
trial_days	integer
monthly_workflow_runs	integer, nullable	null = unlimited.
included_tokens	integer, nullable
storage_bytes	integer, nullable
run_history_days	integer, nullable
live_build_sessions	integer, nullable
features	object	Feature flags keyed by feature name.
support_tier	string
is_self_serve	boolean	false = contact sales; checkout refuses it.

Example

curl -X GET "https://api.example.com/subscriptions/plans/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /subscriptions/checkout-session/

Start a Stripe checkout

Creates a Stripe Checkout session for a self-serve plan and returns its URL; redirect the user there. Stripe redirects back to the app's payment-success / payment-cancel pages. The subscription is activated by Stripe's webhook, not by the redirect.

Auth: Session token · In the app: Plans → Subscribe

Request body (application/json)

Field	Type	Required	Description
plan_code	string	no	Plan code (preferred).
plan_id	integer	no	Legacy alternative to plan_code.
interval	string ("monthly", "yearly")	no	Default: "monthly".
quantity	integer	no	Seats. Default: 1.

{
  "plan_code": "pro",
  "interval": "yearly"
}

Response 200 — Checkout URL.

Field	Type	Description
url	string (uri)

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

Response 400 — Bad interval, non-self-serve plan, or no Stripe price for that interval.

{
  "error": "path is required"
}

Response 404 — Unknown plan.

Example

curl -X POST "https://api.example.com/subscriptions/checkout-session/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_code":"pro","interval":"yearly"}'

POST /subscriptions/cancel/

Cancel my subscription

Cancels the Stripe subscription immediately and marks the local subscription inactive.

Auth: Session token · In the app: Profile → Billing → Cancel

Response 200 — Cancelled.

Field	Type	Description
message	string

{
  "message": "Subscription canceled successfully."
}

Response 404 — No active subscription.

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/subscriptions/cancel/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /subscriptions/history/

Payment history

Stripe invoices for the user's subscription.

Auth: Session token · In the app: Profile → Billing

Response 200 — Invoices.

Array of:

Field	Type	Description
id	string
amount_paid	number	In the currency's major unit.
currency	string
status	string
pdf	string (uri)

[
  {
    "id": "in_1P…",
    "amount_paid": 49,
    "currency": "usd",
    "status": "paid",
    "pdf": "https://pay.stripe.com/invoice/…"
  }
]

Response 404 — No payment history.

{
  "error": "path is required"
}

Example

curl -X GET "https://api.example.com/subscriptions/history/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/cost-tracker/users/{username}/costs

My LLM usage and cost

Token usage and cost for the signed-in user over the last days days (you may only query your own username). No trailing slash on this path.

Auth: Session token · In the app: Profile → Usage; Overview card

Path parameters

Field	Type	Required	Description
username	string	yes

Query parameters

Field	Type	Required	Description
days	integer	no	Default: 30.

Response 200 — Usage report (cost-tracker service response).

Field	Type	Description
status	string
username	string
summary	object
summary.total_cost	number
summary.request_count	integer
daily	object[]
daily[].date	string (date)
daily[].cost	number
daily[].requests	integer
by_model	object[]
by_model[].model	string
by_model[].total_cost	number
by_model[].input_tokens	integer
by_model[].output_tokens	integer

{
  "status": "ok",
  "username": "jane",
  "summary": {
    "total_cost": 12.41,
    "request_count": 318
  },
  "daily": [
    {
      "date": "2026-09-21",
      "cost": 0.82,
      "requests": 21
    }
  ],
  "by_model": [
    {
      "model": "gpt-4.1",
      "total_cost": 9.9,
      "input_tokens": 812000,
      "output_tokens": 140000
    }
  ]
}

Response 403 — Not your username.

{
  "detail": "Authentication credentials were not provided."
}

Response 503 — Cost tracker not configured.

Example

curl -X GET "https://api.example.com/microservices/cost-tracker/users/jane/costs?days=30" \
  -H "Authorization: Token $FINBLADE_TOKEN"