Feature: Bills

The bills feature is a UK-only multi-step checkout flow for student utility bills packages. It lives in src/features/bills/.

Directory Structure

src/features/bills/
  actions/
    auth/
      register.ts              # User registration
    checkout/
      share-with-housemates.ts # Share quote link with housemates
      submit.ts                # Final bills signup submission
    location/
      get-addresses.ts         # Address lookup by postcode
    quote/
      get-quote.ts             # Fetch bills quote/pricing
      get-quote-prefill.ts     # Load prefilled quote data (from shared link)
    tenant/
      update-status.ts         # Update tenant status
    validation/
      email.ts                 # Email validation
  components/
    common/
      BillsFlow.tsx            # Main flow orchestrator
      ProgressTracker.tsx      # Step progress indicator
      AnimatedContent.tsx      # Step transition animations
      AnimatedButton.tsx
      QuotePrefillDialog.tsx   # Dialog for prefilled quotes
    postcode/
      PostcodeStep.tsx         # Step 1: Enter postcode
    register/
      RegisterStep.tsx         # Step 2: Personal details
      NotStudentDialog.tsx
    quote/
      QuoteStep.tsx            # Step 3: Select services
      ServiceSelection.tsx
      ServiceItem.tsx
      PricingDisplay.tsx
      InternetSpeedService.tsx
      UnlimitedWaterService.tsx
      UnlimitedEnergyService.tsx
      FreeContentsCover.tsx
      NavigationButtons.tsx
      types/QuotePrice.type.ts
    checkout/
      CheckoutStep.tsx         # Step 4: Review and submit
      HousemateDialog.tsx
      ShareDialog.tsx
      SubmissionStatusDialog.tsx
      types/SubmissionStatus.type.ts
    bills-header.tsx           # Landing page hero
    bills-faq.tsx
    bills-feature-cards.tsx
    how-it-works-section.tsx
    student-testimonials.tsx
  helpers/
    constants.ts
  hooks/

Multi-Step Flow

The checkout flow is orchestrated by BillsFlow.tsx using a step-based state machine:

Step 1: Postcode (PostcodeStep)

User enters their postcode. This is used to look up available addresses and determine pricing.

Step 2: Details (RegisterStep)

User provides personal details (name, email, phone), selects an address from the postcode lookup, and specifies tenancy dates and number of tenants.

Step 3: Quote (QuoteStep)

Displays pricing options fetched from the API. User can customize:

• Internet speed tier
• Unlimited water add-on
• Unlimited energy add-on

The quote is fetched via getQuote(postcode, bedrooms, referral) which calls GET /api/bills/quote on the v2 API.

Step 4: Checkout (CheckoutStep)

Review and submit. User can:

• Add housemate details
• Enter a referral code
• Share the quote with housemates (generates a prefill link)
• Submit the signup

Key Server Actions

getQuote(postcode, bedrooms, referral)

Fetches pricing from the v2 API at /api/bills/quote. Returns an array of QuotePrice objects and agent codes. Uses revalidate: 0 (no caching).

submitBillsSignup(formData, price, quotePrefillUuid?)

Submits the final signup to POST /api/bills/signup. Builds a tenant array with a LEAD tenant and optional HOUSEMATE tenants. Calculates the tenancy end date as 12 months minus 1 day from start if not provided.

getAddresses(postcode) (in location/)

Looks up addresses by postcode for the address picker.

shareWithHousemates(data) (in checkout/)

Shares the quote link with housemates.

Quote Prefill Flow

When a user receives a shared quote link with a ?uuid= parameter:

1. BillsFlow receives the uuid prop
2. useQuotePrefill hook loads the prefilled data
3. A QuotePrefillDialog shows the prefilled details
4. On confirmation, the flow jumps directly to the Checkout step

Route Config

The bills feature has two route entries:

"/bills": {
  mainSection: <BillsHeader />,
  isBillsPage: true,
  allowedRegions: ["uk"],
},
"/bills/quote": {
  withFooter: false,
  withHeader: false,
  allowedRegions: ["uk"],
},

The quote page hides both the header and footer to provide a full-screen checkout experience.