core-billing-service

Handles Stripe integration for checkout sessions, subscription management, and billing builders used during onboarding. Receives Stripe webhooks for payment event processing.

Worker name: crow-core-billing-service Domain (prod): internal.billing.crowai.dev Domain (dev): dev.internal.billing.crowai.dev

Schema

billing_builder

Used during onboarding to accumulate billing preferences before creating a Stripe subscription.

Column	Type	Notes
id	text PK
organizationId	text
modules	text	JSON {"web":false,"cctv":false,"social":false}
payAsYouGo	boolean	default false
billingPeriod	text	default monthly, also annual
stripeCustomerId	text	nullable, set after checkout
stripeSubscriptionId	text	nullable, set after checkout
status	text	default draft, also active
onboardingId	text	nullable
createdAt	integer	epoch ms

subscription

Column	Type	Notes
id	text PK
organizationId	text	unique (one subscription per org)
stripeCustomerId	text
stripeSubscriptionId	text
modules	text	JSON {"web":true,"cctv":false,"social":false}
payAsYouGo	boolean
billingPeriod	text	monthly or annual
status	text	default active, also cancelled, past_due
currentPeriodStart	integer	epoch ms
currentPeriodEnd	integer	epoch ms
createdAt	integer	epoch ms
updatedAt	integer	epoch ms

Routes

Method	Path	Description
POST	/api/v1/billing/billing-builders	Create billing builder
GET	/api/v1/billing/billing-builders/{id}	Get billing builder
PATCH	/api/v1/billing/billing-builders/{id}	Update modules/period/payAsYouGo
POST	/api/v1/billing/checkout/session	Create Stripe checkout session
GET	/api/v1/billing/plans	List available plans and pricing
POST	/api/v1/billing/subscriptions	Create subscription record
GET	/api/v1/billing/subscriptions/{organizationId}	Get subscription for org
POST	/api/v1/billing/webhook	Stripe webhook endpoint (public, signature-verified)

Environment Variables

Variable	Example
ENVIRONMENT	dev
AUTH_SERVICE_URL	https://dev.internal.auth-api.crowai.dev
NOTIFICATION_SERVICE_URL	https://dev.internal.notifications.crowai.dev
AUTH_CLIENT_URL	https://dev.auth.crowai.dev
STRIPE_PRICE_ID_PRO	Stripe price ID
STRIPE_PRICE_ID_ENTERPRISE	Stripe price ID

Secrets

Secret	Purpose
BETTER_AUTH_SECRET	JWT verification
INTERNAL_GATEWAY_KEY	Gateway trust validation
STRIPE_SECRET_KEY	Stripe API authentication
STRIPE_WEBHOOK_SECRET	Stripe webhook signature verification

Bindings

Binding	Type	Name
DB	D1	crow-core-billing-service-db
R2_BUCKET	R2	crow-core-billing-service-store

Dependencies

• Inbound: gateway (billing operations), auth service (onboarding flow)
• Outbound: auth service (JWT verification), notification service (payment confirmations)

Key Behaviors

• INTERNAL_GATEWAY_KEY guard: Applied on /api/v1/billing/* middleware, runs before JWT verification
• Checkout BOLA: Checkout route requires X-Organization-Id header and validates it against the billing builder's org
• Webhook bypass: POST /api/v1/billing/webhook is public (no auth, no internal key) -- Stripe provides authentication via Stripe-Signature header
• ZodError sanitization: Validation errors return generic messages without schema details
• Modules: Three toggleable components -- web, cctv, social