Billing API

GET /api/billing/state

• Purpose: Return billing state and plan limits for the user.
• Auth: Clerk session.
• Request shape: none.
• Response shape: Plan/status + limits + period metadata.
• Key errors: 401.
• Example: GET /api/billing/state.

POST /api/billing/checkout

• Purpose: Create a Stripe Checkout session for upgrade.
• Auth: Clerk session.
• Request shape: none.
• Response shape: { url } for redirect.
• Key errors: 400 when checkout cannot be created, 401.
• Example: POST /api/billing/checkout.

POST /api/billing/portal

• Purpose: Create a Stripe Billing Portal session.
• Auth: Clerk session.
• Request shape: none.
• Response shape: { url } for redirect.
• Key errors: 401, 400.
• Example: POST /api/billing/portal.

POST /api/billing/sync

• Purpose: Force sync billing state from Stripe to local records.
• Auth: Clerk session (administrative/owner action per app policy).
• Request shape: none.
• Response shape: { ok } or sync result payload.
• Key errors: 401, 403.
• Example: POST /api/billing/sync.

POST /api/billing/webhook

• Purpose: Receive Stripe webhook events and update billing state.
• Auth: Stripe webhook signature (no Clerk session).
• Request shape: Raw Stripe payload + signature header.
• Response shape: { received: true } / { ok: true } (zavisno od handlera).
• Key errors: 400 invalid signature/payload.
• Example: Stripe webhook request with Stripe-Signature header.