Billing API
The Billing service manages subscriptions, entitlements, and Stripe integration for GospeLib's freemium model.
This API reference will be auto-generated from services/billing/api/openapi.yaml using docusaurus-plugin-openapi-docs once the OpenAPI spec is created. The content below is a high-level summary.
What This API Covers
Plans & Pricing
- GET /api/v1/billing/plans — List available subscription plans and pricing
Subscription Management
- GET /api/v1/billing/subscription — Retrieve the current user's subscription details
- POST /api/v1/billing/checkout — Create a Stripe Checkout session for plan purchase
- POST /api/v1/billing/portal — Create a Stripe Customer Portal session for self-service management
Entitlements
The Billing service determines which features a user can access based on their subscription tier:
| Tier | Features |
|---|---|
| Reader (free) | Basic passage reading, search, topical guide |
| Scholar ($79.99/yr) | Interlinear text, manuscript witnesses, expanded AI |
| Academic ($149.99/yr) | Full scholarly tools, bulk export, API access |
Entitlement data is cached in Redis with a 60-second TTL. The gateway checks entitlements via Redis — it never calls the Billing service in the hot path.
Stripe Webhooks
- POST /api/v1/billing/webhook — Receives Stripe webhook events (subscription created, updated, canceled, payment succeeded/failed)
Webhook payloads are verified using Stripe's signing secret. Idempotency keys are stored in PostgreSQL to prevent duplicate processing.
Authentication
/api/v1/billing/plans is public. All other endpoints require a valid Bearer token. The webhook endpoint uses Stripe signature verification instead of JWT auth.