Skip to main content

Knowledge > Processes > Church Claim Flow

Church Claim Flow

How a pastor finds their church on PewSearch, claims it, pays for a Premium Page ($9.95/mo) or Pro Website ($19.95/mo), and gets admin access. This is PewSearch's primary conversion funnel.

State Machine​

The claim page at /claim/[slug] renders one of four views based on the state of the premium_churches record:

NO RECORD                                 STATUS = preview              STATUS = active
  |                                            |                            |
  v                                            v                            v
GenericClaimPage  --pre-checkout-->  PreviewPage  --stripe checkout-->  AlreadyActivePage
                                           |
                                   (if ?activated=true)
                                           |
                                           v
                                   ActivationSuccessPage

Step-by-Step Flow​

Phase 1: Pastor Discovers Their Church​

  1. A pastor finds their church on PewSearch in one of several ways:

    • Browses the directory at pewsearch.com/directory
    • Searches by name, city, or denomination
    • Finds their church via Google (PewSearch has 218K+ indexed church pages)
    • Gets a link from a ChurchWiseAI marketing email or ad

  2. On the church detail page (/churches/[slug]), the pastor sees:

    • A "Claim This Church" banner (if unclaimed)
    • A sticky bottom CTA on mobile
    • An upsell section showing what Premium/Pro Website includes

  3. The pastor clicks "Claim This Church" and is taken to /claim/[slug].

Phase 2: Generic Claim Page (No Premium Record)​

  1. The claim page server component loads: a. Church data from churches table (by slug). b. Premium record from premium_churches (by church_id).

  2. If no premium record exists, render GenericClaimPage with:

    • Church name and basic info (address, phone, hours)
    • Denomination-aware customization (denomination-specific placeholders via getDenomConfig)
    • A tier selection: Premium Page ($9.95/mo) or Pro Website ($19.95/mo)
    • The ClaimForm component

  3. The claim form collects:

    • Name — pastor or admin's full name (required)
    • Email — church email recommended, magic link will be sent here (required)
    • Role — dropdown: Senior Pastor, Associate Pastor, Church Administrator, Office Manager, Board Member, Worship Leader, Other (required)
    • Declaration checkbox — "I declare that I am authorized to manage this church's listing" (required)
    • Tier — Premium ($9.95) or Pro Website ($19.95), pre-selected based on URL parameter

  4. The tier can be pre-selected via the URL:

    • /claim/[slug]?tier=pro_website --> Pro Website selected
    • /claim/[slug] --> Premium selected by default

Phase 3: Pre-Checkout (Creates Preview Record + Redirects to Admin Dashboard)​

Preview-first flow (updated April 2026): The claim form now creates a premium_churches record with status='preview' immediately on submission — BEFORE Stripe checkout. The pastor is redirected to the admin dashboard with the preview banner visible. Payment is completed from the admin dashboard, not the claim page.

  1. When the pastor submits the form, the ClaimForm component sends a POST to /api/stripe/pre-checkout with:

    • church_id, name, email, role, tier

  2. The pre-checkout API performs security checks: a. CSRF origin validation. b. Rate limit: 10 attempts per 60 seconds per IP. c. Validate all required fields are present. d. Validate email format.

  3. Look up the church in the churches table. Return 404 if not found.

  4. Check for existing premium record:

    • If status = "active" --> return 409 "This church page has already been claimed by another administrator."
    • If status = "preview" and same email --> return existing preview record (no new DB write)
    • If status = "preview" and different email --> create new preview record (overwrite)
    • If no record --> create new preview record

  5. Upsert premium_churches row with status='preview':

    • Set admin_name = submitted name
    • Set admin_email = submitted email (lowercased)
    • Set preview_expires_at = now + 48 hours
    • Generate admin_token for magic-link admin access
    • Save admin_role if provided

  6. Send a preview-started email to the pastor with the admin dashboard magic link (fire-and-forget).

  7. Send a claim notification email to the ChurchWiseAI admin (fire-and-forget).

  8. Return the admin dashboard URL (/admin/[admin_token]) to the ClaimForm component.

  9. The ClaimForm redirects the browser to the admin dashboard (not Stripe checkout directly).

Phase 4: Stripe Checkout​

  1. The pastor completes payment on Stripe's hosted checkout page.

    • Enters card details.
    • Sees the price ($9.95/mo or $19.95/mo).
    • No free trial on PewSearch plans (trials are for CWA chatbot plans only).
    • Promo codes are allowed.

  2. On successful payment, Stripe redirects back to /claim/[slug]?activated=true.

  3. Stripe fires a checkout.session.completed webhook event to /api/stripe/webhook.

