Docs/Subscription
API RefKnowledgeDB.dev
Console →
Not logged in

Subscription

Manage billing, checkout, plan changes, cancellations, and usage tracking. Powered by Polar for seamless payment processing.

GET

Get Subscription

/subscription

Retrieve the current user's subscription details. Returns the subscription object or null if no subscription exists.

Response Fields

subscriptionobject | nullSubscription object with plan, status, apiKey, cancelAtPeriodEnd, period dates, createdAt, updatedAt. Null if no subscription.
// GET /subscription
// 200 OK — active subscription
{
  "subscription": {
    "plan": "starter",
    "status": "active",
    "apiKey": "abc123...",
    "cancelAtPeriodEnd": false,
    "currentPeriodStart": "2026-03-12T...",
    "currentPeriodEnd": "2026-04-12T...",
    "createdAt": "2026-03-12T...",
    "updatedAt": "2026-03-12T..."
  }
}
GET

Get Usage

/subscription/usage

Retrieve API usage statistics for the current billing period.

Response Fields

planstringCurrent plan name.
quotanumberTotal API calls allowed.
usednumberAPI calls used this period.
remainingnumberRemaining API calls.
percentUsednumberUsage percentage.
throttleobjectRate limit and burst limit.
// GET /subscription/usage
// 200 OK
{
  "plan": "professional",
  "quota": 100000,
  "used": 15420,
  "remaining": 84580,
  "percentUsed": 15.42,
  "periodStart": "2026-01-01",
  "periodEnd": "2026-02-01",
  "throttle": {
    "rateLimit": 50,
    "burstLimit": 100
  }
}
POST

Create Checkout

/subscription/checkout

Create a checkout session for subscribing to a plan. Returns a URL to redirect the user to the payment page.

Request Parameters

planstring*Plan to subscribe to (starter, professional).
successUrlstringURL to redirect after successful payment.
// POST /subscription/checkout
{
  "plan": "professional",
  "successUrl": "https://knowledgedb.dev/console/checkout/success?checkout_id={CHECKOUT_ID}"
}
POST

Confirm Checkout

/subscription/confirm

Confirm a checkout session after the user completes payment on Polar. Call this on your success page to activate the subscription and receive the new API key.

Request Parameters

checkoutIdstring*The checkout ID from the Polar redirect URL query parameter.
// POST /subscription/confirm
{
  "checkoutId": "466de8b3-d631-451d-ac6d-e6f1d595301b"
}
POST

Cancel Subscription

/subscription/cancel

Cancel the current subscription. Access continues until the end of the current billing period.

// POST /subscription/cancel
// No body required
POST

Reactivate Subscription

/subscription/reactivate

Reactivate a subscription that has a pending cancellation. Undoes cancelAtPeriodEnd so the subscription renews normally. No request body needed.

// POST /subscription/reactivate
// 200 OK
{
  "message": "Subscription reactivated. Cancellation has been undone.",
  "subscription": {
    "plan": "professional",
    "status": "active",
    "cancelAtPeriodEnd": false,
    "currentPeriodEnd": "2026-04-12T..."
  }
}
POST

Customer Portal

/subscription/portal

Get a URL to the customer billing portal where users can manage payment methods and view invoices.

// POST /subscription/portal
// 200 OK
{
  "portalUrl": "https://polar.sh/portal/..."
}
POST

Webhook

/subscription/webhook

Polar webhook endpoint for subscription events. This is called by Polar, not by your application directly.

ℹ️This endpoint is called by Polar when subscription events occur (created, updated, cancelled). You do not need to call this directly.
// POST /subscription/webhook
// Called by Polar
{
  "type": "subscription.updated",
  "data": {
    "id": "sub_xxx",
    "status": "active",
    ...
  }
}