Platform

Billing

CognitionDesk's billing is handled by a dedicated BillingService that supports multiple payment providers. Token usage is tracked in real time and enforced at the API level.

Payment Providers

Provider	Use case
LemonSqueezy	Primary — subscriptions, token packs, vouchers
Stripe	Enterprise — custom plans, invoices
Paddle	Global — VAT-inclusive pricing
PayPal	Alternative payment method
MercadoPago	Latin America markets

Check billing status

JSON

GET /billing/status
Authorization: Bearer <token>

// Response
{
  "plan": "pro",
  "status": "active",
  "tokensUsed": 125000,
  "tokensLimit": 500000,
  "tokensRemaining": 375000,
  "renewsAt": "2026-04-15T00:00:00Z",
  "provider": "lemonsqueezy"
}

Create a checkout

Redirect users to a LemonSqueezy checkout to upgrade their plan:

JSON

POST /billing/checkout
Authorization: Bearer <token>

{
  "planId": "plan_pro",
  "successUrl": "https://app.cognitiondesk.com/billing?success=true",
  "cancelUrl": "https://app.cognitiondesk.com/billing"
}

// Response: redirect user to checkout URL
{
  "checkoutUrl": "https://checkout.lemonsqueezy.com/checkout/buy/...",
  "sessionId": "sess_abc123"
}

Recharge tokens

Users can purchase additional token packs without changing their plan:

JSON

POST /billing/recharge-tokens
Authorization: Bearer <token>

{
  "pack": "tokens_500k",   // token pack ID
  "successUrl": "https://app.cognitiondesk.com/billing"
}

Validate vouchers

JSON

POST /billing/voucher/validate
Authorization: Bearer <token>

{
  "code": "LAUNCH25"
}

// Response
{
  "valid": true,
  "discount": { "type": "percent", "value": 25 },
  "description": "25% off for launch week"
}

Token usage

Every AI request consumes tokens. The backend enforces limits via the quotaMiddleware — requests that exceed the plan limit return 402 Payment Required.

Endpoints

Method	Endpoint	Auth	Description
GET	`/billing/status`	Firebase Token	Current plan, token usage, and renewal date
GET	`/billing/invoices`	Firebase Token	Invoice history
GET	`/billing/payment-methods`	Firebase Token	Stored payment methods
GET	`/billing/plans`	Firebase Token	Available subscription plans with pricing
GET	`/billing/analytics`	Firebase Token	Billing and usage analytics
POST	`/billing/checkout`	Firebase Token	Create LemonSqueezy checkout for plan upgrade
POST	`/billing/recharge-tokens`	Firebase Token	Create checkout to purchase token packs
POST	`/billing/voucher/validate`	Firebase Token	Validate a discount voucher code
POST	`/billing/sync`	Firebase Token	Sync usage data to BillingService
POST	`/billing/check-overage`	Firebase Token	Check if usage exceeds plan limits
POST	`/billing/webhook/upgrade`	Webhook Secret	Internal: plan upgrade webhook from BillingService
POST	`/billing/webhook/cancel`	Webhook Secret	Internal: subscription cancellation webhook
POST	`/billing/webhook/token-recharge`	Webhook Secret	Internal: token recharge webhook
POST	`/billing/webhook/lemonsqueezy`	HMAC Signature	Direct LemonSqueezy webhook (public)