Skip to main content

Pastor connects a custom domain to their Pro Website

Persona​

A pastor on the bundled Pro Website tier ($19.95/mo) who wants gracechurch.org instead of gracechurch.john316.church. They own the domain already, have basic technical confidence (can log in to their registrar), and know what a CNAME record is. Custom domain costs $49.95 setup; annual customers get it free.

Entry points​

  1. Admin Settings tab — Settings → Domain section. Site-only tier: locked tombstone ("Custom domains available on bundled tier"). Bundled tier: "Add custom domain" form.
  2. Email offer from founder — Active bundled customers receive an email offering custom domain setup with a direct link to /admin/[token]?tab=settings#domain.
  3. Return visit — Pastor bookmarks Settings and returns after initial setup.

Click-through flow​

Steps​

  1. Navigate to Domain settings — Settings tab. Scroll to Domain section. Server-side gate: site-only tier returns null or a tombstone card; bundled tier shows the form.

  2. Review current subdomain and upsell/form — Site-only: "Your site is at [slug].john316.church" + locked icon + "Upgrade to Bundle." Bundled: current subdomain (read-only) + "Add Custom Domain" form with hint: "Custom domains cost $49.95 one-time. Annual subscribers get this free."

  3. Enter custom domain and submit — Text input (no www. or https://). Client-side regex validates domain format. POST to /api/premium/domain/add with { churchId, customDomain: 'gracechurch.org' }.

  4. Stripe charges setup fee — Monthly: stripe.invoiceItems.create() for $49.95, appended to next invoice. Annual: same item + 100% coupon applied; invoice shows the waiver. Coupon description: "Custom domain setup (annual included)."

  5. UI transitions to pending DNS; email sent — Domain section shows amber "Pending DNS" badge with CNAME instruction card: Record type CNAME, Name www, Value cname.vercel-dns.com. "Verify DNS" button (manual refresh, no auto-polling in v1). Email sent with same instructions plus GoDaddy/Namecheap screenshot examples.

  6. Verify DNS and finalize SSL — Pastor returns after propagation (typically 5 min, up to 48h), clicks "Verify DNS." GET /api/premium/domain/verify checks DNS via Vercel API. If resolved: status badge moves to "Verifying DNS…" then "SSL provisioning" (Vercel auto-provisions Let's Encrypt cert) then "Live." Final email: "Your custom domain is live! gracechurch.org is now pointing to your Pro Website."

Acceptance spec​

Canonical: knowledge/acceptance/cwa-pro-website.md (section 7 — "Domain config").

Key coverage: tier gating, subdomain default, custom domain upsell ($49.95, waived on annual), DNS validation state machine, SSL provisioning, invoice handling.

Success criteria​

  • Domain section only visible to bundled tier.
  • Adding a domain is straightforward (type domain, click Add).
  • Clear CNAME instructions via email and on-screen.
  • Setup fee appears on next invoice, or is waived if annual.
  • After DNS propagates and SSL is ready, site resolves at custom domain with HTTPS.

Known failure modes​

  • Site-only tombstone is confusing. Should include "$19.95/mo" price and what Chat Starter adds. Link to /pricing.

  • Vercel API token missing. If VERCEL_API_TOKEN env var is unset, verification fails. UI message: "We can't verify your domain right now. Please contact support@churchwiseai.com."

  • DNS propagation expectations. UI must show "DNS takes 5 min–48 hours to propagate. Check back soon" — do not let pastor think something is broken when it's just propagating.

  • Cancellation leaves domain pointing at ChurchWiseAI. Post-cancellation, the CNAME still points to Vercel infrastructure (returns 404 or fallback). Include DNS cleanup instructions in the service-ended email.

  • CNAME target typed wrong. If verification fails 3 times, proactively email: "It looks like your DNS record might be misconfigured — please reply and we can help."