ADR: Card-Backed Beta Setup With Email Queue Fallback

Date: 2026-07-03 Status: Accepted Supersedes: 2026-07-03-email-first-beta-registration-supersedes-stripe-first.md

Context

Scout needs a real self-service hosted beta path, not a shared password or a manual founder-issued key path. Earlier implementation work moved public beta to direct email registration through /v1/hosted/beta-key because production Stripe and SMTP were not configured. That kept signup safe, but it did not verify the payment, webhook, account provisioning, and email key-delivery pipeline the way a hosted SaaS beta should.

Arijit's current product direction is that beta testers should go through a card-backed $0 setup flow when the hosted billing stack is ready. If Stripe or SMTP is not yet configured, Scout should still accept beta interest through a queued email registration fallback, but that fallback is not the target steady-state beta path.

Decision

The public /beta page is the beta self-service entrypoint.

• Primary path when ready: $0 Stripe Checkout setup through /v1/billing/stripe/checkout-session with package_id=beta_trial.
• Fallback while checkout is paused: queued email registration through /v1/hosted/beta-key.
• Raw API keys are never shown in the browser.
• API keys are emailed after account/key provisioning.
• /v1/billing/stripe/status advertises the public self-service path as stripe_beta_checkout_with_email_queue_fallback.
• Production remains blocked until SMTP delivery, Stripe Checkout, Stripe webhook verification, and smoke tests are configured.

Consequences

• The prior email-first ADR is historical and superseded.
• /beta can be safely visible before Stripe is configured because it falls back to queued email registration.
• The public website must not claim beta checkout is ready until the readiness flags are green.
• Operators still need SMTP and Stripe secrets before beta key delivery and checkout can work end to end.

Evidence

Repo slice changed:

• website/beta.html
• website/assets/hosted-keygen.js
• scout/api/routers/billing.py
• docs/product/hosted-admin-operations.md
• docs/product/unit-economics-and-pricing-model-2026-06-29.md
• docs/distribution.md
• docs/product/public-hosted-launch-readiness-plan-2026-07-03.md

Verification:

• TDD red: beta website tests failed because /beta lacked data-checkout-endpoint and still advertised email-only behavior.
• Green: focused website/API/docs verification reported 61 passed.
• Pyright reported 0 errors for the touched billing surfaces.
• Ruff check and format check are clean for touched code/test files.
• Live readiness still reports health/package OK and SMTP/Stripe blockers.