billt API Reference

This is billt's own subscription - your Free/Pro/Team plan for using billt itself, completely separate from the plans you sell to your end-users via /founder/projects/{id}/plans. Don't mix the two up.

{
  "plan": "free" // free | pro | team,
  "status": "ok" // ok | warning | blocked,
  "mau": 0,
  "mau_limit": 1000 // -1 = unlimited (Pro/Team),
  "project_limit": 1 // -1 = unlimited,
  "plan_renews_at": "2026-08-09T00:00:00Z" // omitted if not on a paid plan,
  "has_billing_customer": false // true once a Stripe customer exists - gates the portal link
}

status is computed from your MAU relative to your plan's limit: free plans go warning past 2x the limit and blocked past 4x. Paid plans (pro/team) are always ok regardless of MAU since they're unlimited. When blocked, every project under your account gets billing_blocked = true and their end-users are locked out until you upgrade.

Recomputes your MAU synchronously (users across all your projects who consumed usage in the last 30 days) and caches it. GET /founder/billing reads the cached value - call this first if you need a fresh number right now instead of waiting for the next scheduled recalculation.

{ "mau": 42 }

Redirects (307) to Stripe Checkout for a billt Pro or Team subscription. This is what the "Upgrade" buttons on /public/billing.html hit.

Redirects (307) to the Stripe customer billing portal - update card, view invoices, cancel or downgrade. There's no separate "downgrade" API endpoint; cancellation here is what drops you back to Free (handled via the customer.subscription.deleted webhook event below).

Registered once in the Stripe Dashboard against BILLT_STRIPE_WEBHOOK_SECRET - this is billt's own webhook for its own subscriptions, not to be confused with the per-project /sdk/payments/webhook/{project_id} above. Idempotent - replays of the same event ID are skipped.

[
  {
    "id": "uuid",
    "public_id": "uuid",
    "founder_id": "uuid",
    "name": "My SaaS",
    "redirect_url": "https://app.com/auth/callback",
    "google_client_id": "xxx.apps.googleusercontent.com",
    "billy_api_key": "billt_xxx" // hashed key, not the raw secret,
    "allowed_origins": ["https://app.com"]
  }
]

google_client_secret, stripe_secret_key, stripe_webhook_secret are never returned in JSON - they're write-only fields.

{ "project_name": "My SaaS" }

Creates the project and its default free plan (price 0, empty credits/features) atomically. Edit the free plan afterwards to actually grant credits.

{
  "project_id": "uuid",
  "api_key": "billt_xxxxxxxxxxxx"
}

{
  "redirect_url": "https://app.com/auth/callback",
  "google_client_id": "xxx.apps.googleusercontent.com",
  "google_client_secret": "GOCSPX-...",
  "stripe_secret_key": "sk_live_...",
  "stripe_webhook_secret": "whsec_...",
  "allowed_origins": ["https://app.com"]
}

Secrets are encrypted at rest. Leave a field empty/omitted to keep its current value - empty string never overwrites an existing secret.

204 No Content

Cascades to all users, plans, credit balances and payments belonging to this project. Not reversible.

204 No Content

[
  {
    "id": "uuid",
    "project_id": "uuid",
    "stripe_price_id": "price_1ABC...",
    "name": "pro",
    "price": 2900 // cents,
    "currency": "usd",
    "billing_interval": "month" // month | year | one_time,
    "credits": { "api_calls": 10000 },
    "features": { "priority_support": true },
    "archived": false
  }
]

{
  "name": "pro",
  "price": 2900,
  "currency": "usd",
  "billing_interval": "month",
  "credits": { "api_calls": 10000 },
  "features": { "priority_support": true }
}

"uuid"  // just the new plan's id, as a raw JSON string

{
  "name": "pro",
  "billing_interval": "year",
  "credits": { "api_calls": 20000 },
  "features": { "priority_support": true }
}

{ // full updated plan object, same shape as list }

This sets archived = true, it does not hard-delete the row - existing subscribers keep resolving to it (e.g. on renewal webhooks), it just disappears from GET /sdk/plans so new users can't pick it.

204 No Content

This is a browser redirect endpoint reached by public_project_id (safe to expose client-side), not your secret X-API-Key. Find public_id in the project list response.

GET /sdk/auth/login?public_project_id=3fa1...c2e

Creates or finds the user, issues a one-time login_code, then redirects the browser to your project's configured redirect_url:

your_redirect_url?code=<login_code>

Your frontend should pick up code from the query string and immediately send it to your own backend to exchange for tokens (next endpoint) - never expose your X-API-Key in frontend JS to do this exchange directly.

Despite being a GET, this endpoint reads a JSON body - a raw JSON string, not an object:

"the_login_code_from_the_redirect"

The code is single-use and short-lived; a second exchange attempt returns 401.

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ..."
}

{ "refresh_token": "eyJ..." }

{
  "user_access_token": "eyJ...",
  "user_refresh_token": "eyJ..."
}

{ "refresh_token": "eyJ..." }

200 OK

{
  "user_id": "uuid",
  "user_email": "user@example.com",
  "plan": "pro",
  "payment_status": "active",
  "features": { "priority_support": true }
}

features comes straight from the resolved plan's features map - use it to gate UI/functionality client-side without a separate entitlement call. It's null if the plan can't be resolved.

payment_status reflects the user's Stripe subscription health: "active" (no payment problem) or "past_due" (a renewal payment failed and Stripe is retrying). During past_due the user keeps access - surface an "update your card" prompt. If retries ultimately fail, the user is downgraded to free and reset to "active".

No X-API-Key and no founder token needed - safe to call from a public pricing page. Returns only non-archived plans.

[
  {
    "id": "uuid",
    "name": "pro",
    "price": 2900,
    "currency": "usd",
    "billing_interval": "month",
    "credits": { "api_calls": 10000 },
    "features": { "priority_support": true }
  }
]

Redirects (307) to the Stripe Checkout page for the given plan. Checkout mode is picked automatically from the plan: subscription for month/year plans, payment for one_time plans.

On success/cancel, Stripe redirects back to your project's redirect_url with ?checkout=success or ?checkout=cancel appended.

Point your Stripe Dashboard → Webhooks at this URL (per-project, note the {project_id} path segment). Verified against the project's stripe_webhook_secret. Idempotent - replays of the same event ID are skipped.

{ "credit_key": "api_calls", "amount": 1 }

amount defaults to 1 if omitted or ≤ 0. The bucket for credit_key is lazily created on first use, sized to the user's current plan grant.

{ "remaining": 9999 }

insufficient credits

can't resolve plan / plan "free" has no credit "api_calls"

[
  {
    "user_id": "uuid",
    "project_id": "uuid",
    "credit_key": "api_calls",
    "balance": 9999,
    "period_end": "2026-08-01T00:00:00Z"
  }
]

Use for uptime monitoring (UptimeRobot, etc.).

{ "status": "ok", "db": "ok" }

{ "status": "error", "db": "unreachable" }