Billing & Subscription Pipeline

Environment Reality (read this first)

Website (dev.lucidpal.pages.dev) is not a true dev environment — CI builds it with defaultConfiguration: production (environment.prod.ts), so it calls api.lucidpal.app (production lucidpal-api). The dev API (api-dev.lucidpal.app) is not used by the website at all.

iOS app (DEBUG / TestFlight) is a true dev environment — APIEnvironment.swift defaults isDev = true, routing to api-dev.lucidpal.app. Developers can toggle this in-app; the preference is persisted in App Group UserDefaults. App Store builds compile out the dev URL entirely.

The licensing-service dev worker (api-dev.lucidfabrics.com) and production worker (api.lucidfabrics.com) share the same D1 database and KV namespace — there is no data isolation between them.

Layer Matrix

Layer	Dev	Production	Notes
Website	dev.lucidpal.pages.dev	lucidpal.app	CI uses nx build with defaultConfiguration: production — both deploys use the same binary
Angular env file	environment.prod.ts	environment.prod.ts	Both use prod config — website dev calls prod API
iOS app (DEBUG/TF)	api-dev.lucidpal.app (default, toggleable)	api.lucidpal.app	APIEnvironment.swift — defaults isDev = true; toggle persisted in App Group UserDefaults
iOS app (App Store)	—	api.lucidpal.app	api-dev URL not compiled in for App Store builds (#else branch)
LucidPal API	api-dev.lucidpal.app (lucidpal-api)	api.lucidpal.app (lucidpal-api-production)	Dev API is actively used by iOS DEBUG/TestFlight builds
Licensing service	api-dev.lucidfabrics.com (licensing-api)	api.lucidfabrics.com (licensing-api-production)	Shared DB — no isolation
D1 — lucidpal-api	lucidpal-db-dev (ab5eccf6)	lucidpal-db (338c0725)	Separate ✓
KV — lucidpal-api	3ce605504ebf460e	69c4028e55b6432a	Separate ✓
R2 — lucidpal-api	lucidpal-assets-dev	lucidpal-assets	Separate ✓
D1 — licensing-service	licensing-db (6ee8eb93)	licensing-db (6ee8eb93)	SAME DB ⚠️
KV — licensing-service	f38bec7e60c84889	f38bec7e60c84889	SAME KV ⚠️
Stripe	LucidPal account — test key (sk_test_51TRaAI…)	LucidPal account — live key not set yet	Swap sk_live_ at launch

Bindings — lucidpal-api (both workers)

Defined in wrangler.toml. Not secrets — set at deploy time, not via wrangler secret put.

Binding	Type	Dev value	Prod value
DB	D1 database	lucidpal-db-dev	lucidpal-db
SESSIONS	KV namespace	3ce605504ebf460e	69c4028e55b6432a
ASSETS	R2 bucket	lucidpal-assets-dev	lucidpal-assets
TRANSCRIPTION_SESSION	Durable Object	TranscriptionSession	same
SYNC_SESSION	Durable Object	SyncSession	same
ENVIRONMENT	var ([vars])	"development"	"production"

ENVIRONMENT = "development" bypasses subscription checks in AI and Agent services — used for local wrangler dev only.

Payment Flow

Web (Stripe)

User clicks Subscribe
  → POST /billing/checkout  (lucidpal-api)
      → GET /api/pricing?product=lucidpal   (licensing-service) — resolves Stripe priceId from DB
      → POST /api/stripe/checkout           (licensing-service) — creates Stripe Checkout Session
  → browser redirects to Stripe hosted checkout page
      → user pays
      → Stripe sends webhook → POST /api/webhooks/stripe (licensing-service) → updates licensing-db
  → browser redirects to {origin}/#subscription-success
  → /billing/status polling picks up updated state (polls at 3s + 8s post-redirect)

iOS US + EU (Stripe)

User taps "Subscribe via Web" in UpgradeView
  → StoreKitManager.createStripeCheckout() → POST /billing/checkout  (lucidpal-api)
      No Origin header sent — appUrl falls back to APP_URL (https://lucidpal.app in prod)
      successUrl = https://lucidpal.app/#subscription-success
  → UIApplication.shared.open(stripeURL)  ← opens Stripe in default Safari browser
      → user pays in Safari
      → Stripe sends webhook → licensing-service → updates licensing-db
  → user switches back to app
  → refreshEntitlement() called immediately + after 2s delay
  → UpgradeView dismisses when entitlement is no longer .free

No deep link. iOS Stripe opens in external Safari. The app polls twice (not 6×4s — that is the website's polling schedule). The lucidpal://payment/* scheme is not used.

iOS Rest of World (Apple IAP)

User taps "Get [Plan]" in UpgradeView
  → StoreKit.Product.purchase()
      → Apple servers verify payment
      → Transaction.updates listener fires with VerificationResult
  → StoreKitManager.verifyWithBackend(jwsTransaction:transactionId:)
      → POST /billing/apple/verify  (lucidpal-api, authenticated)
          → decodes JWS payload (no Apple server call — client-side decode only)
          → upserts subscriptions row in lucidpal-db
  → transaction.finish()
  → premiumManager.refreshEntitlement()

Apple also sends server-side notifications:

Apple → POST /billing/apple/notifications  (lucidpal-api, NO auth — Apple calls directly)
    → decodes signedPayload
    → updates subscription status in lucidpal-db

successUrl / cancelUrl

Derived from the Origin request header on POST /billing/checkout (falls back to APP_URL env var).

Context	Success URL	Cancel URL
Web	{origin}/#subscription-success	{origin}/#pricing
iOS Stripe	https://lucidpal.app/#subscription-success (APP_URL fallback — no Origin header from URLSession)	https://lucidpal.app/#pricing

iOS Payment Region

StoreKitManager.paymentRegion (in StoreKitManager.swift):

Region	Method	Country codes
🇺🇸 US	Stripe	"US"
🇪🇺 EU + EEA	Stripe	AT BE BG HR CY CZ DK EE FI FR DE GR HU IE IT LV LT LU MT NL PL PT RO SK SI ES SE + NO IS LI
Rest of world	Apple IAP	All other Locale.current.region codes

static var paymentRegion: PaymentRegion {
    let code = Locale.current.region?.identifier ?? ""
    if code == "US" || euRegionCodes.contains(code) { return .stripe }
    return .apple
}

EU routes to Stripe already (EU Digital Markets Act entitlement active). The old doc note "EU: Apple IAP only (currently)" was stale.

Apple IAP Product IDs

Defined in StoreKitService.swift and apple-billing.service.ts:

Plan	Monthly product ID	Yearly product ID
starter	app.lucidpal.starter.monthly	app.lucidpal.starter.yearly
pro	app.lucidpal.pro.monthly	app.lucidpal.pro.yearly
ultimate	app.lucidpal.ultimate.monthly	app.lucidpal.ultimate.yearly

PRODUCT_TO_PLAN in apple-billing.service.ts maps these to SubscriptionPlan values.

Stripe Account (LucidPal — dedicated)

Created 2026-04-29. Separate from BitBonsai. Owned by W M Solutions Inc.

Field	Value
Account ID prefix	51TRaAI7
Stripe product	prod_UQRg3WxkmYkn43
Current key type	sk_test_… (sandbox)
Go-live action	wrangler secret put STRIPE_SECRET_KEY --env production with sk_live_…

Old price IDs with ApElOUGi6b prefix (BitBonsai account) are invalid. Do not use.

Stripe Price IDs

Stored in licensing-db.pricing_tiers. Created and updated via the licensing admin portal publish flow — never hardcode. Query GET /api/pricing?product=lucidpal for current values.

Plan	DB tier name	Monthly	Yearly
starter	STARTER	price_1TRanG77vQU9Tdum6jqQpd2A	price_1TRanH77vQU9TdumsWcgKq9X
pro	PRO	price_1TRanL77vQU9TdumJxoE41W4	price_1TRanL77vQU9TdumSPBdvSp8
ultimate	ULTIMATE	price_1TRanN77vQU9TdumxTzuwLX6	price_1TRanO77vQU9TdumhkxOKgF3

billing.service.ts maps frontend plan names to DB tier names via PLAN_TO_TIER: starter → STARTER, pro → PRO, ultimate → ULTIMATE. Lookup is case-insensitive (toUpperCase()).

Stripe Webhook (production licensing worker)

Field	Value
Endpoint	https://api.lucidfabrics.com/api/webhooks/stripe
Webhook ID	we_1TRavP77vQU9TdumfmouB78O
Events	checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.payment_failed
Secret	STRIPE_WEBHOOK_SECRET on licensing-api-production

Dev licensing worker (licensing-api) has no webhook configured — it shares the production DB so Stripe events from sandbox checkouts are written to the same tables. This is intentional for now.

Secrets — lucidpal-api (dev worker → api-dev.lucidpal.app)

Secret	Value
LICENSING_API_URL	https://api-dev.lucidfabrics.com
LICENSING_API_KEY	admin key (X-Admin-Key header)
LICENSING_PRODUCT_ID	lucidpal-dev-001 (TBC — verify in Cloudflare dashboard)
APP_URL	https://dev.lucidpal.pages.dev
GOOGLE_CLIENT_ID	1074612045085-q3mqvpt342ud5juiuu5q2bm69ton8u9n.apps.googleusercontent.com
JWT_SECRET	set
GEMINI_API_KEY	set
DEEPGRAM_API_KEY	set
LOOPS_API_KEY	set
APPLE_CLIENT_ID	set
APNS_KEY_ID	set
APNS_TEAM_ID	set
APNS_PRIVATE_KEY_BASE64	set
APNS_BUNDLE_ID	set

Secrets — lucidpal-api-production (prod worker → api.lucidpal.app)

Secret	Value
LICENSING_API_URL	https://api.lucidfabrics.com
LICENSING_API_KEY	admin key (X-Admin-Key header)
LICENSING_PRODUCT_ID	lucidpal-prod-001
APP_URL	https://lucidpal.app
GOOGLE_CLIENT_ID	1074612045085-q3mqvpt342ud5juiuu5q2bm69ton8u9n.apps.googleusercontent.com
JWT_SECRET	set
GEMINI_API_KEY	set
DEEPGRAM_API_KEY	set
LOOPS_API_KEY	set
APPLE_CLIENT_ID	set
APNS_KEY_ID	set
APNS_TEAM_ID	set
APNS_PRIVATE_KEY_BASE64	set
APNS_BUNDLE_ID	set

Secrets — licensing-api (dev worker → api-dev.lucidfabrics.com)

Secret	Value
STRIPE_SECRET_KEY	sk_test_51TRaAI… (LucidPal sandbox)
JWT_SECRET	set
ADMIN_API_KEY	set
ENCRYPTION_KEY	set
ED25519_PRIVATE_KEY	set
ED25519_PUBLIC_KEY	set
CLOUDFLARE_ANALYTICS_TOKEN	set
STRIPE_WEBHOOK_SECRET	not set — dev worker has no webhook endpoint

Secrets — licensing-api-production (prod worker → api.lucidfabrics.com)

Secret	Value
STRIPE_SECRET_KEY	sk_test_51TRaAI… → swap to sk_live_… at launch
STRIPE_WEBHOOK_SECRET	whsec_pcsN6jLwkk…
JWT_SECRET	set
ADMIN_API_KEY	set
ENCRYPTION_KEY	set
ED25519_PRIVATE_KEY	set
ED25519_PUBLIC_KEY	set
CLOUDFLARE_ANALYTICS_TOKEN	set

CORS Origins

lucidpal-api (both dev and prod)

Allowlist in src/index.ts:

https://lucidpal.app
https://app.lucidpal.app
http://localhost:4600
https://dev.lucidpal.pages.dev

licensing-api (dev worker) — wrangler.toml [vars]

https://admin.lucidfabrics.com
https://lucidpal.app
https://lucidfabrics.com
https://licensing-admin-d5k.pages.dev
http://localhost:4204
https://dev.licensing-admin-d5k.pages.dev
https://dev.lucidpal.pages.dev

licensing-api-production — wrangler.toml [env.production.vars]

https://admin.lucidfabrics.com
https://lucidpal.app
https://lucidfabrics.com
https://dev.lucidpal.pages.dev

GCP OAuth — Google Sign-In

Field	Value
Client ID	1074612045085-q3mqvpt342ud5juiuu5q2bm69ton8u9n.apps.googleusercontent.com
Authorized JS origins	https://lucidpal.app, http://localhost:4600, https://dev.lucidpal.pages.dev
Used in	Angular environment.*.ts (all three) + GOOGLE_CLIENT_ID secret on both lucidpal-api workers

Admin Portal — Licensing Service

Environment	URL
Dev preview	https://dev.licensing-admin-d5k.pages.dev
Production	https://licensing-admin-d5k.pages.dev / https://admin.lucidfabrics.com

To republish pricing tiers after a Stripe account change:

1. Clear old price IDs in DB: UPDATE pricing_tiers SET stripe_price_id_monthly=NULL, stripe_price_id_yearly=NULL, is_active=0 WHERE ...
2. Update stripe_product_id on the product row to match the new Stripe account
3. Log in to admin portal → LucidPal pricing → publish each tier

Feature Gates

These are not stable facts. Tier boundaries and feature assignments change as the product evolves. This doc describes the mechanism; the code is the source of truth.

Two enforcement layers:

Layer	File	When to change
iOS UI gating	apps/lucidpal-ios/Sources/Models/FeatureGate.swift — requiredTier switch	Moving a feature between tiers
API enforcement	apps/lucidpal-api/src/middleware/requirePlan.ts — requirePlan(minPlan)	Protecting an endpoint
API service checks	AiService.checkChatAccess(), AgentService.assertPaidPlan()	Cloud AI / agent plan requirements

iOS vs API discrepancy by design: iOS gates (FeatureGate.swift) may be stricter than the API. Trial and promotional flows can grant API access below the iOS-gated tier. When adjusting a tier boundary, update both files and keep them in sync.

Features bypassing FeatureGate

Some features are intentionally always-on in PremiumManager without going through FeatureGate.swift. These are unconditional var canUseX: Bool { true } properties.

Property	Reason
canUseDataExport	Data export is free for all users — no tier gate
canUseVision	On-device, no cloud cost
canUseLiveActivities	On-device, no cloud cost
canUseAirpodsAutoVoice	On-device, no cloud cost
canUseProactiveAI	On-device, no cloud cost
canUseAgent	On-device agent is free
canUseContinuousAgent	On-device, no cloud cost

When a feature moves from gated to always-free: remove the FeatureGate case, change the PremiumManager property to { true }, and update the UI to remove the upgrade prompt.

Credit & Rate Limits

Not hardcoded in this doc — check the source. Limits are defined in code and change independently per tier as the product evolves.

Cloud AI Chat — monthly credits

• Mechanism: KV key cloud_msg:{userId}:{YYYY-MM} (60-day TTL)
• Source of truth: MONTHLY_LIMIT map in apps/lucidpal-api/src/services/ai.service.ts
• Behaviour: HTTP 402 = no eligible plan; HTTP 429 = monthly cap hit
• iOS client: PremiumManager.creditsRemaining decremented optimistically on each message. The server does not return this value in /billing/status — the iOS BillingStatusResponse decodes creditsRemaining as Int? and always gets nil. Client count is the only display value.

Cloud Agent (/agent/chat) — daily turns

• Mechanism: KV key gemini_agent:{userId}:{YYYY-MM-DD} (48h TTL)
• Source of truth: DAILY_LIMIT map in apps/lucidpal-api/src/services/agent.service.ts
• Behaviour: HTTP 429 = daily cap hit
• /agent/synthesize has no daily rate limit — only the paid-plan check.

When you change a limit: update the constant in the service file, deploy the worker, done. No DB migration, no admin portal action required.

Agent Synthesis (/agent/synthesize)

Single-turn non-streaming Gemini call for paid tiers after on-device tool data is gathered.

• HTTP 402 = no paid subscription (assertPaidPlan)
• HTTP 503 = GEMINI_API_KEY not set
• No rate limit on this endpoint (unlike /agent/chat)
• maxOutputTokens: 512 for synthesize, 1024 for chat

subscriptions Table (lucidpal-db)

Column	Type	Notes
id	text PK
user_id	text FK	→ users.id (cascade delete)
stripe_customer_id	text	unique; set after first Stripe checkout
stripe_subscription_id	text	unique; set by webhook
apple_original_transaction_id	text	unique; set by /billing/apple/verify
payment_source	text	'stripe' | 'apple'
plan	text	'free' | 'starter' | 'pro' | 'ultimate'
billing_period	text	'monthly' | 'yearly' | null
status	text	'active' | 'inactive' | 'canceled' | 'past_due'
current_period_end	text	ISO datetime; null until webhook fires

Status Caching & Webhook Latency

GET /billing/status reads D1 (cached row). Background waitUntil syncs fresh state from licensing-service — eventual consistency ~1–2s lag after webhook.

Stripe → POST /api/webhooks/stripe (licensing-service) → updates licensing-db
       → lucidpal-api /billing/status background sync → updates lucidpal-db
       → next /billing/status call returns updated state

Client	Post-payment polling schedule
Web	3s + 8s after redirecting to #subscription-success
iOS Stripe	refreshEntitlement() immediately + after 2s delay
iOS IAP	refreshEntitlement() after transaction.finish()

Latency: 5–20s from payment to D1 update.

Go-Live Checklist

• [ ] Set STRIPE_SECRET_KEY to sk_live_… on licensing-api-production
• [ ] Register live Stripe webhook → get new whsec_… → set STRIPE_WEBHOOK_SECRET on licensing-api-production
• [ ] Republish all LucidPal pricing tiers via admin portal (creates live Stripe prices)
• [ ] Verify LICENSING_PRODUCT_ID is correct on both lucidpal-api workers (lucidpal-dev-001 / lucidpal-prod-001)
• [ ] Register Apple IAP product IDs in App Store Connect (app.lucidpal.*.monthly/yearly)
• [ ] Separate licensing-service dev DB from prod DB (currently shared — risk of test data contamination)

Cloudflare Infrastructure — LucidPal Resources

Cloudflare account is shared (W M Solutions Inc. — account ID eab661fba6c6a4d2e11c090abd0a811b). LucidPal-specific resources are listed below. A buyer would need all of these transferred.

Workers (licensing-service)

Worker name	Purpose	Domain
licensing-api	Dev/staging licensing worker	api-dev.lucidfabrics.com
licensing-api-production	Production licensing worker	api.lucidfabrics.com

Workers (lucidpal-api)

Worker name	Purpose	Domain
lucidpal-api	Dev/staging API worker	api-dev.lucidpal.app
lucidpal-api-production	Production API worker	api.lucidpal.app

D1 Databases

Binding	Name	ID	Shared?
DB	licensing-db	6ee8eb93-ba1a-46da-a7c9-6eb648bb4a2e	Dev+prod share same DB ⚠️
DB	lucidpal-db	338c0725-…	Production only
DB	lucidpal-db-dev	ab5eccf6-…	Dev only

KV Namespaces

Binding	Purpose	ID	Shared?
SESSIONS	licensing session KV	f38bec7e60c84889	Dev+prod share ⚠️
CACHE	lucidpal-api KV (prod)	69c4028e55b6432a	Prod only
CACHE	lucidpal-api KV (dev)	3ce605504ebf460e	Dev only

R2 Buckets

Binding	Bucket name	Purpose
ASSETS	lucidpal-assets	Prod: user uploads, avatars
ASSETS	lucidpal-assets-dev	Dev: user uploads
EXPORT_BUCKET	licensing-exports	Prod: product data export snapshots
EXPORT_BUCKET	licensing-exports-dev	Dev: export snapshots

Pages Deployments

Project name	URL	Repo branch
lucidpal	lucidpal.app	main
lucidpal (dev)	dev.lucidpal.pages.dev	main
licensing-admin-d5k	dev.licensing-admin-d5k.pages.dev	main

DNS Zones

Domain	Registrar	Notes
lucidpal.app	Cloudflare	All DNS managed in Cloudflare
lucidfabrics.com	Cloudflare	Shared with BitBonsai — do NOT transfer whole zone

lucidfabrics.com hosts both LucidPal (api.lucidfabrics.com) and BitBonsai records. A buyer of LucidPal only needs the api.lucidfabrics.com subdomain migrated to their own domain, not the full zone transfer.

Product Isolation & Export Playbook

All licensing-service data is scoped to a productId. LucidPal's product ID is lucidpal-default-01 (dev) and lucidpal-prod-001 (production) — set as LICENSING_PRODUCT_ID secret on lucidpal-api.

The export feature (POST /api/admin/export/trigger) produces a ZIP-compatible JSON snapshot of all product-scoped data stored in R2 (licensing-exports bucket). A buyer can use this snapshot to bootstrap their own licensing-service instance.

Exported tables: product, pricing_tiers, promo_codes, licenses, license_activations, webhook_events, audit_log.

Not exported (global / not product-scoped): admin_users, email_templates, app_config, donations.

See ~/git/licensing-service/PRODUCT_ISOLATION_PLAN.md for the full isolation and export plan.

---

Retention / Cancellation Flow

How It Works

When a user taps Manage Subscription in the app, PremiumService.showManageSubscriptions() calls Billing.showManageSubscriptions() → StoreKit 2's AppStore.showManageSubscriptions(in: scene). Apple presents the native subscription management sheet. If the user taps Cancel Subscription, Apple automatically shows the Retention Messaging UI configured in App Store Connect — no additional app code required.

Manage Subscription UI

ManageSubscriptionComponent (apps/lucidpal-mobile/src/app/features/premium/manage-subscription.component.ts) is a bottom sheet (75% height) that shows:

Element	Condition
Current plan name + tier color	Always
Credits remaining	When creditBalance > 0
Upgrade note	When tier === 'free'
Manage Subscription button	iOS + active subscription
Upgrade to Starter button	Free tier only

The component emits dismissed (closes) and upgradeRequested (opens paywall).

Entry points:

• Settings page → Account section → "Manage Subscription" row (existing, direct action)
• Left sidebar → App section → Subscription item → dispatches lp-open-subscription window event → settings component @HostListener('window:lp-open-subscription') sets showManageSubscription = true

App Store Connect — Subscription Group

Group: LucidPal Premium (ID: 22027381)
App ID: 6761450212

Subscription	Product ID	ASC ID
Starter Monthly	app.lucidpal.starter.monthly	6762061454
Starter Yearly	app.lucidpal.starter.yearly	6762058254
Pro Monthly	app.lucidpal.pro.monthly	6762061476
Pro Yearly	app.lucidpal.pro.yearly	6762057544
Ultimate Monthly	app.lucidpal.ultimate.monthly	6762060367
Ultimate Yearly	app.lucidpal.ultimate.yearly	6762059573

Promotional Offers — Apple Retention Messaging

Promotional offers are configured per-subscription in App Store Connect under Subscription Prices → Promotional Offers. Apple surfaces them natively at cancellation.

Offer structure:

Tier	Offer ID	Type	Value	Duration
Starter Monthly	app.lucidpal.starter.monthly.retention.1mfree	Free	$0	1 month
Starter Yearly	app.lucidpal.starter.yearly.retention.1mfree	Free	$0	1 month
Pro Monthly	app.lucidpal.pro.monthly.retention.50pct	Pay as you go	50% off	2 months
Pro Yearly	app.lucidpal.pro.yearly.retention.50pct	Pay as you go	50% off	2 months
Ultimate Monthly	app.lucidpal.ultimate.monthly.retention.50pct	Pay as you go	50% off	3 months
Ultimate Yearly	app.lucidpal.ultimate.yearly.retention.50pct	Pay as you go	50% off	3 months

Note: Promotional offers on native subscription management sheets require no app-side code. The offer appears in Apple's native cancellation flow automatically once configured in App Store Connect.

Review Information Screenshot

All 6 subscriptions require a Review Information Screenshot in App Store Connect before going live. Upload a paywall screenshot to each subscription → Review Information → Screenshot. This is what causes "Missing Metadata" in the subscription list.