Architecture, Billing & Security FAQ
Everything you need to know about how subscriptions, feature gates, and storage work under the hood.
All checkout, customer portal, subscription cancellation, and webhook events go through BillingService and the BillingProvider adapter interface. Plans and prices are stored in the database (plan and plan_price tables), allowing you to switch providers via environment configuration without changing business logic.
By default, cancellations set cancel_at_period_end = true. Your subscription is never deleted from the database, and your paid entitlements remain active until entitled_until (the end of your current paid billing period). You can resume your subscription anytime before the cycle ends.
When an invoice.payment_failed webhook arrives, your subscription status moves to past_due and automatically enters a 3-day Grace Period (grace_period_end). During this window, your paid features remain active and you receive a Payment Failed notification email to update your payment method.
Usage is tracked independently in the usage table per UTC billing period. Quota consumption uses a single atomic SQL UPDATE statement (used + amount <= limit) so concurrent requests can never exceed plan entitlements.
Yes. When an anonymous user initiates an upload, the server sets a cryptographically signed HttpOnly cookie (anon_id) and namespaces the storage key under anonymous/{anonymousId}/{uuid}. Once the user signs in, calling POST /api/files/claim transfers ownership to their userId and clears the cookie.
No. In accordance with our server-first security model, the success redirect URL is strictly for UI feedback. Subscriptions and entitlements are only activated by signature-verified, deduplicated provider webhooks (or explicit provider API reconciliation).