Phase 5: Webhook Activation​

  1. The PewSearch webhook handler validates the Stripe signature and parses the event.

  2. For checkout.session.completed: a. Extract church_id, premium_id, and tier from session metadata. b. Validate that the metadata combination is legitimate (premium_id belongs to church_id). c. Skip CWA product tiers (chatbot_starter, voice_pro, etc.) — those are handled by churchwiseai.com's webhook. d. Call activateChurch().

  3. activateChurch() performs: a. Idempotency check — if the premium record already has this stripe_subscription_id and is active, skip (prevents duplicate processing). b. Update premium record:

    • status = "active"
    • plan = tier (e.g., "premium" or "pro_website")
    • activated_at = now
    • stripe_customer_id = from Stripe
    • stripe_subscription_id = from Stripe c. Pro Website defaults (if tier is "pro_website"):
    • Set website_template = "protestant_modern"
    • Set chatbot_enabled = true d. Update churches table: set is_premium = true. e. Bust cache: revalidate /churches/[slug] and /claim/[slug] pages. If vanity_slug exists, also revalidate /s/[vanity_slug]. f. Send welcome email with magic link:
    • Uses admin_email from premium record (or retrieves from Stripe customer if missing)
    • Contains a link to pewsearch.com/admin/[admin_token]
    • Retries up to 3 times with 2-second delays between attempts
    • If all retries fail, logs a critical error (admin can recover via resend-link API)

Phase 6: Activation Success Page​

  1. When the browser loads /claim/[slug]?activated=true, the claim page detects activated=true and renders ActivationSuccessPage regardless of webhook timing (the redirect happens before the webhook may have finished).

  2. The success page shows:

    • Green checkmark with church name
    • For Pro Website: the vanity URL (pewsearch.com/s/[slug])
    • "What's next" card with 4 steps:
      • Pro Website: website is live, set up content, customize, verified badge
      • Premium: page is live, manage from admin, enable chatbot, higher search ranking
    • AI Starter Kit download link (FAITH framework PDF)
    • CTA buttons:
      • Pro Website: "Set Up Your Website" (links to admin dashboard, Website tab)
      • Premium: "View Your Church Page" (links to church detail page)

Phase 7: Preview Mode (Admin Dashboard with PreviewBanner)​

  1. After submitting the claim form, the pastor lands in the admin dashboard with status = "preview". The dashboard renders a PreviewBanner at the top:

    • Shows a countdown timer to preview_expires_at (48 hours from claim)
    • Has an "Activate Now" / "Complete Payment" CTA
    • If preview_expires_at has passed, shows an expired gate instead of the countdown

  2. To complete payment from the preview state, the dashboard calls /api/stripe/checkout-link (POST with adminToken). This endpoint:

    • Validates the token and confirms status IN ('preview', 'cancelled', 'expired', 'paused')
    • Validates the plan is a PewSearch plan (not a CWA voice/bundle)
    • Creates or retrieves a Stripe customer
    • Creates a Stripe Checkout session with the correct price
    • Returns the Stripe Checkout URL

  3. If a returning pastor visits /claim/[slug] (not the admin dashboard):

    • The claim page still renders PreviewPage for status = "preview" records
    • PreviewPage shows a countdown timer and "Activate Now" CTA
    • Clicking "Activate Now" calls /api/stripe/checkout-link the same way

Phase 8: Already Active Page​

  1. If the church already has an active paid premium record and someone else visits /claim/[slug]:
    • Render AlreadyActivePage
    • Shows: "This Church Page Is Already Managed"
    • Provides support contact link for ownership disputes
    • CTA: "View Church Page" and "Back to Directory"

Key Database Changes During Claim​

StepTableOperationKey Fields
Pre-checkoutpremium_churchesUPSERTadmin_name, admin_email, admin_role
Webhookpremium_churchesUPDATEstatus=active, plan, activated_at, stripe_customer_id, stripe_subscription_id, website_template (pro_website), chatbot_enabled (pro_website)
WebhookchurchesUPDATEis_premium=true

Error Recovery​

  • Webhook fails but redirect succeeds: The success page renders immediately on ?activated=true regardless of webhook timing. The webhook will fire asynchronously.
  • Welcome email fails: After 3 retries, a critical error is logged. The pastor can request a new magic link via /api/premium/resend-link.
  • Double claim attempt: The pre-checkout API returns 409 if the church is already active.
  • Preview expires: The preview record remains in the database. The pastor can still visit the claim page and complete checkout.