Billing API

The billing service manages credits, orders, subscriptions, check-in, and payment processing.

Credits

Get Balance

GET /credits/balance

Response:

{
  "success": true,
  "data": {
    "balance": 1500
  }
}

Get Transactions

GET /credits/transactions?limit=20&offset=0

Response:

{
  "success": true,
  "data": [
    {
      "id": "txn-id",
      "type": "ai_usage",
      "amount": -50,
      "description": "AI chat completion (gpt-4)",
      "created_at": "2026-04-15T10:00:00Z"
    }
  ]
}

Orders

List Orders

GET /orders?limit=20&offset=0

Get Order

GET /orders/:id

Subscriptions

Get Plans

GET /subscription/plans

Returns all available subscription plans:

{
  "success": true,
  "data": [
    {
      "id": "plan-id",
      "name": "Pro",
      "description": "For growing teams",
      "price_monthly": 999,
      "price_yearly": 9990,
      "credits_included": 10000,
      "features": ["Unlimited AI chat", "Priority support"]
    }
  ]
}

Check-in

Daily Check-in

POST /checkin

Awards daily free credits. Returns error if already checked in today.

Payment

Create Payment Session

POST /payment/create-session

{
  "channel": "stripe",
  "type": "subscription",
  "plan_id": "plan-id",
  "success_url": "https://example.com/dashboard/subscription?success=true",
  "cancel_url": "https://example.com/dashboard/subscription"
}

Creates a checkout session with the specified payment provider and returns a redirect URL.

Notes:

• Stripe subscriptions use the plan’s Stripe price identifiers.
• Creem checkouts are product-backed. For Creem flows, plan_id must reference a billing plan that has creem_product_id configured in admin.

Manage Subscription

POST /subscription/portal

{
  "return_url": "https://example.com/dashboard/subscription"
}

Creates a provider-backed billing portal session and returns a redirect URL.

Webhooks

POST /payment/webhook/stripe
POST /payment/webhook/creem

Payment provider webhook endpoints. These are public (no session required) and verify webhook signatures internally.

Admin Endpoints

Plans Management

Method	Path	Description
GET	/admin/billing/plans	List all plans
POST	/admin/billing/plans	Create a plan
PUT	/admin/billing/plans/:id	Update a plan

Coupons

Method	Path	Description
GET	/admin/billing/coupons	List coupons
POST	/admin/billing/coupons	Create a coupon

Credit Administration

Method	Path	Description
GET	/admin/credits/transactions	List all transactions
POST	/admin/credits/manual	Manual credit adjustment

Check-in Configuration

Method	Path	Description
GET	/admin/checkin/config	Get check-in config
PUT	/admin/checkin/config	Update check-in config