/v1/billing — Billing endpoints

Authenticated by user session (same JWT as /v1/keys). API keys are not accepted — billing is a user-level action, not a machine-level one.

In local mode, every endpoint returns 503 with a clean explanation. Local installs are free.

POST /v1/billing/checkout — start a Stripe Checkout

Creates a Stripe Checkout session for a paid tier.

Request

{
  "tier": "pro",
  "successUrl": "https://yourapp.com/upgraded",
  "cancelUrl": "https://yourapp.com/upgrade"
}

tier is required. Currently pro and team. successUrl and cancelUrl are optional — they default to your dashboard.

Response

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

Redirect the browser to url.

POST /v1/billing/portal — open the Stripe Customer Portal

Generates a one-time URL that opens Stripe’s customer portal for the user — change card, update plan, view invoices.

Request

{
  "returnUrl": "https://yourapp.com/dashboard"
}

Response

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

GET /v1/billing/balance — current balance and tier

Returns the user’s current credit balance, tier, period end, auto-recharge config, and (for free-tier users) an upgrade URL.

Response (cloud, paid user)

{
  "tier": "pro",
  "credits": 4823100,
  "currentPeriodEnd": "2026-05-15T00:00:00.000Z",
  "autoRechargeEnabled": true,
  "autoRechargeThreshold": 500000,
  "autoRechargeAmount": 1000000,
  "upgradeUrl": null
}

Response (cloud, free tier)

{
  "tier": "free",
  "credits": 0,
  "currentPeriodEnd": null,
  "autoRechargeEnabled": false,
  "upgradeUrl": "https://app.prxy.monster/upgrade?u=..."
}

Response (local mode)

{
  "tier": "local",
  "credits": 0,
  "currentPeriodEnd": null,
  "autoRechargeEnabled": false,
  "local": true
}

Errors