Title

Referral

Functional Requirement Document

BA & Ideation: Deval Chauhan

Reviewed By: KG (Project Manager)

Updated Date: 1 December 2025
Status:

Version 1.0

1. Referral System for Pixally User

Functional Requirements Document (FRD)

Referral System for Pixally User

1. Module Overview

Module Name

Referral System for Pixally User

Purpose

The Referral System module enables existing Pixally subscribers (Studio/Agency owners) to earn monetary rewards by referring new customers to Pixally through a unique referral link. The module provides users with referral tools, earnings tracking, payout management, and detailed visibility into their referral history and subscription receipts.

Business Goals

• Incentivize existing Pixally users to promote the platform and acquire new customers through word-of-mouth marketing.
• Provide transparent tracking of referral earnings with milestone-based or flat payout structures depending on the referred user's subscription plan.
• Increase user engagement and retention by rewarding advocacy and successful referrals.
• Establish a clear revenue-sharing mechanism that aligns with Pixally's subscription business model.

2. User Roles & Permissions

Roles with Access

• Agency Owner: Only the Agency Owner has access to the Referral System module. This role is the primary account holder with full administrative privileges over the agency account.

Roles WITHOUT Access

• Admins: Agency admins do NOT have access to the Referral System. The module is completely hidden from their view.
• Team Members: Team members do NOT have access to the Referral System. The module is completely hidden from their view.
• Any Other Agency Users: No other user roles within an agency can view, access, or manage the Referral System.

Referral Code Ownership

• Each agency has ONE single referral code that is tied to the agency account, not to individual users.
• The referral code is generated at the agency level when the Agency Owner first accesses the Referral System.
• All referral earnings, tracking, and payouts are managed at the agency level by the Agency Owner.

Permissions (Agency Owner Only)

• View: The Agency Owner can view the referral dashboard, including earnings summary, total referrals count, next payout date, referral link, and subscription receipts table.
• Copy: The Agency Owner can copy the agency's unique referral link to share with others.
• Share: The Agency Owner can directly share the referral link via social media platforms (X, Facebook, LinkedIn) or email.
• Access "How it Works" Information: The Agency Owner can view a modal explaining the referral program's payout structure and terms.
• Manage Payment Details: The Agency Owner can add or update bank account information to receive referral payouts. The bank account is configurable by the owner (can be business or personal account).
• No Edit Permissions on Referral Link: The Agency Owner cannot edit or regenerate the agency's referral link once created.
• No Delete Permissions: The Agency Owner cannot delete referral history or subscription receipt records.

3. User Flow

Step-by-Step Navigation Sequence

1. **Access Referral System Module:
   **
   • The user logs into their Pixally account.
   • The user navigates to the left sidebar menu and clicks on "Referral System".
2. **View Referral Dashboard:
   **
   • The system loads the Referral System dashboard page displaying the main heading "Earn with Our Referral Program" with a subtitle "We love when you share Pixally with friends — and we want to thank you for it!".
   • The dashboard displays three summary cards at the top: "Next Payout", "Total Earnings", and "Total Referrals".
3. **Review Earnings and Referral Summary:
   **
   • The user reviews the "Next Payout" card showing the upcoming payout amount and expected date.
   • The user reviews the "Total Earnings" card showing cumulative earnings and the count of active referred users.
   • The user reviews the "Total Referrals" card showing the total number of referrals and active user count.
4. **Access Referral Tools:
   **
   • The user scrolls to the "Your Referral Tools" section.
   • The user views their unique "Basic Referral Link" displayed in a non-editable text field.
5. **Copy Referral Link:
   **
   • The user clicks the "Copy Link" button adjacent to the referral link field.
   • The system copies the link to the clipboard and displays a success message.
6. **Share Referral Link via Social Media or Email:
   **
   • The user clicks one of the "Quick Share" buttons: "Share on X", "Share on Facebook", "Share on LinkedIn", or "Email".
   • The system opens the respective platform's sharing interface with the referral link pre-populated.
7. **Access "How it Works" Modal:
   **
   • The user clicks the "How it Works" button in the top-right corner of the dashboard.
   • The system opens a modal overlay displaying detailed information about payout structures for yearly and monthly plans.
8. **Review Modal Content:
   **
   • The user reads the three-step process: "Share your referral link with friends, colleagues, or fellow creatives", "They sign up for a Pixally plan", "Once they hit each milestone, your reward is automatically sent to you".
   • The user reviews the payout structure for yearly plans ($100 after 90 days active).
   • The user reviews the milestone-based payout structure for monthly plans (90 days = $15, 6 months = +$25, 12 months = +$60).
   • The user reads the tip: "The more friends you refer, the more you can earn — there's no limit!".
9. **Close Modal:
   **
   • The user clicks "Got It" button or the close icon to dismiss the modal.
10. **Review Subscription Receipts:
    **
    • The user scrolls to the "Subscription Receipts" section with subtitle "View history of payments".
    • The user reviews the table displaying columns: User, Email, Plan, Payout Date, Payment Status, and Amount.
11. **Sort Subscription Receipts:
    **
    • The user clicks on any column header (User, Email, Plan, Payout Date, Payment Status, Amount) to sort the table in ascending or descending order.
12. **Navigate to Payment Details (Optional):
    **
    • The user clicks the "Payment Details" tab in the top navigation bar.
    • The system navigates to the Payment Details page where the user can add or update bank account information.

4. Functional Logic

4.1 Module Access and Navigation

4.1.1 Left Sidebar Menu Access

• The "Referral System" menu item is visible in the left sidebar ONLY for the Agency Owner.
• The "Referral System" menu item is completely hidden from Admins, Team Members, and all other non-owner users within the agency.
• Non-owner users do not see any indication that the Referral System module exists; it is entirely absent from their navigation menu.
• When the Agency Owner clicks "Referral System" in the left sidebar, the system navigates to the Referral System dashboard page.
• The system highlights the "Referral System" menu item to indicate the current active page.
• If a non-owner user attempts to access the Referral System URL directly, the system redirects them to the main dashboard with an "Access Denied" message or a 403 Forbidden response.

4.1.2 Top Navigation Tabs

• The Referral System module includes two tabs in the top center navigation: "Referral System" and "Payment Details".
• The "Referral System" tab is selected by default when the module is accessed.
• Clicking the "Payment Details" tab navigates the user to the payment setup page where bank account details can be added or updated.

4.2 Dashboard Display - Empty State

4.2.1 Initial State (No Referrals)

• When a user accesses the Referral System for the first time and has not generated any referrals, the dashboard displays:
  • "Next Payout" card showing $0.00 with "Expected: N/A" or "No upcoming payouts".
  • "Total Earnings" card showing $0.00 with "0 active users".
  • "Total Referrals" card showing 0 with "0 active users".
  • The "Your Referral Tools" section displays the user's unique referral link.
  • The "Subscription Receipts" table displays a message: "No referrals yet. Start sharing your link to earn rewards!" or an empty table state.

4.2.2 Referral Link Generation

• The system automatically generates ONE unique referral link per agency upon the Agency Owner's first access to the Referral System module.
• The referral link follows the format: https://yourapp.com/ref/\[UNIQUE\_CODE\] where [UNIQUE_CODE] is a unique alphanumeric identifier tied to the agency account (not individual users).
• Each agency has exactly one referral code; there is no separate code for the agency as a whole versus individual team members. The single code represents the agency.
• The referral link is permanent and cannot be changed or regenerated by the Agency Owner.
• The referral link remains valid indefinitely and does not expire.
• All referrals generated through this link are attributed to the agency, and earnings are managed at the agency level by the Agency Owner.

4.3 Dashboard Display - With Referrals

4.3.1 Next Payout Card

• The "Next Payout" card displays the total amount scheduled for the next payout cycle.
• The card shows the payout amount in bold (e.g., "$300.00").
• Below the amount, the card displays "Expected: [DATE]" indicating the estimated payout date based on the monthly payout schedule.
• If no payout is scheduled (e.g., no referrals have reached a milestone), the card displays "$0.00" with "Expected: N/A".

4.3.2 Total Earnings Card

• The "Total Earnings" card displays the cumulative earnings the user has accrued from all successful referrals.
• The card shows the total earnings amount in bold (e.g., "$1,600.00").
• Below the amount, the card displays "[X] active users" indicating the count of referred users who are currently active paying subscribers.

4.3.3 Total Referrals Card

• The "Total Referrals" card displays the total count of users who have signed up using the user's referral link.
• The card shows the total referral count as a bold number (e.g., "23").
• Below the count, the card displays "[X] active users" indicating how many of those referrals are currently active paying subscribers.

4.4 Your Referral Tools Section

4.4.1 Basic Referral Link Display

• The "Your Referral Tools" section displays a heading "Basic Referral Link".
• Below the heading, a non-editable text field displays the user's unique referral link (e.g., https://yourapp.com/ref/ALEX2024).
• The text field is styled to prevent editing but allows text selection for manual copying.

4.4.2 Copy Link Button Functionality

• A "Copy Link" button is positioned to the right of the referral link text field.
• When the user clicks the "Copy Link" button, the system copies the referral link to the user's clipboard.
• Upon successful copy, the system displays a success message: "Referral link copied to clipboard!".
• The button remains functional for repeated copying actions.

4.4.3 Quick Share Buttons

• Below the referral link field, the system displays a "Quick Share" section with four social sharing buttons:
  • Share on X: Opens a new browser tab/window with X (formerly Twitter) compose interface pre-filled with the referral link and a default message.
  • Share on Facebook: Opens Facebook's sharing dialog with the referral link.
  • Share on LinkedIn: Opens LinkedIn's sharing interface with the referral link.
  • Email: Opens the user's default email client with a new message containing the referral link in the body.
• Each button displays the platform logo and corresponding text label.
• Clicking any button triggers the respective platform's native sharing mechanism.

4.5 How it Works Modal

4.5.1 Modal Trigger

• A "How it Works" button is positioned in the top-right area of the dashboard header.
• When the user clicks the "How it Works" button, the system displays a modal overlay on top of the current page.

4.5.2 Modal Content Structure

• The modal displays a heading "How It Works" at the top.
• The modal contains three main sections:
  1. General Process (3 Steps):
     • Step 1: "Share your referral link with friends, colleagues, or fellow creatives."
     • Step 2: "They sign up for a Pixally plan."
     • Step 3: "Once they hit each milestone, your reward is automatically sent to you."
  2. If Your Friend Chooses a Yearly Plan:
     • Displays "$100 payout" in bold.
     • Explanation text: "Once your friend has been active for 90 days (past our 90-day guarantee window), you'll receive your $100 reward — simple as that."
  3. If Your Friend Chooses a Monthly Plan:
     • Displays the heading "You'll earn rewards in 3 milestones as they continue using Pixally:".
     • Lists three milestones:
       • 90 Days Active: You earn $15
       • 6 Months Active: You earn $25
       • 12 Months Active: You earn $60
     • Displays total summary: "That's a total of $100 if they stay active for the full year!"
     • Displays a highlighted tip box: "Tip: The more friends you refer, the more you can earn — there's no limit!"

4.5.3 Modal Actions

• The modal includes a "Got It" button at the bottom.
• Clicking the "Got It" button closes the modal and returns the user to the dashboard view.
• The modal also includes a close icon (X) in the top-right corner for dismissal.
• Clicking outside the modal area or pressing the Escape key also closes the modal.

4.6 Subscription Receipts Table

4.6.1 Table Structure and Display

• The "Subscription Receipts" section is displayed below the referral tools section.
• The section heading reads "Subscription Receipts" with a subtitle "View history of payments".
• The table contains the following columns:
  • User: Displays the referred user's name and "Since [DATE]" indicating when they became a subscriber.
  • Email: Displays the referred user's email address (partially masked for privacy, e.g., "s***@gmail.com").
  • Plan: Displays the subscription plan type (e.g., "Yearly", "Monthly").
  • Payout Date: Displays the date when the payout was processed or is scheduled.
  • Payment Status: Displays the status as "Paid" (green badge) or "Unpaid" (gray/orange badge).
  • Amount: Displays the payout amount earned from this referral (e.g., "$100.00") with additional context text (e.g., "Active for 90 days", "3 of 3 (Active for 12 months)").

4.6.2 Table Population Logic

• The table displays all referred users who have signed up using the user's referral link and have met at least one payout milestone or have a scheduled payout.
• Each row represents a single payout event (for yearly plans) or a milestone payout (for monthly plans).
• For monthly plan referrals, multiple rows may appear for the same user representing each milestone reached (e.g., three separate rows for 90 days, 6 months, and 12 months milestones).
• The table is sorted by default in descending order of "Payout Date" (most recent at the top).

4.6.3 Sorting Functionality

• Each column header is clickable to enable sorting.
• Clicking a column header once sorts the table in ascending order based on that column.
• Clicking the same column header again toggles the sort to descending order.
• A visual indicator (up/down arrow icon) appears next to the active sorted column header to indicate sort direction.

4.6.4 Payment Status Logic

• Paid Status: Displayed when the payout has been successfully processed and transferred to the user's bank account. The badge is styled in green.
• Unpaid Status: Displayed when the payout is scheduled but has not yet been processed (e.g., waiting for the monthly payout cycle or pending milestone completion). The badge is styled in gray or orange.

4.6.5 Amount Display Logic

• For yearly plan referrals: The amount column displays "$100.00" with context text "Active for 90 days".
• For monthly plan referrals: The amount column displays the milestone-specific amount ($15, $25, or $60) with context text indicating the milestone reached:
  • First milestone: "$15.00" with "1 of 3 (Active for 90 days)".
  • Second milestone: "$25.00" with "2 of 3 (Active for 6 months)".
  • Third milestone: "$60.00" with "3 of 3 (Active for 12 months)".

4.7 Payout Calculation and Processing

4.7.1 Active User Definition

• A referred user is considered "active" if they maintain a paid subscription without cancellation.
• The active duration is calculated from the date the user completes their first successful payment (excluding any free trial or grace periods).
• A user remains active as long as their subscription payments are processed successfully without interruption.
• If a payment fails but is retried and succeeds within the billing grace period, the user continues to be considered active.

4.7.2 Yearly Plan Payout Logic

• When a referred user signs up for a yearly plan and completes 90 consecutive days as an active paying subscriber, the referrer becomes eligible for a $100 payout.
• The system calculates the 90-day period starting from the date of the referred user's first successful payment.
• On day 91, the payout is added to the referrer's "Next Payout" total and scheduled for the next monthly payout cycle.
• If the referred user cancels their subscription on or before day 89, the $100 payout is forfeited and the referrer does not earn any amount for that referral.

4.7.3 Monthly Plan Payout Logic - Milestone 1 (90 Days)

• When a referred user signs up for a monthly plan and completes 90 consecutive days as an active paying subscriber, the referrer becomes eligible for a $15 payout (Milestone 1).
• The system calculates the 90-day period starting from the date of the referred user's first successful payment.
• On day 91, the $15 payout is added to the referrer's "Next Payout" total and scheduled for the next monthly payout cycle.
• A new row is added to the "Subscription Receipts" table showing the $15 amount with "1 of 3 (Active for 90 days)" status.

4.7.4 Monthly Plan Payout Logic - Milestone 2 (6 Months)

• When a referred user on a monthly plan reaches 6 months (180 days) of active subscription, the referrer becomes eligible for an additional $25 payout (Milestone 2).
• The system calculates the 6-month period as 180 consecutive days from the date of the referred user's first successful payment.
• On day 181, the $25 payout is added to the referrer's "Next Payout" total and scheduled for the next monthly payout cycle.
• A new row is added to the "Subscription Receipts" table showing the $25 amount with "2 of 3 (Active for 6 months)" status.
• The referrer retains the previously earned $15 from Milestone 1 regardless of future activity.

4.7.5 Monthly Plan Payout Logic - Milestone 3 (12 Months)

• When a referred user on a monthly plan reaches 12 months (365 days) of active subscription, the referrer becomes eligible for an additional $60 payout (Milestone 3).
• The system calculates the 12-month period as 365 consecutive days from the date of the referred user's first successful payment.
• On day 366, the $60 payout is added to the referrer's "Next Payout" total and scheduled for the next monthly payout cycle.
• A new row is added to the "Subscription Receipts" table showing the $60 amount with "3 of 3 (Active for 12 months)" status.
• The total cumulative payout for this monthly referral reaches $100 ($15 + $25 + $60).
• The referrer retains all previously earned amounts ($15 + $25) regardless of future activity.

4.7.6 Cancellation Impact on Payouts

• If a referred user cancels their subscription before reaching the next milestone, the referrer forfeits any future payouts for that referral.
• Previously earned and paid milestone amounts are retained by the referrer and are not clawed back.
• For example, if a monthly plan user cancels after 200 days (after Milestone 1 and Milestone 2 have been paid), the referrer keeps the $15 and $25 already received but will not earn the $60 for Milestone 3.
• If a referred user cancels and then resubscribes, the milestone tracking does not restart; the system does not count the reactivated subscription toward new milestones.

4.7.7 Payout Schedule and Processing

• Payouts are processed on a monthly schedule on a fixed date each month (e.g., the 1st or 15th of every month).
• All eligible payouts that have reached their milestone criteria by the payout cutoff date are included in the next payout cycle.
• The "Next Payout" card displays the sum of all eligible payouts scheduled for the upcoming payout date.
• The system transfers the payout amount to the referrer's designated bank account using the payment details provided in the "Payment Details" section.
• After a payout is successfully processed, the corresponding rows in the "Subscription Receipts" table are updated to "Paid" status.
• Standard Stripe processing fees are deducted from the payout amount before transfer (referrer receives the net amount after fees).

4.7.8 Payment Details Requirement

• Before the first payout can be processed, the Agency Owner must provide valid bank account information in the "Payment Details" section.
• The bank account is fully configurable by the Agency Owner; they may choose to use a business bank account or a personal bank account at their discretion.
• If bank details are not provided by the scheduled payout date, the payout is held in a pending state and displayed as "Unpaid" in the Subscription Receipts table.
• The system sends a notification to the Agency Owner prompting them to add payment details.
• Once payment details are added, the held payout is processed in the next available payout cycle.
• Earnings can ONLY be cashed out to a bank account; referrers cannot apply earnings toward their own Pixally subscription.

4.8 Duplicate Prevention and Attribution

4.8.1 No Duplicate Blocking

• The system does not block referrals based on IP address, device fingerprint, payment card, or email domain.
• Multiple users from the same organization, household, or network can sign up using the same referral link and each will be counted as a separate valid referral.

4.8.2 Attribution Logic

• Referral attribution is determined by the referral link used during the signup process.
• When a new user clicks a referral link, the system captures the unique referral code from the URL and stores it in the user's session.
• If the user completes the signup and subscription process, the referral is attributed to the owner of that referral code.
• If a user clicks multiple different referral links before signing up, the referral is attributed to the link from which the user actually completed the signup and subscription (the final link used in the signup session).

4.9 Earnings Summary Updates

4.9.1 Real-Time Updates

• The "Total Earnings" card is updated in real-time when a payout milestone is reached and added to the user's account balance.
• The "Total Referrals" card is updated immediately when a new user signs up using the referral link.
• The "Next Payout" card is updated when new milestones are reached and payouts are added to the upcoming payout cycle.

4.9.2 Active User Count Updates

• The active user count displayed in the "Total Earnings" and "Total Referrals" cards is recalculated daily to reflect the current status of referred users.
• If a referred user cancels their subscription, the active user count decreases by one.
• If a previously canceled user resubscribes, the active user count does not automatically increase (resubscriptions do not restart milestone tracking for referral purposes).

4.10 Impact on Other Modules

4.10.1 Integration with Subscription Module

• The Referral System module integrates with the Subscription module to track referred users' subscription status, plan type, and payment activity.
• The system monitors subscription lifecycle events (signup, payment success, payment failure, cancellation, plan changes) to determine milestone eligibility.

4.10.2 Integration with Payment Module

• The Referral System module integrates with the Payment module to process monthly payouts to referrers' bank accounts.
• Payment details provided in the "Payment Details" tab are stored securely and used for payout transfers via Stripe.

4.10.3 Integration with Notifications Module

• The system sends email notifications to referrers when:
  • A new user signs up using their referral link.
  • A referred user reaches a payout milestone.
  • A payout is successfully processed.
  • Payment details are missing and need to be added before payout processing.

5. Field Details & Validations

5.1 Referral Link Field

• Field Name: Basic Referral Link
• Field Type: Text (Read-only)
• Validation Rules:
  • The field displays a permanent, system-generated unique URL.
  • The field is non-editable by the user.
  • The link must follow the format: https://yourapp.com/ref/\[UNIQUE\_CODE\] where [UNIQUE_CODE] is alphanumeric.
  • The field allows text selection for manual copying.

5.2 Next Payout Amount

• Field Name: Next Payout
• Field Type: Currency Display (Read-only)
• Validation Rules:
  • Displays monetary value formatted as "$X.XX" (e.g., "$300.00").
  • Value must be non-negative (minimum $0.00).
  • Updated automatically by the system based on milestone calculations.

5.3 Total Earnings Amount

• Field Name: Total Earnings
• Field Type: Currency Display (Read-only)
• Validation Rules:
  • Displays cumulative monetary value formatted as "$X.XX" (e.g., "$1,600.00").
  • Value must be non-negative (minimum $0.00).
  • Updated automatically by the system when payouts are processed.

5.4 Total Referrals Count

• Field Name: Total Referrals
• Field Type: Integer Display (Read-only)
• Validation Rules:
  • Displays whole number count (e.g., "23").
  • Value must be non-negative (minimum 0).
  • Updated automatically when new referrals sign up.

5.5 Active Users Count

• Field Name: Active Users (displayed in Total Earnings and Total Referrals cards)
• Field Type: Integer Display (Read-only)
• Validation Rules:
  • Displays whole number count (e.g., "18 active users").
  • Value must be non-negative (minimum 0).
  • Value cannot exceed Total Referrals count.
  • Updated daily based on subscription status of referred users.

5.6 Payout Date Field

• Field Name: Expected Payout Date (Next Payout card) / Payout Date (Subscription Receipts table)
• Field Type: Date Display (Read-only)
• Validation Rules:
  • Displays date in format "DD MMM YYYY" (e.g., "11 Sep 2025").
  • Must be a valid future date for scheduled payouts.
  • Can display "N/A" if no payout is scheduled.

5.7 Payment Status Field

• Field Name: Payment Status
• Field Type: Badge/Label Display (Read-only)
• Validation Rules:
  • Must display one of two values: "Paid" or "Unpaid".
  • "Paid" status is styled with green color.
  • "Unpaid" status is styled with gray or orange color.

5.8 User Email Field (Subscription Receipts)

• Field Name: Email
• Field Type: Text Display (Read-only, Partially Masked)
• Validation Rules:
  • Displays email in partially masked format for privacy (e.g., "s***@gmail.com", "j***@gmail.com", "m***@yahoo.com").
  • Must be a valid email format when stored in the system.

5.9 Plan Type Field (Subscription Receipts)

• Field Name: Plan
• Field Type: Text Display (Read-only)
• Validation Rules:
  • Must display one of two values: "Yearly" or "Monthly".
  • Value is determined by the referred user's selected subscription plan.

5.10 Amount Field (Subscription Receipts)

• Field Name: Amount
• Field Type: Currency Display (Read-only)
• Validation Rules:
  • Displays monetary value formatted as "$X.XX" (e.g., "$100.00", "$15.00", "$25.00", "$60.00").
  • Must be one of the valid payout amounts: $15, $25, $60 (for monthly milestones), or $100 (for yearly plan).
  • Includes context text below the amount (e.g., "Active for 90 days", "2 of 3 (Active for 6 months)").

6. Success Message Handling

6.1 Referral Link Copied

• Operation: User clicks "Copy Link" button
• Success Message: "Referral link copied to clipboard!"
• Trigger Condition: The referral link is successfully copied to the user's clipboard.
• Post-Success Action: The message is displayed as a toast notification for 3-5 seconds and then auto-dismisses. No page refresh or navigation occurs.

6.2 Modal Acknowledged

• Operation: User clicks "Got It" button in the "How it Works" modal
• Success Message: No explicit message displayed (modal simply closes).
• Trigger Condition: User clicks the "Got It" button or close icon.
• Post-Success Action: The modal closes and the user returns to the main dashboard view.

6.3 Payout Processed Successfully

• Operation: System processes a scheduled payout to the user's bank account
• Success Message: Email notification sent: "Your referral payout of $[AMOUNT] has been successfully processed and will arrive in your bank account within 2-3 business days."
• Trigger Condition: Payout transfer is completed successfully by Stripe.
• Post-Success Action: The corresponding row(s) in the Subscription Receipts table are updated from "Unpaid" to "Paid" status. The "Next Payout" card is recalculated to reflect remaining scheduled payouts.

6.4 Payment Details Added

• Operation: User adds bank account information in the Payment Details section
• Success Message: "Payment details saved successfully. You're all set to receive your referral earnings!"
• Trigger Condition: User submits valid bank account information and it is successfully saved.
• Post-Success Action: The system enables payout processing for any pending "Unpaid" amounts. User is redirected back to the Referral System tab or remains on the Payment Details page.

6.5 New Referral Signup Notification

• Operation: A new user signs up using the user's referral link
• Success Message: Email notification sent: "Great news! [USER_NAME] signed up for Pixally using your referral link. You'll start earning once they become an active subscriber."
• Trigger Condition: A new user completes signup and creates an account using the referral link.
• Post-Success Action: The "Total Referrals" count is incremented by 1. A new entry is prepared for tracking in the system (visible in Subscription Receipts once milestones are reached).

6.6 Milestone Reached Notification

• Operation: A referred user reaches a payout milestone (90 days, 6 months, or 12 months active)
• Success Message: Email notification sent: "Congratulations! [USER_NAME] has reached the [MILESTONE] milestone. You've earned $[AMOUNT]! Your payout is scheduled for [DATE]."
• Trigger Condition: A referred user completes the required active duration for a milestone.
• Post-Success Action: The payout amount is added to the "Next Payout" total. A new row is added to the Subscription Receipts table with "Unpaid" status. The "Total Earnings" card is updated with the pending amount.

7. Error Message Handling

7.1 Copy to Clipboard Failure

• Error Scenario: User clicks "Copy Link" button but the clipboard API fails (e.g., browser permissions issue).
• Error Message: "Unable to copy link. Please manually select and copy the referral link."
• Trigger Condition: Browser clipboard API returns an error or is unavailable.
• Required Action: User manually selects the text from the referral link field and copies it using keyboard shortcuts (Ctrl+C / Cmd+C).
• System Response: Display error message as a toast notification for 5 seconds. The referral link field remains accessible for manual selection.

7.2 Social Share Popup Blocked

• Error Scenario: User clicks a "Quick Share" button but browser blocks the popup window.
• Error Message: "Pop-up blocked. Please allow pop-ups for this site or manually copy and share your referral link."
• Trigger Condition: Browser's popup blocker prevents the social sharing window from opening.
• Required Action: User enables popups in browser settings or manually copies the referral link to share via the platform.
• System Response: Display error message as a toast notification. Provide fallback instructions to manually copy the link.

7.3 Payment Details Missing at Payout Time

• Error Scenario: A payout is scheduled but the user has not provided bank account information.
• Error Message: Email notification sent: "Action Required: Add your payment details to receive your referral earnings of $[AMOUNT]. Visit your Referral System settings to complete setup."
• Trigger Condition: Payout cycle is triggered but no valid bank account is on file.
• Required Action: User navigates to Payment Details tab and adds bank account information.
• System Response: Payout remains in "Unpaid" status until payment details are provided. Once added, payout is processed in the next cycle.

7.4 Payout Processing Failure (Stripe Error)

• Error Scenario: System attempts to process payout but Stripe returns an error (e.g., invalid bank account, insufficient funds, account verification failed).
• Error Message: Email notification sent: "We encountered an issue processing your referral payout of $[AMOUNT]. Please verify your payment details and contact support if the issue persists."
• Trigger Condition: Stripe API returns an error during payout transfer.
• Required Action: User reviews and updates payment details in the Payment Details section. User may need to contact support for assistance.
• System Response: Payout remains in "Unpaid" status. User is prompted to update payment information. System retries payout in the next cycle after details are corrected.

7.5 Referred User Payment Failure Before Milestone

• Error Scenario: A referred user's payment fails (e.g., card declined) before reaching a milestone.
• Error Message: No direct error message to referrer (internal system tracking only).
• Trigger Condition: Referred user's subscription payment fails and they do not become an active subscriber.
• Required Action: No action required from referrer. System continues tracking if the referred user resolves payment and reactivates.
• System Response: Milestone countdown pauses or resets depending on whether the referred user successfully resumes payments within the grace period. If the user remains inactive for an extended period, they may not contribute to milestone calculations.

7.6 Dashboard Loading Failure

• Error Scenario: User navigates to the Referral System dashboard but the page fails to load due to network or server issues.
• Error Message: "Unable to load referral dashboard. Please check your connection and try again."
• Trigger Condition: API request to fetch dashboard data fails or times out.
• Required Action: User refreshes the page or checks internet connection.
• System Response: Display error message on the page with a "Retry" button. Clicking "Retry" re-attempts to load the dashboard data.

7.7 Subscription Receipts Table Load Failure

• Error Scenario: Subscription Receipts table fails to load or display data.
• Error Message: "Unable to load subscription receipts. Please try again later."
• Trigger Condition: API request to fetch subscription receipt data fails.
• Required Action: User refreshes the page or tries again after a few minutes.
• System Response: Display error message in place of the table with a "Retry" button.

7.8 Invalid Referral Link (Edge Case)

• Error Scenario: User's referral link is malformed or missing from the database (rare system error).
• Error Message: "Your referral link could not be generated. Please contact support for assistance."
• Trigger Condition: Database query returns no referral link for the user or the link format is invalid.
• Required Action: User contacts Pixally support to resolve the issue.
• System Response: Display error message in place of the referral link field. Disable "Copy Link" and "Quick Share" buttons until resolved.

8. Edge Cases

8.1 Referred User Cancels on Day 89

• Scenario: A referred user cancels their subscription on day 89 (one day before the 90-day milestone).
• Handling: The referrer does not earn the payout for that referral. The cancellation occurs before the milestone is reached, so no amount is added to "Next Payout" or "Total Earnings". The referral count remains in "Total Referrals" but the active user count decreases.

8.2 Referred User Downgrades from Yearly to Monthly Before 90 Days

• Scenario: A referred user signs up for a yearly plan but downgrades to a monthly plan before completing 90 days.
• Handling: The system recalculates the payout structure based on the new plan type (monthly). The milestone tracking resets and follows the monthly milestone schedule (90 days = $15, 6 months = $25, 12 months = $60). The user does not receive the $100 yearly payout.

8.3 Referred User Upgrades from Monthly to Yearly After First Milestone

• Scenario: A referred user signs up for a monthly plan, reaches the 90-day milestone ($15 earned), and then upgrades to a yearly plan.
• Handling: The referrer keeps the $15 already earned from the first milestone. Future milestone tracking is discontinued as the user is now on a yearly plan. No additional payouts are earned for this referral (the yearly $100 payout only applies if the user starts with a yearly plan, not if they upgrade mid-cycle).

8.4 Payment Details Added After Multiple Payouts Are Due

• Scenario: A user has multiple payouts in "Unpaid" status because they did not add payment details for several months.
• Handling: Once payment details are added, all accumulated "Unpaid" payouts are processed together in the next payout cycle. The user receives a single transfer containing the sum of all pending amounts (minus Stripe fees).

8.5 Referred User Resubscribes After Cancellation

• Scenario: A referred user cancels their subscription after earning the referrer $15 (Milestone 1) and then resubscribes a few months later.
• Handling: The referrer retains the $15 already earned. However, milestone tracking does not restart or resume. The resubscription is not counted as a new referral, and no additional payouts are earned from this user.

8.6 Same User Signs Up Multiple Times with Different Emails

• Scenario: The same individual creates multiple Pixally accounts using different email addresses and the same referral link.
• Handling: The system does not block based on IP, device, or payment card, so each signup is counted as a separate referral. Each account is tracked independently for milestone payouts. If this behavior is flagged as fraudulent by internal monitoring, support may investigate and invalidate fraudulent referrals.

8.7 Referrer Cancels Their Own Subscription

• Scenario: A Pixally user who has active referrals and pending payouts cancels their own Pixally subscription.
• Handling: The user retains access to the Referral System module as long as they have pending payouts or a grace period. Earned payouts that are already in "Paid" status are not affected. Unpaid payouts are still processed according to the payout schedule. If the user fully terminates their account, pending payouts may be held until the account is reactivated or handled according to the terms of service.

8.8 No Payment Details Provided for Extended Period

• Scenario: A user accumulates significant referral earnings but does not add payment details for 6+ months.
• Handling: All payouts remain in "Unpaid" status indefinitely. The system sends periodic email reminders prompting the user to add payment details. Once details are added, all accumulated payouts are processed in the next cycle. No payouts are lost or expire due to lack of payment details.

8.9 Stripe Account Verification Fails

• Scenario: User adds bank account information, but Stripe cannot verify the account (e.g., incorrect routing number, closed account).
• Handling: The system displays an error message prompting the user to correct the payment details. Payouts remain in "Unpaid" status. Support may reach out to assist with resolving verification issues.

8.10 Multiple Referrers Claim the Same Signup

• Scenario: A new user clicks multiple referral links from different referrers before signing up.
• Handling: Referral attribution is assigned to the referral link from which the user completed the final signup and subscription process. Only one referrer receives credit for the signup. The system tracks the referral code used during the account creation session to determine attribution.

8.11 Referred User Payment Fails Midway Through Milestone

• Scenario: A referred user's payment fails on day 120 (after earning the referrer $15 for the 90-day milestone) and they do not resume payments.
• Handling: The referrer retains the $15 already earned and paid from Milestone 1. The countdown for Milestone 2 (6 months) pauses. If the user does not reactivate their subscription, no further payouts are earned. The active user count is decremented.

8.12 Dashboard Accessed from Multiple Devices Simultaneously

• Scenario: User accesses the Referral System dashboard from two devices at the same time (e.g., desktop and mobile).
• Handling: Both devices display the same dashboard data based on the latest state from the server. Updates (such as new referral signups or milestone completions) are reflected on both devices upon page refresh or real-time sync (if implemented). No data conflicts occur.

8.13 User Shares Referral Link on Public Forum

• Scenario: User posts their referral link on a public forum or social media platform, resulting in a large number of signups.
• Handling: All signups using the referral link are counted as valid referrals, regardless of volume. There is no limit to the number of referrals a user can generate. Each valid referral that meets milestone criteria earns the corresponding payout.

8.14 Referred User Subscribes During a Promotional Period

• Scenario: A referred user signs up using a referral link while Pixally is running an additional promotional discount (e.g., 60% off instead of 50% off).
• Handling: The referral discount (50% off first year + extra 10% off first 3 months) is applied on top of any existing promotional offer if allowed by system business rules. The referrer's payout structure remains unchanged ($100 for yearly, milestone-based for monthly). Payouts are not affected by the amount the referred user actually pays.

8.15 Referral Link Shared via Email Attachment or PDF

• Scenario: User copies their referral link into a document, PDF, or email attachment and shares it.
• Handling: As long as the recipient clicks the link from the document or attachment and completes signup, the referral is attributed correctly. The link functions the same way regardless of how it is shared.

8.16 Agency with Multiple Users (Admins/Team Members)

• Scenario: An agency has an owner plus multiple admins and team members. Admins or team members attempt to access the Referral System.
• Handling: Only the Agency Owner has access to the Referral System module. The "Referral System" menu item is completely hidden from Admins, Team Members, and all other non-owner users within the agency. There is ONE single referral code per agency, tied to the agency account itself—not separate codes for each team member. All referral earnings, tracking, and payouts are managed at the agency level by the Agency Owner. If a non-owner user attempts to access the Referral System URL directly (e.g., via bookmark or direct link), the system redirects them to the main dashboard with an "Access Denied" message.

8.17 Agency Owner Role Transfer

• Scenario: The Agency Owner role is transferred to another user within the agency (e.g., original owner leaves the organization).
• Handling: The new Agency Owner inherits full access to the Referral System module, including the existing referral code, all historical earnings, payout records, and payment details. The referral code does not change during ownership transfer. The new owner may update payment details as needed.

9. Acceptance Criteria

9.1 Functional Requirements

• The Referral System module must be accessible from the left sidebar menu ONLY for the Agency Owner; it must be completely hidden from Admins, Team Members, and all other non-owner users.
• Non-owner users attempting to access the Referral System URL directly must be redirected to the main dashboard with an "Access Denied" message or receive a 403 Forbidden response.
• The dashboard must display the three summary cards: "Next Payout", "Total Earnings", and "Total Referrals" with accurate real-time data.
• The system must generate ONE unique, permanent referral link per agency (not per user) that follows the format https://yourapp.com/ref/\[UNIQUE\_CODE\].
• The "Copy Link" button must successfully copy the referral link to the user's clipboard and display a success message.
• The "Quick Share" buttons must open the respective social platform or email client with the referral link pre-populated.
• The "How it Works" button must open a modal displaying detailed information about the referral program's payout structure.
• The modal must include the 3-step process, yearly plan payout details, monthly plan milestone details, and a "Got It" button to close.
• The "Subscription Receipts" table must display all referral payouts with columns: User, Email, Plan, Payout Date, Payment Status, and Amount.
• Each column in the Subscription Receipts table must be sortable in ascending and descending order.
• The system must correctly calculate and display payouts: $100 for yearly plans after 90 days, and milestone-based payouts ($15, $25, $60) for monthly plans.
• The system must process monthly payouts to users' bank accounts via Stripe after payment details are provided.
• The system must update the "Payment Status" from "Unpaid" to "Paid" after successful payout processing.

9.2 Validation Expectations

• Referral links must be unique per agency, non-editable, and permanent. Each agency has exactly one referral code.
• All monetary amounts must be displayed in the format "$X.XX" with two decimal places.
• The "Next Payout" card must only display scheduled payouts that have reached milestone eligibility.
• Active user counts must be updated daily and must not exceed the total referral count.
• Email addresses in the Subscription Receipts table must be partially masked for privacy.
• Payment Status badges must be color-coded correctly: green for "Paid", gray/orange for "Unpaid".

9.3 Data Consistency Rules

• The sum of all individual payouts in the Subscription Receipts table must equal the "Total Earnings" displayed in the summary card.
• The "Next Payout" amount must accurately reflect the sum of all eligible unpaid milestones scheduled for the next cycle.
• Milestone tracking must pause or reset if a referred user's subscription is canceled before reaching the next milestone.
• Previously earned and paid milestone amounts must not be clawed back if a referred user cancels their subscription.
• Referral attribution must be consistent and assigned to the referral link used during the signup session.

9.4 User Actions and System Flow Validations

• Users must be able to navigate between "Referral System" and "Payment Details" tabs without data loss.
• The "How it Works" modal must be dismissible via the "Got It" button, close icon, clicking outside the modal, or pressing Escape.
• Social sharing buttons must trigger native platform sharing mechanisms or default email client.
• Error messages must be displayed as toast notifications and must auto-dismiss after 3-5 seconds.
• The system must send email notifications for new referrals, milestone achievements, and payout processing.

10. Dependencies

10.1 Internal Module Dependencies

• Subscription Module: The Referral System relies on the Subscription module to track referred users' subscription status, plan type (yearly or monthly), payment success/failure events, and cancellation events to determine milestone eligibility.
• Payment Module: The Referral System integrates with the Payment module to process monthly payouts to referrers' bank accounts and to store/retrieve payment details (bank account information).
• User Authentication Module: The Referral System requires the User Authentication module to verify logged-in users and ensure only active Pixally subscribers can access the referral dashboard.
• Notifications Module: The Referral System depends on the Notifications module to send email alerts for new referrals, milestone achievements, payout processing, and payment detail reminders.

10.2 External Service Dependencies

• Stripe API: The system uses Stripe for payout processing. Stripe must be configured to handle transfers to referrers' bank accounts. Stripe's processing fees are deducted from payouts.
• Email Service Provider (e.g., SendGrid, Mailgun): Required for sending transactional email notifications to referrers regarding referral activity and payout status.
• Social Media APIs (Optional): For seamless social sharing, the system may integrate with X (Twitter), Facebook, and LinkedIn sharing APIs to pre-populate share content.

10.3 Configuration Requirements

• Referral Link Base URL: The system must have a configured base URL (e.g., https://yourapp.com/ref/) to generate referral links.
• Payout Schedule Configuration: The system must have a defined monthly payout schedule date (e.g., payouts processed on the 1st of every month).
• Milestone Criteria: The system must have hardcoded or configurable milestone criteria: 90 days, 180 days (6 months), and 365 days (12 months).
• Payout Amounts: The system must have configured payout amounts: $100 for yearly plans, $15/$25/$60 for monthly milestones.
• Stripe Account Configuration: A valid Stripe account must be set up with payout capabilities enabled.

10.4 Expected System Behavior if Dependencies Fail

• Subscription Module Failure: If the Subscription module is unavailable, milestone tracking cannot occur. Payouts are delayed until subscription data is accessible. Users see outdated data on the dashboard.
• Payment Module Failure: If the Payment module is unavailable, payouts cannot be processed. Payouts remain in "Unpaid" status and are retried in the next cycle. Users receive error notifications.
• Stripe API Failure: If Stripe is down or returns errors, payouts fail and remain in "Unpaid" status. Users are notified of the issue and prompted to verify payment details. The system retries in the next payout cycle.
• Email Service Failure: If the email service is unavailable, notification emails are queued and sent once the service is restored. Users do not receive real-time notifications but can view updates on the dashboard.
• Social Media API Failure: If social sharing APIs are unavailable, the "Quick Share" buttons may open generic share interfaces or display an error. Users can still manually copy the referral link to share.

11. References

Figma Links

• Referral Dashboard (Pixally User): Image 1 - referalsystemforpixallyuser.png
• "How it Works" Modal: Image 2 - howitwork.png
• Referral System Dashboard (Alternative View): Image 4 - influedashboard.png
• Payment Details Page: Image 5 - influepaymentdashboard.png

Related Documents

• Referral Logic Discussion: referral-logic-discusison.rtf
• Client Meeting MOM (NotebookLM Notes): Provided in project documentation

External References

• Stripe Payouts API Documentation: https://stripe.com/docs/payouts
• Social Media Sharing Guidelines:
  • X (Twitter) Web Intent: https://developer.twitter.com/en/docs/twitter-for-websites/tweet-button/overview
  • Facebook Share Dialog: https://developers.facebook.com/docs/sharing/reference/share-dialog
  • LinkedIn Share API: https://docs.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/plugins/share-plugin

End of Document

2. Sign Up Flow for Normal User from Referral URL

Functional Requirements Document (FRD)

Sign Up Flow for Normal User from Referral URL

1. Module Overview

Module Name

Sign Up Flow for Normal User from Referral URL

Purpose

The Sign Up Flow for Normal User from Referral URL module enables new users who click on a referral link to create a Pixally account with exclusive referral discounts applied automatically. The module provides a customized signup experience that displays the referrer's name, the discount offer, and guides the user through account creation while ensuring proper referral attribution for payout tracking.

Business Goals

• Convert referred traffic into new Pixally subscribers by offering attractive signup incentives (50% off first year + extra 10% off first 3 months).
• Ensure accurate referral attribution to enable correct payout calculations for referrers.
• Provide a seamless, user-friendly signup experience that highlights the value proposition of the referral offer.
• Drive user acquisition through word-of-mouth marketing by incentivizing both referrers and referred users.

2. User Roles & Permissions

Roles with Access

• New User (Referred User): Any individual who clicks on a referral link and does not have an existing Pixally account.

Permissions

• View: New users can view the referral signup page displaying the referrer's name and discount offer.
• Create Account: New users can create a Pixally account by filling out the signup form with their personal information.
• Sign Up with Google: New users can create an account using Google OAuth authentication.
• Accept Terms & Conditions: New users must agree to Pixally's Terms & Conditions and Privacy Policy to proceed with signup.
• No Edit Permissions on Referral Attribution: Users cannot change or remove the referral attribution once they land on the referral signup page.

3. User Flow

Step-by-Step Navigation Sequence

1. **Click Referral Link:
   **
   • A potential new user receives a referral link from an existing Pixally user via email, social media, or direct message.
   • The referral link follows the format: https://yourapp.com/ref/\[UNIQUE\_CODE\].
   • The user clicks on the referral link.
2. **Land on Referral Signup Page:
   **
   • The system loads a customized signup page designed specifically for referral traffic.
   • The page displays the Pixally logo at the top center.
   • The page prominently displays the referrer's name and the discount offer: "[REFERRER_NAME] gave you 60% off first 3 months and 50% off first year".
3. **View Signup Form:
   **
   • The page displays a signup form on the right side with the following fields:
     • First name
     • Last name
     • Email address
     • Password
   • Below the form fields, a "Create Account" button is displayed.
4. **Fill Out Signup Form:
   **
   • The user enters their first name in the "First name" field.
   • The user enters their last name in the "Last name" field.
   • The user enters their email address in the "Email address" field.
   • The user enters a password (minimum 6+ characters) in the "Password" field with a show/hide toggle icon.
5. **Alternative: Sign Up with Google:
   **
   • Instead of filling out the manual form, the user can click the "Sign Up with Google" button located below the "Create Account" button.
   • The system redirects the user to Google's OAuth authentication screen.
   • The user authorizes Pixally to access their Google account information (name, email).
   • Upon successful authorization, the system automatically creates a Pixally account using the user's Google credentials and returns the user to the Pixally platform.
6. **Review Terms and Conditions:
   **
   • At the bottom of the form, the page displays a small text: "By signing up, you agree to our Terms & Conditions" (with "Terms & Conditions" as a clickable link).
   • Below that, another line reads: "This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply." (with clickable links for Privacy Policy and Terms of Service).
7. **Submit Signup Form:
   **
   • The user clicks the "Create Account" button to submit the form.
   • The system validates all form fields according to the validation rules.
8. **Account Creation and Referral Attribution:
   **
   • If all validations pass, the system creates a new Pixally account for the user.
   • The system stores the referral attribution by linking the new user's account to the referrer's unique code captured from the URL.
   • The system applies the referral discount to the user's account: 50% off first year + extra 10% off first 3 months.
9. **Redirect to Subscription Selection:
   **
   • After successful account creation, the system redirects the user to the subscription plan selection page where they can choose between monthly or yearly plans.
   • The discount is automatically applied and displayed on the pricing page.
10. **Existing Account Login:
    **
    • If the user already has an account, they can click the "Already have an account? Login" link at the bottom of the form.
    • The system redirects the user to the standard login page (referral attribution is not applied if the user logs into an existing account).

4. Functional Logic

4.1 Referral Link Processing

4.1.1 URL Parameter Capture

• When a user clicks a referral link (e.g., https://yourapp.com/ref/ALEX2024), the system captures the unique referral code (ALEX2024) from the URL path.
• The system validates that the referral code exists in the database and is associated with an active Pixally subscriber (referrer).
• If the referral code is valid, the system stores the code in the user's session/cookies to maintain referral attribution throughout the signup process.
• If the referral code is invalid or expired, the system redirects the user to the standard signup page without referral benefits.

4.1.2 Referrer Information Retrieval

• The system queries the database to retrieve the referrer's name (first name and last name or display name) associated with the referral code.
• The retrieved referrer name is used to personalize the signup page heading.

4.2 Referral Signup Page Display

4.2.1 Page Layout and Branding

• The referral signup page is divided into two sections: a left visual section and a right form section.
• The left section displays a hero image (lifestyle/creative professional image) to create an engaging visual experience.
• The right section contains the signup form and all related elements.
• The Pixally logo is displayed at the top center of the right section.

4.2.2 Personalized Heading

• The heading displays the text: "[REFERRER_NAME] gave you 60% off first 3 months and 50% off first year".
• The referrer's name is dynamically populated based on the referral code from the URL.
• The discount percentages are hardcoded as part of the referral offer structure.
• The heading is styled prominently to draw attention to the offer.

4.3 Signup Form Display and Interaction

4.3.1 Form Field Layout

• The form displays four input fields arranged vertically:
  1. First name: A text input field with placeholder text "First name" and pre-filled example "Aaron".
  2. Last name: A text input field with placeholder text "Last name" and pre-filled example "Sanders".
  3. Email address: A text input field with placeholder text "Email address" and pre-filled example "a.sanders@gmail.com".
  4. Password: A password input field with placeholder text "Password" and hint "6+ characters". Includes a show/hide toggle icon (eye icon) to reveal or mask the password.

4.3.2 Field Interaction and Validation

• Each field displays placeholder text to guide the user.
• When a user focuses on a field, the placeholder disappears and the user can begin typing.
• Real-time validation is performed as the user types or upon field blur (when the user clicks outside the field).
• If a validation error occurs, the field is highlighted with a red border and an error message is displayed below the field.

4.4 Form Validation Logic

4.4.1 First Name Validation

• The first name field is required and cannot be empty.
• The field must contain at least 2 characters.
• The field should only contain alphabetic characters (letters, spaces, hyphens, and apostrophes are allowed).
• Special characters and numbers are not allowed.
• If validation fails, the system displays an error message: "Please enter a valid first name."

4.4.2 Last Name Validation

• The last name field is required and cannot be empty.
• The field must contain at least 2 characters.
• The field should only contain alphabetic characters (letters, spaces, hyphens, and apostrophes are allowed).
• Special characters and numbers are not allowed.
• If validation fails, the system displays an error message: "Please enter a valid last name."

4.4.3 Email Address Validation

• The email address field is required and cannot be empty.
• The field must contain a valid email format (e.g., user@example.com).
• The email address must not already be registered in the Pixally system.
• If the email format is invalid, the system displays an error message: "Please enter a valid email address."
• If the email is already registered, the system displays an error message: "This email is already registered. Please login or use a different email."

4.4.4 Password Validation

• The password field is required and cannot be empty.
• The password must be at least 6 characters long.
• The password can contain letters, numbers, and special characters.
• If the password is shorter than 6 characters, the system displays an error message: "Password must be at least 6 characters long."

4.5 Create Account Button Functionality

4.5.1 Button State and Interaction

• The "Create Account" button is styled prominently in yellow/gold color to stand out.
• The button is enabled by default when the page loads.
• When the user clicks the "Create Account" button, the system performs the following actions:
  1. Validates all form fields according to the validation rules defined above.
  2. If any validation fails, the system highlights the problematic field(s) and displays corresponding error messages.
  3. If all validations pass, the system disables the button and displays a loading spinner to prevent duplicate submissions.

4.5.2 Account Creation Process

• The system sends the form data (first name, last name, email, password) to the backend API endpoint for account creation.
• The backend API creates a new user record in the database with the following information:
  • User's first name and last name
  • User's email address (used as the unique identifier)
  • Hashed password (securely stored using encryption)
  • Referral attribution (the referral code captured from the URL is stored and linked to the user's account)
  • Account creation timestamp
  • User status: Active (pending subscription)
• The system applies the referral discount eligibility to the user's account (50% off first year + extra 10% off first 3 months) so that the discount is automatically reflected when the user selects a subscription plan.

4.5.3 Post-Creation Actions

• Upon successful account creation, the system generates a session token/cookie to authenticate the user.
• The system logs the user into their new Pixally account automatically (no additional login required).
• The system redirects the user to the subscription plan selection page where they can choose a monthly or yearly plan.
• The system increments the referrer's "Total Referrals" count by 1 in the Referral System dashboard.
• The system sends a notification email to the referrer informing them of the new signup.

4.6 Sign Up with Google Functionality

4.6.1 Google OAuth Button

• Below the "Create Account" button, a separator line displays "OR" to indicate an alternative signup method.
• A "Sign Up with Google" button is displayed with the Google logo icon.
• When the user clicks the "Sign Up with Google" button, the system initiates Google OAuth authentication flow.

4.6.2 Google OAuth Flow

• The system redirects the user to Google's authentication page.
• The user logs into their Google account (if not already logged in) and grants permission for Pixally to access their basic profile information (name, email).
• Google returns the user to Pixally with an authorization code.
• The system exchanges the authorization code for an access token and retrieves the user's Google profile information (name, email).

4.6.3 Account Creation via Google

• The system checks if the retrieved Google email address is already registered in Pixally.
• If the email is not registered, the system creates a new Pixally account using the Google profile information:
  • First name and last name are extracted from the Google profile.
  • Email address is used as the unique identifier.
  • No password is stored (user will log in via Google OAuth in the future).
  • Referral attribution is applied by linking the referral code to the new account.
  • Referral discount eligibility is applied to the account.
• If the email is already registered, the system displays an error message: "This Google account is already registered. Please login instead."

4.6.4 Post-Google Signup Actions

• Upon successful account creation via Google, the system logs the user in automatically.
• The system redirects the user to the subscription plan selection page.
• The referrer's "Total Referrals" count is incremented by 1.
• The system sends a notification email to the referrer informing them of the new signup.

4.7 Terms & Conditions and Privacy Policy Links

4.7.1 Legal Disclaimers

• At the bottom of the signup form, the system displays the text: "By signing up, you agree to our Terms & Conditions".
• The "Terms & Conditions" text is styled as a clickable link.
• When the user clicks the "Terms & Conditions" link, the system opens the Terms & Conditions page in a new browser tab.
• Below that, the system displays: "This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply."
• "Privacy Policy" and "Terms of Service" are styled as clickable links that open the respective Google policy pages in new tabs.

4.8 Already Have an Account - Login Link

4.8.1 Login Redirect

• At the bottom of the form, the system displays the text: "Already have an account? Login".
• The "Login" text is styled as a clickable link in yellow/gold color.
• When the user clicks the "Login" link, the system redirects the user to the standard Pixally login page.
• If the user logs into an existing account, the referral attribution from the referral URL is not applied (referrals only apply to new account signups).

4.9 Referral Attribution Tracking

4.9.1 Session and Cookie Management

• When a user lands on the referral signup page, the system stores the referral code in both the session and a browser cookie.
• The session stores the referral code temporarily for the duration of the user's browsing session.
• The cookie stores the referral code for a longer period (e.g., 30 days) to ensure attribution is maintained even if the user navigates away and returns later.
• When the user completes the signup process, the system retrieves the referral code from the session/cookie and links it to the newly created account.

4.9.2 Multi-Link Attribution Logic

• If a user clicks multiple different referral links before signing up, the referral is attributed to the link from which the user actually completed the signup process.
• The most recent referral code stored in the session/cookie is used for attribution.
• For example, if User A clicks Referrer X's link, then later clicks Referrer Y's link and signs up from that session, Referrer Y receives the referral credit.

4.10 Discount Application Logic

4.10.1 Discount Eligibility Flag

• When a new user account is created via the referral signup flow, the system sets a "referral discount eligible" flag on the user's account.
• This flag indicates that the user is entitled to receive the referral discount: 50% off first year + extra 10% off first 3 months.

4.10.2 Discount Display on Subscription Page

• When the user is redirected to the subscription plan selection page, the system checks for the "referral discount eligible" flag.
• If the flag is present, the system displays the discounted pricing:
  • Yearly Plan: Original price with 50% off applied, plus a note indicating "Extra 10% off first 3 months" (though yearly plans do not have monthly breakdowns, the equivalent discount is factored into the calculation as per the logic document: 2 months free + 50% off + extra 10% off first 3 months).
  • Monthly Plan: Original monthly price with 50% off applied, plus a note indicating "Extra 10% off first 3 months".
• The discount is automatically applied at checkout when the user selects a plan and completes payment.

4.10.3 Discount Calculation for Yearly Plan

• Original yearly plan price: $39/month × 12 months = $468.
• Apply 2 months free offer: $39 × 10 months = $390.
• Apply 50% off first year: $390 × 50% = $195.
• Apply extra 10% off first 3 months: Calculate 10% discount on the already discounted monthly rate ($19.50) for 3 months = $1.95 × 3 = $5.85 total additional discount.
• Final first-year price: $195 - $5.85 = $189.15.

4.10.4 Discount Calculation for Monthly Plan

• Original monthly plan price: $39/month.
• Apply 50% off: $39 × 50% = $19.50/month.
• Apply extra 10% off for first 3 months: $19.50 × 10% = $1.95 discount per month for 3 months.
• First 3 months pricing: $19.50 - $1.95 = $17.55/month.
• Months 4-12 pricing: $19.50/month (50% off continues, but extra 10% off expires after 3 months).

4.11 Empty State Handling

4.11.1 Invalid or Missing Referral Code

• If a user lands on the referral signup URL but the referral code is invalid (e.g., the code does not exist in the database or the referrer's account is inactive), the system redirects the user to the standard non-referral signup page.
• The user can still create an account, but they will not receive the referral discount and no referral attribution is recorded.

4.11.2 Referral Code Expired (Edge Case)

• Referral codes are designed to be permanent and do not expire. However, if a referrer deletes their account or becomes inactive, their referral code may be deactivated.
• If a user clicks a deactivated referral link, the system redirects them to the standard signup page without referral benefits.

4.12 Impact on Other Modules

4.12.1 Integration with Referral System Module (Referrer Dashboard)

• When a new user signs up via a referral link, the system updates the referrer's Referral System dashboard:
  • Increments the "Total Referrals" count by 1.
  • Sends an email notification to the referrer.
  • Prepares the new referral for milestone tracking (payouts will be calculated once the referred user subscribes and remains active).

4.12.2 Integration with Subscription Module

• After account creation, the system redirects the user to the subscription plan selection page.
• The Subscription module reads the "referral discount eligible" flag and applies the appropriate discount to the pricing display and checkout process.
• The referred user's subscription status and payment activity are tracked by the Subscription module to determine when referral milestones are reached (for payout calculations).

4.12.3 Integration with User Authentication Module

• The signup process integrates with the User Authentication module to create secure user credentials (hashed passwords) and generate session tokens.
• Google OAuth integration relies on the Authentication module to handle third-party login flows.

4.12.4 Integration with Notifications Module

• Upon successful signup, the Notifications module sends a welcome email to the new user.
• The Notifications module also sends a referral signup notification email to the referrer.

5. Field Details & Validations

5.1 First Name Field

• Field Name: First name
• Field Type: Text Input
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 2 characters.
  • Maximum length: 50 characters.
  • Must contain only alphabetic characters (letters, spaces, hyphens, apostrophes allowed).
  • No numbers or special characters (except hyphen and apostrophe).
• Error Message: "Please enter a valid first name."

5.2 Last Name Field

• Field Name: Last name
• Field Type: Text Input
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 2 characters.
  • Maximum length: 50 characters.
  • Must contain only alphabetic characters (letters, spaces, hyphens, apostrophes allowed).
  • No numbers or special characters (except hyphen and apostrophe).
• Error Message: "Please enter a valid last name."

5.3 Email Address Field

• Field Name: Email address
• Field Type: Email Input
• Validation Rules:
  • Required (cannot be empty).
  • Must be a valid email format (e.g., user@example.com).
  • Must contain "@" symbol and a valid domain.
  • Must not already exist in the Pixally user database (unique constraint).
• Error Messages:
  • Invalid format: "Please enter a valid email address."
  • Already registered: "This email is already registered. Please login or use a different email."

5.4 Password Field

• Field Name: Password
• Field Type: Password Input (with show/hide toggle)
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 6 characters.
  • No maximum length (but practical limit of 128 characters for security).
  • Can contain letters (uppercase and lowercase), numbers, and special characters.
• Error Message: "Password must be at least 6 characters long."

5.5 Referral Code (Hidden Field)

• Field Name: Referral Code (not visible to user)
• Field Type: Hidden Input / Session Variable
• Validation Rules:
  • Must be a valid alphanumeric string matching a referrer's unique code in the database.
  • Must be associated with an active referrer account.
  • Cannot be manually edited by the user.
• Error Handling: If invalid, redirect to standard signup page without referral benefits.

6. Success Message Handling

6.1 Account Created Successfully

• Operation: User submits the signup form with valid data or completes Google OAuth signup.
• Success Message: No explicit success message is displayed on the signup page. Instead, the user is immediately redirected to the subscription plan selection page.
• Trigger Condition: Account creation is successful and the user record is saved in the database.
• Post-Success Action:
  • User is automatically logged in with a session token.
  • User is redirected to the subscription plan selection page.
  • Welcome email is sent to the user's registered email address.
  • Referrer receives an email notification: "Great news! [USER_NAME] signed up for Pixally using your referral link. You'll start earning once they become an active subscriber."
  • Referrer's "Total Referrals" count is incremented by 1 in their dashboard.

6.2 Referral Link Clicked Successfully

• Operation: User clicks a valid referral link and lands on the referral signup page.
• Success Message: No explicit success message. The page loads with the personalized heading displaying the referrer's name and discount offer.
• Trigger Condition: Referral code in the URL is valid and associated with an active referrer.
• Post-Success Action: Referral code is stored in the user's session/cookie for attribution tracking.

6.3 Google OAuth Signup Completed

• Operation: User completes Google OAuth authentication and account creation.
• Success Message: No explicit success message. User is immediately redirected to the subscription plan selection page.
• Trigger Condition: Google returns user profile data successfully and account is created.
• Post-Success Action: Same as 6.1 (automatic login, redirect, welcome email, referrer notification).

7. Error Message Handling

7.1 First Name Validation Error

• Error Scenario: User submits the form with an empty, too short, or invalid first name.
• Error Message: "Please enter a valid first name."
• Trigger Condition: First name field fails validation (empty, <2 characters, or contains numbers/special characters).
• Required Action: User corrects the first name field and resubmits.
• System Response: Red border appears around the first name field. Error message is displayed below the field in red text.

7.2 Last Name Validation Error

• Error Scenario: User submits the form with an empty, too short, or invalid last name.
• Error Message: "Please enter a valid last name."
• Trigger Condition: Last name field fails validation (empty, <2 characters, or contains numbers/special characters).
• Required Action: User corrects the last name field and resubmits.
• System Response: Red border appears around the last name field. Error message is displayed below the field in red text.

7.3 Email Format Validation Error

• Error Scenario: User submits the form with an invalid email format (e.g., missing "@", invalid domain).
• Error Message: "Please enter a valid email address."
• Trigger Condition: Email address field fails format validation.
• Required Action: User corrects the email address and resubmits.
• System Response: Red border appears around the email field. Error message is displayed below the field in red text.

7.4 Email Already Registered Error

• Error Scenario: User submits the form with an email address that already exists in the Pixally database.
• Error Message: "This email is already registered. Please login or use a different email."
• Trigger Condition: Email uniqueness check fails during backend validation.
• Required Action: User either logs in using the existing account or enters a different email address.
• System Response: Red border appears around the email field. Error message is displayed below the field in red text. The "Login" link in the error message can be clicked to navigate to the login page.

7.5 Password Too Short Error

• Error Scenario: User submits the form with a password shorter than 6 characters.
• Error Message: "Password must be at least 6 characters long."
• Trigger Condition: Password field fails minimum length validation.
• Required Action: User enters a longer password (at least 6 characters) and resubmits.
• System Response: Red border appears around the password field. Error message is displayed below the field in red text.

7.6 Account Creation Failed (Server Error)

• Error Scenario: User submits valid form data, but the backend API fails to create the account due to a server error or database issue.
• Error Message: "We're sorry, something went wrong. Please try again or contact support if the issue persists."
• Trigger Condition: Backend API returns a 500 error or fails to complete account creation.
• Required Action: User attempts to submit the form again or contacts support.
• System Response: A generic error message is displayed at the top of the form as a red alert banner. The "Create Account" button is re-enabled for retry.

7.7 Google OAuth Authentication Failed

• Error Scenario: User clicks "Sign Up with Google" but the OAuth authentication fails (e.g., user denies permission, network error, Google API down).
• Error Message: "Unable to sign up with Google. Please try again or use the manual signup form."
• Trigger Condition: Google OAuth flow returns an error or user cancels the authorization.
• Required Action: User either retries the Google signup or uses the manual form.
• System Response: Error message is displayed as a red alert banner at the top of the form. User remains on the signup page.

7.8 Google Email Already Registered Error

• Error Scenario: User attempts to sign up with Google using an email address that is already registered in Pixally.
• Error Message: "This Google account is already registered. Please login instead."
• Trigger Condition: Email retrieved from Google OAuth already exists in the database.
• Required Action: User navigates to the login page and logs in with their existing account.
• System Response: Error message is displayed as a red alert banner. A "Login" link is provided to redirect the user to the login page.

7.9 Invalid or Expired Referral Code

• Error Scenario: User clicks a referral link with an invalid or deactivated referral code.
• Error Message: No explicit error message displayed to the user.
• Trigger Condition: Referral code in the URL does not exist in the database or is associated with an inactive referrer account.
• Required Action: No action required from the user.
• System Response: User is silently redirected to the standard non-referral signup page. The user can still create an account but will not receive referral benefits.

7.10 Session or Cookie Failure (Edge Case)

• Error Scenario: Referral code cannot be stored in session/cookie due to browser settings (e.g., cookies disabled).
• Error Message: "Please enable cookies in your browser to complete the signup process."
• Trigger Condition: System is unable to set session or cookie data.
• Required Action: User enables cookies in browser settings and reloads the page.
• System Response: Error message is displayed as a red alert banner. Signup form is disabled until cookies are enabled.

8. Edge Cases

8.1 User Clicks Referral Link But Already Has Account

• Scenario: A user who already has a Pixally account clicks a referral link.
• Handling: The system detects that the user is already logged in or has an existing account. The user is redirected to their dashboard or the login page. Referral attribution is not applied (referrals only count for new signups, not existing accounts).

8.2 User Clicks Multiple Referral Links Before Signing Up

• Scenario: A user clicks Referrer A's link, then later clicks Referrer B's link, and then signs up.
• Handling: The referral is attributed to Referrer B (the last referral code stored in the session/cookie). Only Referrer B receives credit for the signup.

8.3 User Navigates Away and Returns Later

• Scenario: A user clicks a referral link, lands on the signup page, navigates away without signing up, and returns days later.
• Handling: If the referral code cookie is still valid (e.g., set to expire after 30 days), the referral attribution is maintained. If the cookie has expired, the user lands on the standard signup page without referral benefits.

8.4 User Submits Form with All Fields Empty

• Scenario: User clicks "Create Account" button without filling out any fields.
• Handling: The system displays validation errors for all required fields (first name, last name, email, password) simultaneously. All fields are highlighted in red with corresponding error messages below each field.

8.5 User Enters Email with Extra Spaces

• Scenario: User enters email address with leading or trailing spaces (e.g., " user@example.com ").
• Handling: The system automatically trims whitespace from the email field during validation. The email is processed correctly without error.

8.6 User Attempts to Sign Up with Disposable/Temporary Email

• Scenario: User enters a temporary or disposable email address (e.g., from services like Mailinator, TempMail).
• Handling: The system does not block disposable emails by default. The account is created successfully. However, if the business decides to block disposable emails in the future, a validation rule can be added to reject known disposable email domains.

8.7 Google OAuth Returns Incomplete Profile Data

• Scenario: Google OAuth authentication succeeds but returns incomplete profile data (e.g., missing last name).
• Handling: The system uses whatever data is available from Google. If the last name is missing, the system may prompt the user to complete their profile after account creation or use the email prefix as a placeholder name.

8.8 User Cancels Google OAuth Authorization

• Scenario: User clicks "Sign Up with Google" but cancels the authorization on Google's consent screen.
• Handling: Google returns an error code. The system displays an error message: "Unable to sign up with Google. Please try again or use the manual signup form." The user remains on the signup page.

8.9 Network Failure During Form Submission

• Scenario: User submits the signup form but experiences a network failure or timeout before the backend API responds.
• Handling: The system displays an error message: "Network error. Please check your connection and try again." The "Create Account" button is re-enabled. Form data is retained so the user does not need to re-enter information.

8.10 Referrer Deletes Account After Sharing Link

• Scenario: A user shares their referral link, then deletes their Pixally account before the referred user signs up.
• Handling: When the referred user clicks the link, the referral code is no longer valid (referrer account is inactive). The system redirects the user to the standard signup page without referral benefits. No referral attribution is recorded.

8.11 User Opens Referral Link in Incognito/Private Mode

• Scenario: User clicks a referral link while browsing in incognito or private mode.
• Handling: The referral code is stored in the session/cookie as usual. The signup process works normally. However, if the user closes the incognito window before completing signup and returns later in a regular browsing session, the referral attribution may be lost (depending on cookie settings).

8.12 User Signs Up, Then Immediately Cancels Subscription

• Scenario: A user signs up via a referral link, selects a subscription plan, but cancels the subscription before completing payment or during the first few days.
• Handling: The referrer's "Total Referrals" count is incremented when the user signs up, but no payout milestones are reached because the user did not become an active paying subscriber. The referrer does not earn any money for this referral.

8.13 User Uses VPN or Proxy to Access Referral Link

• Scenario: User accesses the referral link through a VPN or proxy, masking their true IP address.
• Handling: The system does not block or flag referrals based on IP address, so the signup proceeds normally. Referral attribution is based on the referral code in the URL, not IP address.

8.14 User Signs Up with Same Email from Different Referral Links (Impossible Case)

• Scenario: User attempts to create multiple accounts with the same email using different referral links.
• Handling: This scenario is impossible because the system enforces email uniqueness. The second signup attempt will fail with the error: "This email is already registered. Please login or use a different email."

8.15 User Manually Types Referral URL with Typo in Code

• Scenario: User receives a referral link but manually types it into the browser with a typo in the referral code (e.g., ALEX2024 typed as ALEX2025).
• Handling: The system validates the referral code and determines it is invalid. The user is redirected to the standard signup page without referral benefits.

9. Acceptance Criteria

9.1 Functional Requirements

• The referral signup page must load when a user clicks a valid referral link with the format https://yourapp.com/ref/\[UNIQUE\_CODE\].
• The page must display the referrer's name and discount offer in the heading: "[REFERRER_NAME] gave you 60% off first 3 months and 50% off first year".
• The signup form must display four fields: First name, Last name, Email address, and Password.
• All form fields must validate according to the specified validation rules (required, minimum length, format checks).
• The "Create Account" button must submit the form only if all validations pass.
• If validation fails, error messages must be displayed below the corresponding fields with red styling.
• The "Sign Up with Google" button must initiate Google OAuth authentication and create an account using Google profile data.
• Upon successful account creation, the user must be automatically logged in and redirected to the subscription plan selection page.
• The referral discount (50% off first year + extra 10% off first 3 months) must be applied to the user's account.
• The referrer's "Total Referrals" count must increment by 1 when the new user signs up.
• A notification email must be sent to the referrer when a new user signs up via their referral link.

9.2 Validation Expectations

• First name and last name fields must accept only alphabetic characters with a minimum length of 2 characters.
• Email field must enforce valid email format and check for uniqueness in the database.
• Password field must enforce a minimum length of 6 characters.
• If the email is already registered, the system must display the error: "This email is already registered. Please login or use a different email."
• If a referral code is invalid or expired, the user must be redirected to the standard signup page without referral benefits.

9.3 Data Consistency Rules

• Referral attribution must be stored accurately and linked to the new user's account upon signup.
• The referral code must be captured from the URL and stored in the session/cookie to maintain attribution throughout the signup process.
• Only one referral code can be attributed per signup (the most recent code in the session/cookie).
• Email addresses must be unique across all user accounts (no duplicate emails allowed).

9.4 User Actions and System Flow Validations

• Clicking the "Create Account" button must trigger form validation before submission.
• Clicking the "Sign Up with Google" button must redirect the user to Google's OAuth consent screen.
• Clicking the "Already have an account? Login" link must redirect the user to the login page.
• Clicking the "Terms & Conditions" or "Privacy Policy" links must open the respective pages in new browser tabs.
• After successful account creation, the system must automatically log the user in and redirect them to the subscription plan selection page.

10. Dependencies

10.1 Internal Module Dependencies

• Referral System Module (Referrer Dashboard): The signup flow depends on the Referral System module to retrieve referrer information (name, referral code validation) and to update referral tracking metrics (Total Referrals count, new signup notifications).
• User Authentication Module: The signup flow integrates with the User Authentication module to create user credentials, hash passwords, generate session tokens, and handle Google OAuth authentication.
• Subscription Module: After account creation, the Subscription module is responsible for displaying the subscription plan selection page and applying the referral discount to the pricing.
• Notifications Module: The Notifications module sends welcome emails to new users and referral signup notifications to referrers.

10.2 External Service Dependencies

• Google OAuth API: Required for "Sign Up with Google" functionality. Google OAuth must be configured with valid API credentials (Client ID, Client Secret) and redirect URIs.
• Email Service Provider (e.g., SendGrid, Mailgun): Required for sending transactional emails (welcome emails to new users, signup notifications to referrers).
• reCAPTCHA (Optional but Recommended): Google reCAPTCHA can be integrated to prevent bot signups and ensure form submissions are from real users.

10.3 Configuration Requirements

• Referral Link Base URL: The system must have a configured base URL (e.g., https://yourapp.com/ref/) to process referral links.
• Google OAuth Credentials: Valid Google OAuth Client ID and Client Secret must be configured in the system's environment variables or configuration files.
• Redirect URIs: Google OAuth redirect URIs must be whitelisted in the Google Cloud Console (e.g., https://yourapp.com/auth/google/callback).
• Session/Cookie Settings: Session and cookie expiration times must be configured (e.g., session expires after browsing session ends, cookie expires after 30 days).
• Referral Discount Logic: Discount percentages (50% off first year, extra 10% off first 3 months) and duration must be hardcoded or configurable in the system.

10.4 Expected System Behavior if Dependencies Fail

• Referral System Module Failure: If the Referral System module is unavailable, the system cannot validate referral codes or retrieve referrer names. The user is redirected to the standard signup page without referral benefits.
• User Authentication Module Failure: If the User Authentication module is unavailable, account creation fails. The system displays an error message: "We're sorry, something went wrong. Please try again later."
• Google OAuth API Failure: If Google OAuth is down or returns errors, the "Sign Up with Google" button displays an error message. Users can still sign up using the manual form.
• Email Service Failure: If the email service is unavailable, welcome emails and referral notifications are queued and sent once the service is restored. The signup process itself is not blocked.
• Subscription Module Failure: If the Subscription module is unavailable after account creation, the user cannot proceed to select a plan. The user is redirected to their dashboard with a message to complete subscription setup later.
• reCAPTCHA Failure (if enabled): If reCAPTCHA fails to load or verify, the system may allow the signup to proceed (depending on configuration) or display an error message prompting the user to reload the page.

11. References

Figma Links

• Referral Signup Page: Image 3 - referalsignup.png

Related Documents

• Referral Logic Discussion: referral-logic-discusison.rtf
• Client Meeting MOM (NotebookLM Notes): Provided in project documentation

External References

• Google OAuth Documentation: https://developers.google.com/identity/protocols/oauth2
• Google Sign-In Button Guidelines: https://developers.google.com/identity/branding-guidelines
• reCAPTCHA Documentation: https://developers.google.com/recaptcha/docs/display

End of Document

3. Influencer Sign Up and Dashboard

Functional Requirements Document (FRD)

Influencer Sign Up and Dashboard

1. Module Overview

Module Name

Influencer Sign Up and Dashboard

Purpose

The Influencer Sign Up and Dashboard module enables influencers, content creators, and brand ambassadors to join Pixally's Referral Partner Program without requiring a Pixally subscription. The module provides a dedicated signup flow for influencers and a streamlined dashboard that allows them to access their referral tools, track earnings, manage payment details, and view subscription receipts—all without needing to navigate the full Pixally platform.

Business Goals

• Expand Pixally's reach by enabling influencers with engaged audiences to promote the platform and earn referral commissions without being Pixally customers themselves.
• Provide a simplified, influencer-focused user experience that removes unnecessary features and focuses solely on referral program management.
• Drive user acquisition through influencer marketing by incentivizing external advocates with the same payout structure as regular Pixally users.
• Establish a scalable referral partner ecosystem that complements the existing user-based referral program.

2. User Roles & Permissions

Roles with Access

• Influencer (Referral Partner): Any individual who signs up as an influencer through the dedicated influencer signup link. Influencers do not need to be Pixally subscribers.

Permissions

• View: Influencers can view their referral dashboard, including earnings summary, total referrals count, next payout date, referral link, and subscription receipts table.
• Copy: Influencers can copy their unique referral link to share with their audience.
• Share: Influencers can directly share their referral link via social media platforms (X, Facebook, LinkedIn) or email.
• Access "How it Works" Information: Influencers can view a modal explaining the referral program's payout structure and terms.
• Manage Payment Details: Influencers can add or update their bank account information to receive referral payouts (via the Payment Details tab).
• No Access to Full Pixally Platform: Influencers do not have access to other Pixally modules (e.g., project management, client portal, proposals) unless they separately sign up as a Pixally subscriber.
• No Edit Permissions on Referral Link: Influencers cannot edit or regenerate their referral link once created.
• No Delete Permissions: Influencers cannot delete referral history or subscription receipt records.

3. User Flow

Step-by-Step Navigation Sequence

Part A: Influencer Signup Flow

1. **Receive Influencer Signup Link:
   **
   • Pixally shares a dedicated influencer signup link (e.g., https://yourapp.com/influencer/signup) with potential influencers via email, social media, or direct outreach.
   • The influencer clicks the signup link.
2. **Land on Influencer Signup Landing Page:
   **
   • The system loads the influencer signup landing page with a hero image on the left and signup information on the right.
   • The page displays the Pixally logo at the top right.
   • The main heading reads: "Join the Referral Partner Program".
   • The subheading explains: "Earn cash rewards by sharing Pixally — no subscription required!"
   • A description explains: "You don't need to be a Pixally customer to benefit. If you have an engaged audience on Instagram, YouTube, or other platforms, you can start earning today by introducing your followers to our services."
3. **Click "Continue to Sign Up" Button:
   **
   • The influencer clicks the prominent "Continue to Sign Up" button.
   • The system navigates to the influencer signup form page.
4. **View Influencer Signup Form:
   **
   • The signup form page displays the Pixally logo at the top right.
   • The main heading reads: "Join the Referral Partner Program".
   • The form displays four input fields:
     • First name
     • Last name
     • Email address
     • Password (with show/hide toggle)
   • Below the form fields, a "Create Account" button is displayed.
5. **Fill Out Signup Form:
   **
   • The influencer enters their first name, last name, email address, and password.
   • The system validates each field according to the validation rules.
6. **Alternative: Sign Up with Google:
   **
   • Instead of filling out the manual form, the influencer can click the "Sign Up with Google" button located below the "Create Account" button.
   • The system redirects the influencer to Google's OAuth authentication screen.
   • Upon successful authorization, the system creates an influencer account using Google credentials.
7. **Review Terms and Conditions:
   **
   • At the bottom of the form, the page displays: "By signing up, you agree to our Terms & Conditions" (with clickable link).
   • Below that: "This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply." (with clickable links).
8. **Submit Signup Form:
   **
   • The influencer clicks the "Create Account" button to submit the form.
   • The system validates all fields and creates an influencer account.
9. **Account Creation and Dashboard Access:
   **
   • Upon successful account creation, the system logs the influencer in automatically.
   • The system redirects the influencer to their Influencer Dashboard.

Part B: Influencer Dashboard Navigation

1. **Access Influencer Dashboard:
   **
   • After signup or subsequent logins, the influencer lands on the Influencer Dashboard.
   • The dashboard displays a simplified interface with only two tabs in the top center navigation: "Referral System" and "Payment Details".
   • The "Referral System" tab is selected by default.
2. **View Dashboard Summary:
   **
   • The dashboard displays the main heading: "Earn with Our Referral Program" with subtitle "We love when you share Pixally with friends — and we want to thank you for it!".
   • Three summary cards are displayed: "Next Payouts", "Total Earnings", and "Total Referrals".
3. **Review Earnings and Referral Tools:
   **
   • The influencer reviews their earnings, next payout amount, and total referrals.
   • The influencer scrolls to the "Your Referral Tools" section to view their unique referral link.
   • The influencer can copy the link or share it via social media using the "Quick Share" buttons.
4. **Access "How it Works" Modal:
   **
   • The influencer clicks the "How it Works" button in the top-right corner.
   • The system displays the same modal as shown to regular Pixally users, explaining the payout structure.
5. **Review Subscription Receipts:
   **
   • The influencer scrolls to the "Subscription Receipts" section to view a table of all payouts and referral activity.
   • The influencer can sort the table by clicking column headers.
6. **Navigate to Payment Details:
   **
   • The influencer clicks the "Payment Details" tab in the top navigation.
   • The system navigates to the Payment Details page where the influencer can add or update bank account information.
7. **Add Payment Details:
   **
   • The influencer fills out the form with: Business bank account number, Business bank routing number, and Business bank name.
   • The influencer clicks "Save changes" to submit the payment information.
8. **Logout:
   **
   • The influencer can click their profile icon/name in the top right corner to access account settings or logout.
   • Upon logout, the influencer is redirected to the standard Pixally login page.

4. Functional Logic

4.1 Influencer Signup Landing Page

4.1.1 Page Access and Display

• The influencer signup landing page is accessible via a dedicated URL (e.g., https://yourapp.com/influencer/signup).
• The page is publicly accessible (no authentication required) and can be shared with potential influencers via any channel.
• The page layout is divided into two sections: a left hero image section and a right content section.

4.1.2 Visual Design and Branding

• The left section displays a lifestyle/creative professional hero image to create an aspirational and engaging visual experience.
• The right section contains the Pixally logo at the top, followed by the main heading, description, and "Continue to Sign Up" button.
• The page uses Pixally's brand colors and typography to maintain consistency with the main platform.

4.1.3 Content and Messaging

• The main heading reads: "Join the Referral Partner Program".
• The description explains the program's value proposition:
  • "Earn cash rewards by sharing Pixally — no subscription required!"
  • "You don't need to be a Pixally customer to benefit. If you have an engaged audience on Instagram, YouTube, or other platforms, you can start earning today by introducing your followers to our services."
• The messaging emphasizes that influencers do not need to purchase a Pixally subscription to participate and earn money.

4.1.4 Continue to Sign Up Button

• A prominent yellow/gold "Continue to Sign Up" button is displayed below the description.
• When the user clicks the button, the system navigates to the influencer signup form page.

4.1.5 Legal Disclaimers

• At the bottom of the page, small text displays: "By signing up, you agree to our Terms & Conditions" (with clickable link).
• Below that: "This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply." (with clickable links).

4.2 Influencer Signup Form Page

4.2.1 Page Layout and Branding

• The influencer signup form page follows the same visual structure as the landing page: left hero image, right form section.
• The right section displays the Pixally logo, main heading "Join the Referral Partner Program", and the signup form.

4.2.2 Form Fields and Input

• The form displays four input fields:
  1. First name: Text input with placeholder "First name".
  2. Last name: Text input with placeholder "Last name".
  3. Email address: Email input with placeholder "Email address".
  4. Password: Password input with placeholder "Password" and hint "6+ characters". Includes a show/hide toggle icon.

4.2.3 Form Validation

• Each field is validated according to the same rules as the regular referral signup flow (see Field Details & Validations section below).
• Real-time or on-blur validation is performed as the user types or moves to the next field.
• Invalid fields are highlighted with a red border and error messages are displayed below the field.

4.2.4 Create Account Button

• A yellow/gold "Create Account" button is displayed below the form fields.
• When clicked, the system validates all fields and submits the form if validations pass.
• Upon submission, the button is disabled and a loading spinner is displayed to prevent duplicate submissions.

4.2.5 Sign Up with Google Option

• Below the "Create Account" button, a separator line displays "OR".
• A "Sign Up with Google" button is displayed with the Google logo.
• When clicked, the system initiates Google OAuth authentication flow (same logic as regular referral signup).

4.2.6 Already Have an Account Link

• At the bottom of the form, the page displays: "Already have an account? Login" (with clickable "Login" link).
• Clicking the "Login" link redirects the user to the standard Pixally login page.
• Influencers log in using the same credentials as regular users, but their dashboard experience is restricted to referral-related features only.

4.3 Influencer Account Creation

4.3.1 Account Type Flag

• When an influencer account is created via the influencer signup flow, the system sets an "influencer" or "referral_partner" account type flag in the user database.
• This flag distinguishes influencer accounts from regular Pixally subscriber accounts.
• The flag determines which modules and features the user can access after login.

4.3.2 Account Creation Process

• The system creates a new user record in the database with the following information:
  • User's first name and last name
  • User's email address (unique identifier)
  • Hashed password (securely stored)
  • Account type: "Influencer" or "Referral Partner"
  • Account creation timestamp
  • User status: Active
• The system generates a unique referral link for the influencer following the same format as regular users: https://yourapp.com/ref/\[UNIQUE\_CODE\].

4.3.3 Post-Creation Actions

• Upon successful account creation, the system generates a session token to authenticate the influencer.
• The system logs the influencer in automatically (no additional login required).
• The system redirects the influencer to the Influencer Dashboard (Referral System tab).
• The system sends a welcome email to the influencer's registered email address with instructions on how to use the referral program.

4.4 Influencer Dashboard - Layout and Access Control

4.4.1 Simplified Navigation

• Unlike regular Pixally users who see a full left sidebar menu with multiple modules, influencers see a simplified interface with NO left sidebar menu.
• The influencer dashboard only displays two tabs in the top center navigation: "Referral System" and "Payment Details".
• The "Referral System" tab is selected by default when the influencer logs in.

4.4.2 Access Restrictions

• Influencers do not have access to other Pixally modules such as:
  • My Profile
  • General Settings
  • Business & Payment Details (for Pixally subscription)
  • Team Management
  • 2-Step Verification
  • AI Preferences
  • Notifications
  • Brands
  • Subscription (for Pixally plans)
• If an influencer attempts to access restricted URLs directly, the system redirects them to the Referral System dashboard with a message: "This feature is only available to Pixally subscribers. Visit our pricing page to learn more."

4.4.3 Top Navigation Bar

• The top navigation bar displays:
  • Pixally logo on the left (clicking it redirects to the Referral System dashboard).
  • Two tabs in the center: "Referral System" and "Payment Details".
  • User profile icon/name on the right with a dropdown menu for account settings and logout.

4.5 Influencer Dashboard - Referral System Tab

4.5.1 Dashboard Content

• The Referral System tab displays the exact same content and functionality as the regular Pixally user's referral dashboard:
  • Main heading: "Earn with Our Referral Program"
  • Three summary cards: "Next Payouts", "Total Earnings", "Total Referrals"
  • "Your Referral Tools" section with referral link, "Copy Link" button, and "Quick Share" buttons
  • "How it Works" button in the top-right corner
  • "Subscription Receipts" table displaying payout history

4.5.2 Functional Behavior

• All functional logic for the Referral System tab is identical to the regular Pixally user's referral dashboard (see "Referral System for Pixally User" FRD for detailed functional logic).
• Influencers earn the same payout structure as regular users:
  • Yearly plan referrals: $100 after 90 days active.
  • Monthly plan referrals: Milestone-based payouts ($15, $25, $60).
• Payouts are processed on the same monthly schedule via Stripe to the influencer's designated bank account.

4.6 Influencer Dashboard - Payment Details Tab

4.6.1 Tab Navigation

• When the influencer clicks the "Payment Details" tab in the top navigation, the system navigates to the Payment Details page.
• The "Payment Details" tab is highlighted to indicate the current active tab.

4.6.2 Payment Details Page Layout

• The page displays a heading: "Set Up Your Payout Details".
• Below the heading, a subtitle explains: "Add or update your payment information to ensure you receive your referral rewards quickly and securely."
• The page displays a form with three input fields:
  1. Business bank account number: Text input for bank account number.
  2. Business bank routing number: Text input for bank routing number.
  3. Business bank name: Text input for bank name.

4.6.3 Form Field Display and Input

• Each field has a label above it indicating the field name.
• Input fields display placeholder text to guide the user (e.g., "Enter account number", "Enter routing number", "Enter bank name").
• All fields are required for payout processing.

4.6.4 Save Changes and Cancel Buttons

• At the bottom of the form, two buttons are displayed:
  • "Cancel" button: Gray/neutral button that discards changes and returns the user to the Referral System tab.
  • "Save changes" button: Yellow/gold button that submits the form and saves the payment details.

4.6.5 Form Validation

• All three fields are required (cannot be empty).
• Bank account number must be numeric and meet minimum length requirements (typically 8-17 digits depending on the bank).
• Bank routing number must be exactly 9 digits (for US banks) and must be a valid routing number.
• Bank name is a text field with no strict validation (minimum 2 characters).

4.6.6 Form Submission and Saving

• When the influencer clicks "Save changes", the system validates all fields.
• If validation passes, the system saves the payment details securely in the database (encrypted).
• The system displays a success message: "Payment details saved successfully. You're all set to receive your referral earnings!".
• If validation fails, error messages are displayed below the corresponding fields with red styling.

4.6.7 Editing Existing Payment Details

• If the influencer has already saved payment details, the form fields are pre-filled with the existing data.
• The influencer can edit any field and click "Save changes" to update the information.
• The system validates and saves the updated details.

4.6.8 Cancel Button Behavior

• When the influencer clicks the "Cancel" button, the system discards any unsaved changes.
• The system navigates back to the Referral System tab.
• If the influencer had previously saved payment details, those details remain unchanged.

4.7 Payout Processing for Influencers

4.7.1 Same Payout Structure as Regular Users

• Influencers earn referral payouts using the exact same structure as regular Pixally users:
  • Yearly plan referrals: $100 flat payout after the referred user remains active for 90 consecutive days.
  • Monthly plan referrals: Milestone-based payouts:
    • $15 after 90 days active
    • $25 after 6 months active (total $40)
    • $60 after 12 months active (total $100)

4.7.2 Payout Schedule and Transfer

• Payouts are processed on the same monthly schedule as regular users (e.g., on the 1st of every month).
• All eligible payouts are transferred to the influencer's designated bank account via Stripe.
• Stripe processing fees are deducted from the payout amount (same as regular users).

4.7.3 Payment Details Requirement

• Before the first payout can be processed, the influencer must provide valid bank account information in the Payment Details section.
• If payment details are missing at payout time, the payout is held in "Unpaid" status and the influencer receives an email notification prompting them to add payment details.
• Once payment details are added, held payouts are processed in the next payout cycle.

4.8 Referral Link Attribution and Tracking

4.8.1 Same Attribution Logic

• Influencer referral links function identically to regular user referral links.
• When a new user clicks an influencer's referral link and signs up, the system attributes the referral to the influencer's account.
• Referral tracking, milestone calculations, and payout processing follow the same logic as described in the "Referral System for Pixally User" FRD.

4.8.2 No Duplicate Prevention

• The system does not block referrals based on IP address, device, payment card, or email domain (same as regular users).
• Each valid signup is counted as a separate referral regardless of source.

4.9 Login and Authentication

4.9.1 Login Process

• Influencers log in using the standard Pixally login page with their registered email and password.
• Alternatively, influencers can log in using Google OAuth if they signed up with Google.
• After successful login, the system checks the user's account type flag.
• If the account type is "Influencer" or "Referral Partner", the system redirects the user to the Influencer Dashboard (Referral System tab) with restricted access.
• If the account type is "Pixally Subscriber", the system redirects the user to the full Pixally platform dashboard with all modules accessible.

4.9.2 Session Management

• Influencer sessions are managed using the same authentication system as regular users.
• Session tokens expire based on the same timeout rules.
• Influencers can remain logged in across multiple devices if the platform supports multi-device sessions.

4.10 Influencer to Subscriber Conversion

4.10.1 Upgrade Path

• If an influencer decides to become a Pixally subscriber, they can navigate to the Pixally pricing page and purchase a subscription.
• Upon subscription purchase, the system updates the user's account type flag from "Influencer" to "Pixally Subscriber".
• The user retains their existing referral earnings and payout history.
• After upgrading, the user gains access to the full Pixally platform (all modules) in addition to the Referral System.
• The left sidebar menu becomes visible, providing access to all Pixally features.

4.10.2 Referral Earnings Continuity

• All previously earned referral payouts and ongoing milestone tracking continue seamlessly after the influencer upgrades to a subscriber.
• The referral link remains the same (no new link is generated).
• Total Earnings, Total Referrals, and Subscription Receipts history are fully preserved.

4.11 Empty State Handling

4.11.1 New Influencer with No Referrals

• When an influencer first logs in and has not generated any referrals, the dashboard displays:
  • "Next Payout" card showing $0.00 with "Expected: N/A".
  • "Total Earnings" card showing $0.00 with "0 active users".
  • "Total Referrals" card showing 0 with "0 active users".
  • The "Subscription Receipts" table displays an empty state message: "No referrals yet. Start sharing your link to earn rewards!".

4.11.2 Payment Details Not Added

• If an influencer has not yet added payment details, the Payment Details form displays empty input fields.
• A helper message is displayed: "Add your payment information to ensure you receive your referral rewards quickly and securely."
• If a payout becomes due before payment details are added, the influencer receives an email reminder to complete payment setup.

4.12 Impact on Other Modules

4.12.1 Integration with Referral System Module

• Influencer accounts integrate seamlessly with the existing Referral System module.
• All referral tracking, milestone calculations, and payout processing logic is shared between regular users and influencers (no separate logic required).
• The only difference is the user interface (simplified dashboard for influencers vs. full platform dashboard for regular users).

4.12.2 Integration with User Authentication Module

• Influencer signup and login are handled by the same User Authentication module as regular users.
• The account type flag is used to determine post-login redirection and feature access.

4.12.3 Integration with Payment Module

• Influencer payout processing uses the same Payment module and Stripe integration as regular users.
• Payment details are stored and validated using the same secure processes.

4.12.4 Integration with Notifications Module

• Influencers receive the same email notifications as regular users:
  • Welcome email upon signup
  • New referral signup notifications
  • Milestone reached notifications
  • Payout processed notifications
  • Payment details reminder notifications

5. Field Details & Validations

5.1 First Name Field (Signup Form)

• Field Name: First name
• Field Type: Text Input
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 2 characters.
  • Maximum length: 50 characters.
  • Must contain only alphabetic characters (letters, spaces, hyphens, apostrophes allowed).
  • No numbers or special characters (except hyphen and apostrophe).
• Error Message: "Please enter a valid first name."

5.2 Last Name Field (Signup Form)

• Field Name: Last name
• Field Type: Text Input
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 2 characters.
  • Maximum length: 50 characters.
  • Must contain only alphabetic characters (letters, spaces, hyphens, apostrophes allowed).
  • No numbers or special characters (except hyphen and apostrophe).
• Error Message: "Please enter a valid last name."

5.3 Email Address Field (Signup Form)

• Field Name: Email address
• Field Type: Email Input
• Validation Rules:
  • Required (cannot be empty).
  • Must be a valid email format (e.g., user@example.com).
  • Must contain "@" symbol and a valid domain.
  • Must not already exist in the Pixally user database (unique constraint).
• Error Messages:
  • Invalid format: "Please enter a valid email address."
  • Already registered: "This email is already registered. Please login or use a different email."

5.4 Password Field (Signup Form)

• Field Name: Password
• Field Type: Password Input (with show/hide toggle)
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 6 characters.
  • No maximum length (practical limit of 128 characters).
  • Can contain letters (uppercase and lowercase), numbers, and special characters.
• Error Message: "Password must be at least 6 characters long."

5.5 Business Bank Account Number Field (Payment Details)

• Field Name: Business bank account number
• Field Type: Text Input (Numeric)
• Validation Rules:
  • Required (cannot be empty).
  • Must contain only numeric digits.
  • Minimum length: 8 digits.
  • Maximum length: 17 digits.
  • No special characters or spaces allowed.
• Error Message: "Please enter a valid bank account number (8-17 digits)."

5.6 Business Bank Routing Number Field (Payment Details)

• Field Name: Business bank routing number
• Field Type: Text Input (Numeric)
• Validation Rules:
  • Required (cannot be empty).
  • Must be exactly 9 digits (for US banks).
  • Must be a valid routing number (checksum validation via Stripe or internal algorithm).
  • No special characters or spaces allowed.
• Error Messages:
  • Invalid length: "Routing number must be exactly 9 digits."
  • Invalid format: "Please enter a valid routing number."

5.7 Business Bank Name Field (Payment Details)

• Field Name: Business bank name
• Field Type: Text Input
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 2 characters.
  • Maximum length: 100 characters.
  • Can contain letters, numbers, spaces, and basic punctuation.
• Error Message: "Please enter your bank name."

5.8 Dashboard Summary Fields (Read-Only)

• All dashboard summary fields (Next Payout, Total Earnings, Total Referrals, Active Users) follow the same validation rules as described in the "Referral System for Pixally User" FRD.

6. Success Message Handling

6.1 Influencer Account Created Successfully

• Operation: User submits the signup form with valid data or completes Google OAuth signup.
• Success Message: No explicit success message on the signup page. User is immediately redirected to the Influencer Dashboard.
• Trigger Condition: Account creation is successful and the user record is saved in the database with "Influencer" account type flag.
• Post-Success Action:
  • User is automatically logged in with a session token.
  • User is redirected to the Influencer Dashboard (Referral System tab).
  • Welcome email is sent to the user's registered email address with instructions on using the referral program.

6.2 Payment Details Saved Successfully

• Operation: User submits the Payment Details form with valid bank account information.
• Success Message: "Payment details saved successfully. You're all set to receive your referral earnings!"
• Trigger Condition: All payment detail fields pass validation and are successfully saved in the database.
• Post-Success Action:
  • Success message is displayed as a green alert banner at the top of the page for 5 seconds.
  • User remains on the Payment Details page with the form fields pre-filled with saved data.
  • Any pending "Unpaid" payouts are now eligible for processing in the next payout cycle.

6.3 Referral Link Copied

• Operation: User clicks "Copy Link" button on the Referral System tab.
• Success Message: "Referral link copied to clipboard!"
• Trigger Condition: Referral link is successfully copied to the user's clipboard.
• Post-Success Action: Success message is displayed as a toast notification for 3-5 seconds and then auto-dismisses.

6.4 Payout Processed Successfully

• Operation: System processes a scheduled payout to the influencer's bank account.
• Success Message: Email notification sent: "Your referral payout of $[AMOUNT] has been successfully processed and will arrive in your bank account within 2-3 business days."
• Trigger Condition: Payout transfer is completed successfully by Stripe.
• Post-Success Action:
  • Corresponding row(s) in the Subscription Receipts table are updated from "Unpaid" to "Paid" status.
  • "Next Payout" card is recalculated to reflect remaining scheduled payouts.

6.5 New Referral Signup Notification

• Operation: A new user signs up using the influencer's referral link.
• Success Message: Email notification sent: "Great news! [USER_NAME] signed up for Pixally using your referral link. You'll start earning once they become an active subscriber."
• Trigger Condition: A new user completes signup and creates an account using the referral link.
• Post-Success Action: "Total Referrals" count is incremented by 1 on the dashboard.

6.6 Milestone Reached Notification

• Operation: A referred user reaches a payout milestone (90 days, 6 months, or 12 months active).
• Success Message: Email notification sent: "Congratulations! [USER_NAME] has reached the [MILESTONE] milestone. You've earned $[AMOUNT]! Your payout is scheduled for [DATE]."
• Trigger Condition: A referred user completes the required active duration for a milestone.
• Post-Success Action:
  • Payout amount is added to the "Next Payout" total.
  • New row is added to the Subscription Receipts table with "Unpaid" status.
  • "Total Earnings" card is updated with the pending amount.

7. Error Message Handling

7.1 Signup Form Validation Errors

• All signup form validation errors follow the same logic as described in the "Sign Up Flow for Normal User from Referral URL" FRD:
  • First name validation error
  • Last name validation error
  • Email format validation error
  • Email already registered error
  • Password too short error

7.2 Account Creation Failed (Server Error)

• Error Scenario: User submits valid form data, but the backend API fails to create the account due to a server error.
• Error Message: "We're sorry, something went wrong. Please try again or contact support if the issue persists."
• Trigger Condition: Backend API returns a 500 error or fails to complete account creation.
• Required Action: User attempts to submit the form again or contacts support.
• System Response: Generic error message is displayed at the top of the form as a red alert banner. "Create Account" button is re-enabled for retry.

7.3 Google OAuth Authentication Failed

• Error Scenario: User clicks "Sign Up with Google" but the OAuth authentication fails.
• Error Message: "Unable to sign up with Google. Please try again or use the manual signup form."
• Trigger Condition: Google OAuth flow returns an error or user cancels authorization.
• Required Action: User retries Google signup or uses the manual form.
• System Response: Error message is displayed as a red alert banner at the top of the form.

7.4 Payment Details Validation Errors

7.4.1 Bank Account Number Invalid

• Error Scenario: User submits the Payment Details form with an invalid bank account number (too short, contains non-numeric characters, etc.).
• Error Message: "Please enter a valid bank account number (8-17 digits)."
• Trigger Condition: Bank account number field fails validation.
• Required Action: User corrects the bank account number and resubmits.
• System Response: Red border appears around the field. Error message is displayed below the field in red text.

7.4.2 Routing Number Invalid

• Error Scenario: User submits the Payment Details form with an invalid routing number (not 9 digits, invalid checksum, etc.).
• Error Message: "Routing number must be exactly 9 digits." or "Please enter a valid routing number."
• Trigger Condition: Routing number field fails length or checksum validation.
• Required Action: User corrects the routing number and resubmits.
• System Response: Red border appears around the field. Error message is displayed below the field in red text.

7.4.3 Bank Name Missing

• Error Scenario: User submits the Payment Details form without entering a bank name.
• Error Message: "Please enter your bank name."
• Trigger Condition: Bank name field is empty.
• Required Action: User enters the bank name and resubmits.
• System Response: Red border appears around the field. Error message is displayed below the field in red text.

7.5 Payment Details Save Failed (Server Error)

• Error Scenario: User submits valid payment details, but the backend API fails to save the data due to a server error.
• Error Message: "Unable to save payment details. Please try again or contact support if the issue persists."
• Trigger Condition: Backend API returns an error during save operation.
• Required Action: User attempts to submit the form again or contacts support.
• System Response: Error message is displayed as a red alert banner at the top of the form. "Save changes" button is re-enabled for retry.

7.6 Payment Details Missing at Payout Time

• Error Scenario: A payout is scheduled but the influencer has not provided bank account information.
• Error Message: Email notification sent: "Action Required: Add your payment details to receive your referral earnings of $[AMOUNT]. Visit your Referral System settings to complete setup."
• Trigger Condition: Payout cycle is triggered but no valid bank account is on file.
• Required Action: Influencer navigates to Payment Details tab and adds bank account information.
• System Response: Payout remains in "Unpaid" status until payment details are provided. Once added, payout is processed in the next cycle.

7.7 Payout Processing Failure (Stripe Error)

• Error Scenario: System attempts to process payout but Stripe returns an error (e.g., invalid bank account, insufficient funds, account verification failed).
• Error Message: Email notification sent: "We encountered an issue processing your referral payout of $[AMOUNT]. Please verify your payment details and contact support if the issue persists."
• Trigger Condition: Stripe API returns an error during payout transfer.
• Required Action: Influencer reviews and updates payment details. May need to contact support for assistance.
• System Response: Payout remains in "Unpaid" status. System retries payout in the next cycle after details are corrected.

7.8 Dashboard Loading Failure

• Error Scenario: Influencer logs in but the dashboard fails to load due to network or server issues.
• Error Message: "Unable to load dashboard. Please check your connection and try again."
• Trigger Condition: API request to fetch dashboard data fails or times out.
• Required Action: User refreshes the page or checks internet connection.
• System Response: Error message is displayed on the page with a "Retry" button.

7.9 Unauthorized Access Attempt

• Error Scenario: Influencer attempts to access a restricted Pixally module URL directly (e.g., project management, client portal).
• Error Message: "This feature is only available to Pixally subscribers. Visit our pricing page to learn more."
• Trigger Condition: System detects that the logged-in user has an "Influencer" account type flag and is attempting to access a restricted module.
• Required Action: User remains on the Influencer Dashboard or navigates to the Pixally pricing page to purchase a subscription.
• System Response: Error message is displayed as a notification banner. User is redirected to the Influencer Dashboard (Referral System tab).

8. Edge Cases

8.1 Influencer Upgrades to Pixally Subscriber

• Scenario: An influencer decides to purchase a Pixally subscription.
• Handling: The system updates the user's account type from "Influencer" to "Pixally Subscriber". The user retains all referral earnings, payout history, and referral link. After upgrading, the user gains access to the full Pixally platform with all modules visible in the left sidebar menu. The referral dashboard remains accessible via the left sidebar.

8.2 Influencer Signs Up with Email Already Used by Regular User

• Scenario: An influencer attempts to sign up with an email address that is already registered as a Pixally subscriber account.
• Handling: The system displays an error message: "This email is already registered. Please login or use a different email." The influencer cannot create a duplicate account. They must either log in with the existing account or use a different email address.

8.3 Influencer Attempts to Access Full Pixally Platform Without Subscription

• Scenario: An influencer tries to navigate to a Pixally module URL (e.g., /dashboard, /projects, /clients) directly.
• Handling: The system checks the user's account type flag. Since the account is marked as "Influencer", access is denied. The system redirects the user to the Influencer Dashboard with an error message: "This feature is only available to Pixally subscribers. Visit our pricing page to learn more."

8.4 Influencer Shares Referral Link but Signs Up as Regular User

• Scenario: An influencer shares their referral link, and another influencer (not a regular user) signs up using that link to become an influencer.
• Handling: The system counts the signup as a valid referral. However, since the referred user is also an influencer (not a paying Pixally subscriber), no payout milestones will ever be reached unless the referred influencer upgrades to a Pixally subscription. The referrer's "Total Referrals" count is incremented, but no payouts are earned until the referred user becomes a paying subscriber.

8.5 Influencer Deletes Account After Earning Payouts

• Scenario: An influencer deletes their account after earning referral payouts that are still in "Unpaid" status.
• Handling: The system marks the account as inactive/deleted. Any "Unpaid" payouts are held and cannot be processed until the influencer reactivates their account or contacts support. "Paid" payouts that have already been transferred are not affected.

8.6 Influencer Adds Invalid Payment Details

• Scenario: Influencer enters an incorrect bank account number or routing number in the Payment Details form.
• Handling: The system performs basic validation (length, format checks) during form submission. If validation passes but the details are incorrect (e.g., account does not exist), Stripe will return an error during payout processing. The influencer receives an email notification prompting them to verify and update payment details. Payouts remain in "Unpaid" status until correct details are provided.

8.7 Influencer Clicks "Already Have an Account? Login" Link

• Scenario: An influencer who already has an account clicks the "Login" link on the signup page.
• Handling: The system redirects the influencer to the standard Pixally login page. After successful login, the system checks the account type flag and redirects the user to the Influencer Dashboard (Referral System tab).

8.8 Multiple People Sign Up as Influencers with Similar Links

• Scenario: Pixally shares the influencer signup link publicly, and multiple people sign up as influencers.
• Handling: Each person receives their own unique referral link. There is no limit to the number of influencers who can join the program. All influencers operate independently and earn payouts based on their own referral activity.

8.9 Influencer Submits Payment Details Multiple Times

• Scenario: Influencer saves payment details, then edits and saves them again multiple times.
• Handling: The system overwrites the previous payment details with the new data each time "Save changes" is clicked. Only the most recent payment details are stored and used for payout processing.

8.10 Influencer Logs in from Multiple Devices

• Scenario: Influencer logs in from desktop and mobile simultaneously.
• Handling: Both devices display the same dashboard data. Updates (e.g., new referral signups, milestone completions) are reflected on both devices upon page refresh or real-time sync (if implemented). No data conflicts occur.

8.11 Influencer Receives Referral Link Before Dashboard is Fully Configured

• Scenario: Influencer signs up but does not immediately add payment details or review the dashboard.
• Handling: The referral link is generated and functional immediately after account creation. The influencer can start sharing the link and tracking referrals. However, payouts cannot be processed until payment details are added. The system sends email reminders prompting the influencer to complete payment setup.

8.12 Influencer Shares Link on Platform with Link Previews (e.g., Facebook)

• Scenario: Influencer shares their referral link on a social media platform that generates automatic link previews.
• Handling: The referral link functions normally. When someone clicks the link from the preview, they are directed to the referral signup page. Attribution is tracked correctly regardless of how the link is displayed.

8.13 Influencer Attempts to Sign Up with Temporary/Disposable Email

• Scenario: Influencer uses a temporary email address (e.g., from Mailinator, TempMail) to sign up.
• Handling: The system does not block disposable emails by default. The account is created successfully. However, the influencer may not receive important email notifications (welcome email, payout notifications) if the temporary email address expires.

8.14 Influencer Forgets Password

• Scenario: Influencer cannot remember their password and needs to reset it.
• Handling: The influencer clicks "Forgot Password?" link on the login page. The system sends a password reset email to the registered email address. The influencer follows the reset link and creates a new password. After resetting, the influencer can log in with the new password.

8.15 Influencer Tries to Change Referral Link

• Scenario: Influencer wants to customize or regenerate their referral link.
• Handling: Referral links are permanent and cannot be edited or regenerated. The system does not provide an option to change the referral code. The influencer must use the assigned link.

9. Acceptance Criteria

9.1 Functional Requirements

• The influencer signup landing page must be accessible via a dedicated URL (e.g., https://yourapp.com/influencer/signup).
• The landing page must display the heading "Join the Referral Partner Program" with descriptive text explaining the program.
• The "Continue to Sign Up" button must navigate the user to the influencer signup form page.
• The signup form must display four fields: First name, Last name, Email address, and Password.
• All form fields must validate according to the specified validation rules.
• The "Create Account" button must create an influencer account with an "Influencer" account type flag.
• The "Sign Up with Google" button must initiate Google OAuth authentication and create an account using Google credentials.
• Upon successful account creation, the user must be automatically logged in and redirected to the Influencer Dashboard.
• The Influencer Dashboard must display only two tabs: "Referral System" and "Payment Details" with no left sidebar menu.
• The Referral System tab must display the same dashboard content as regular Pixally users (summary cards, referral tools, subscription receipts).
• Influencers must earn the same payout structure as regular users ($100 for yearly, milestone-based for monthly).
• The Payment Details tab must allow influencers to add or update bank account information.
• The "Save changes" button must validate and save payment details securely.
• Payouts must be processed on the same monthly schedule via Stripe to the influencer's designated bank account.

9.2 Validation Expectations

• First name and last name fields must accept only alphabetic characters with a minimum length of 2 characters.
• Email field must enforce valid email format and check for uniqueness in the database.
• Password field must enforce a minimum length of 6 characters.
• Bank account number must be numeric and between 8-17 digits.
• Bank routing number must be exactly 9 digits and pass checksum validation.
• If the email is already registered, the system must display the error: "This email is already registered. Please login or use a different email."

9.3 Data Consistency Rules

• Influencer accounts must be flagged with an "Influencer" or "Referral Partner" account type to restrict access to Pixally modules.
• Referral attribution, milestone tracking, and payout processing must function identically for influencers and regular users.
• Payment details must be stored securely and encrypted in the database.
• Referral links must be unique, permanent, and non-editable.
• Email addresses must be unique across all user accounts (influencers and regular users share the same user database).

9.4 User Actions and System Flow Validations

• Clicking the "Continue to Sign Up" button on the landing page must navigate to the signup form page.
• Clicking the "Create Account" button must trigger form validation before submission.
• Clicking the "Sign Up with Google" button must redirect the user to Google's OAuth consent screen.
• Clicking the "Save changes" button on the Payment Details page must validate and save payment information.
• Clicking the "Cancel" button on the Payment Details page must discard changes and return to the Referral System tab.
• After successful account creation, the system must automatically log the user in and redirect them to the Influencer Dashboard.
• Influencers must not be able to access restricted Pixally modules without upgrading to a subscription.

10. Dependencies

10.1 Internal Module Dependencies

• Referral System Module: The Influencer Dashboard relies on the Referral System module for all referral tracking, earnings calculations, and payout processing logic.
• User Authentication Module: The influencer signup and login process integrates with the User Authentication module to create user credentials, hash passwords, generate session tokens, and handle Google OAuth authentication.
• Payment Module: The Payment Details functionality integrates with the Payment module to store and validate bank account information and process payouts via Stripe.
• Notifications Module: The Notifications module sends email notifications to influencers for welcome messages, new referrals, milestone achievements, payout processing, and payment detail reminders.

10.2 External Service Dependencies

• Google OAuth API: Required for "Sign Up with Google" functionality. Google OAuth must be configured with valid API credentials (Client ID, Client Secret) and redirect URIs.
• Stripe API: Required for payout processing. Stripe must be configured to handle transfers to influencers' bank accounts. Stripe's processing fees are deducted from payouts.
• Email Service Provider (e.g., SendGrid, Mailgun): Required for sending transactional email notifications to influencers.
• reCAPTCHA (Optional but Recommended): Google reCAPTCHA can be integrated to prevent bot signups.

10.3 Configuration Requirements

• Influencer Signup URL: The system must have a configured URL for the influencer signup landing page (e.g., https://yourapp.com/influencer/signup).
• Account Type Flags: The database must support an account type field to distinguish between "Influencer" and "Pixally Subscriber" accounts.
• Google OAuth Credentials: Valid Google OAuth Client ID and Client Secret must be configured in the system's environment variables.
• Stripe Account Configuration: A valid Stripe account must be set up with payout capabilities enabled.
• Referral Link Base URL: The system must have a configured base URL (e.g., https://yourapp.com/ref/) to generate referral links.

10.4 Expected System Behavior if Dependencies Fail

• Referral System Module Failure: If the Referral System module is unavailable, the Influencer Dashboard cannot display earnings data. Users see an error message prompting them to try again later.
• User Authentication Module Failure: If the User Authentication module is unavailable, account creation and login fail. Users see an error message: "We're sorry, something went wrong. Please try again later."
• Google OAuth API Failure: If Google OAuth is down or returns errors, the "Sign Up with Google" button displays an error message. Users can still sign up using the manual form.
• Stripe API Failure: If Stripe is down or returns errors, payouts fail and remain in "Unpaid" status. Users are notified of the issue and the system retries in the next payout cycle.
• Email Service Failure: If the email service is unavailable, notification emails are queued and sent once the service is restored. The signup and payout processes are not blocked.
• Payment Module Failure: If the Payment module is unavailable, payment details cannot be saved or retrieved. Users see an error message prompting them to try again later. Payouts are delayed until the module is restored.

11. References

Figma Links

• Influencer Signup Landing Page: Image 6 - influsignuplink.png
• Influencer Signup Form Page: Image 7 - influsignuplinkstep1.png
• Influencer Dashboard (Referral System Tab): Image 4 - influedashboard.png
• Influencer Dashboard (Payment Details Tab): Image 5 - influepaymentdashboard.png

Related Documents

• Referral Logic Discussion: referral-logic-discusison.rtf
• Client Meeting MOM (NotebookLM Notes): Provided in project documentation
• Referral System for Pixally User FRD: Related document for understanding shared referral logic

External References

• Stripe Payouts API Documentation: https://stripe.com/docs/payouts
• Google OAuth Documentation: https://developers.google.com/identity/protocols/oauth2
• Google Sign-In Button Guidelines: https://developers.google.com/identity/branding-guidelines
• reCAPTCHA Documentation: https://developers.google.com/recaptcha/docs/display

End of Document

Deprecated

✅ Influencer Sign Up and Dashboard

1. Module Overview

Module Name

Influencer Sign Up and Dashboard

Purpose

The Influencer Sign Up and Dashboard module enables influencers, content creators, and brand ambassadors to join Pixally's Referral Partner Program without requiring a Pixally subscription. The module provides a dedicated signup flow for influencers and a streamlined dashboard that allows them to access their referral tools, track earnings, manage payment details, and view subscription receipts—all without needing to navigate the full Pixally platform.

Business Goals

• Expand Pixally's reach by enabling influencers with engaged audiences to promote the platform and earn referral commissions without being Pixally customers themselves.
• Provide a simplified, influencer-focused user experience that removes unnecessary features and focuses solely on referral program management.
• Drive user acquisition through influencer marketing by incentivizing external advocates with the same payout structure as regular Pixally users.
• Establish a scalable referral partner ecosystem that complements the existing user-based referral program.

2. User Roles & Permissions

Roles with Access

• Influencer (Referral Partner): Any individual who signs up as an influencer through the dedicated influencer signup link. Influencers do not need to be Pixally subscribers.

Permissions

• View: Influencers can view their referral dashboard, including earnings summary, total referrals count, next payout date, referral link, and subscription receipts table.
• Copy: Influencers can copy their unique referral link to share with their audience.
• Share: Influencers can directly share their referral link via social media platforms (X, Facebook, LinkedIn) or email.
• Access "How it Works" Information: Influencers can view a modal explaining the referral program's payout structure and terms.
• Manage Payment Details: Influencers can add or update their bank account information to receive referral payouts (via the Payment Details tab).
• No Access to Full Pixally Platform: Influencers do not have access to other Pixally modules (e.g., project management, client portal, proposals) unless they separately sign up as a Pixally subscriber.
• No Edit Permissions on Referral Link: Influencers cannot edit or regenerate their referral link once created.
• No Delete Permissions: Influencers cannot delete referral history or subscription receipt records.

3. User Flow

Step-by-Step Navigation Sequence

Part A: Influencer Signup Flow

1. Receive Influencer Signup Link:
   • Pixally shares a dedicated influencer signup link (e.g., https://yourapp.com/influencer/signup) with potential influencers via email, social media, or direct outreach.
   • The influencer clicks the signup link.
2. Land on Influencer Signup Landing Page:
   • The system loads the influencer signup landing page with a hero image on the left and signup information on the right.
   • The page displays the Pixally logo at the top right.
   • The main heading reads: "Join the Referral Partner Program".
   • The subheading explains: "Earn cash rewards by sharing Pixally — no subscription required!"
   • A description explains: "You don't need to be a Pixally customer to benefit. If you have an engaged audience on Instagram, YouTube, or other platforms, you can start earning today by introducing your followers to our services."
3. Click "Continue to Sign Up" Button:
   • The influencer clicks the prominent "Continue to Sign Up" button.
   • The system navigates to the influencer signup form page.
4. View Influencer Signup Form:
   • The signup form page displays the Pixally logo at the top right.
   • The main heading reads: "Join the Referral Partner Program".
   • The form displays four input fields:
     • First name
     • Last name
     • Email address
     • Password (with show/hide toggle)
   • Below the form fields, a "Create Account" button is displayed.
5. Fill Out Signup Form:
   • The influencer enters their first name, last name, email address, and password.
   • The system validates each field according to the validation rules.
6. Alternative: Sign Up with Google:
   • Instead of filling out the manual form, the influencer can click the "Sign Up with Google" button located below the "Create Account" button.
   • The system redirects the influencer to Google's OAuth authentication screen.
   • Upon successful authorization, the system creates an influencer account using Google credentials.
7. Review Terms and Conditions:
   • At the bottom of the form, the page displays: "By signing up, you agree to our Terms & Conditions" (with clickable link).
   • Below that: "This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply." (with clickable links).
8. Submit Signup Form:
   • The influencer clicks the "Create Account" button to submit the form.
   • The system validates all fields and creates an influencer account.
9. Account Creation and Dashboard Access:
   • Upon successful account creation, the system logs the influencer in automatically.
   • The system redirects the influencer to their Influencer Dashboard.

Part B: Influencer Dashboard Navigation

1. Access Influencer Dashboard:
   • After signup or subsequent logins, the influencer lands on the Influencer Dashboard.
   • The dashboard displays a simplified interface with only two tabs in the top center navigation: "Referral System" and "Payment Details".
   • The "Referral System" tab is selected by default.
2. View Dashboard Summary:
   • The dashboard displays the main heading: "Earn with Our Referral Program" with subtitle "We love when you share Pixally with friends — and we want to thank you for it!".
   • Three summary cards are displayed: "Next Payouts", "Total Earnings", and "Total Referrals".
3. Review Earnings and Referral Tools:
   • The influencer reviews their earnings, next payout amount, and total referrals.
   • The influencer scrolls to the "Your Referral Tools" section to view their unique referral link.
   • The influencer can copy the link or share it via social media using the "Quick Share" buttons.
4. Access "How it Works" Modal:
   • The influencer clicks the "How it Works" button in the top-right corner.
   • The system displays the same modal as shown to regular Pixally users, explaining the payout structure.
5. Review Subscription Receipts:
   • The influencer scrolls to the "Subscription Receipts" section to view a table of all payouts and referral activity.
   • The influencer can sort the table by clicking column headers.
6. Navigate to Payment Details:
   • The influencer clicks the "Payment Details" tab in the top navigation.
   • The system navigates to the Payment Details page where the influencer can add or update bank account information.
7. Add Payment Details:
   • The influencer fills out the form with: Business bank account number, Business bank routing number, and Business bank name.
   • The influencer clicks "Save changes" to submit the payment information.
8. Logout:
   • The influencer can click their profile icon/name in the top right corner to access account settings or logout.
   • Upon logout, the influencer is redirected to the standard Pixally login page.

4. Functional Logic

4.1 Influencer Signup Landing Page

4.1.1 Page Access and Display

• The influencer signup landing page is accessible via a dedicated URL (e.g., https://yourapp.com/influencer/signup).
• The page is publicly accessible (no authentication required) and can be shared with potential influencers via any channel.
• The page layout is divided into two sections: a left hero image section and a right content section.

4.1.2 Visual Design and Branding

• The left section displays a lifestyle/creative professional hero image to create an aspirational and engaging visual experience.
• The right section contains the Pixally logo at the top, followed by the main heading, description, and "Continue to Sign Up" button.
• The page uses Pixally's brand colors and typography to maintain consistency with the main platform.

4.1.3 Content and Messaging

• The main heading reads: "Join the Referral Partner Program".
• The description explains the program's value proposition:
  • "Earn cash rewards by sharing Pixally — no subscription required!"
  • "You don't need to be a Pixally customer to benefit. If you have an engaged audience on Instagram, YouTube, or other platforms, you can start earning today by introducing your followers to our services."
• The messaging emphasizes that influencers do not need to purchase a Pixally subscription to participate and earn money.

4.1.4 Continue to Sign Up Button

• A prominent yellow/gold "Continue to Sign Up" button is displayed below the description.
• When the user clicks the button, the system navigates to the influencer signup form page.

4.1.5 Legal Disclaimers

• At the bottom of the page, small text displays: "By signing up, you agree to our Terms & Conditions" (with clickable link).
• Below that: "This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply." (with clickable links).

4.2 Influencer Signup Form Page

4.2.1 Page Layout and Branding

• The influencer signup form page follows the same visual structure as the landing page: left hero image, right form section.
• The right section displays the Pixally logo, main heading "Join the Referral Partner Program", and the signup form.

4.2.2 Form Fields and Input

• The form displays four input fields:
  1. First name: Text input with placeholder "First name".
  2. Last name: Text input with placeholder "Last name".
  3. Email address: Email input with placeholder "Email address".
  4. Password: Password input with placeholder "Password" and hint "6+ characters". Includes a show/hide toggle icon.

4.2.3 Form Validation

• Each field is validated according to the same rules as the regular referral signup flow (see Field Details & Validations section below).
• Real-time or on-blur validation is performed as the user types or moves to the next field.
• Invalid fields are highlighted with a red border and error messages are displayed below the field.

4.2.4 Create Account Button

• A yellow/gold "Create Account" button is displayed below the form fields.
• When clicked, the system validates all fields and submits the form if validations pass.
• Upon submission, the button is disabled and a loading spinner is displayed to prevent duplicate submissions.

4.2.5 Sign Up with Google Option

• Below the "Create Account" button, a separator line displays "OR".
• A "Sign Up with Google" button is displayed with the Google logo.
• When clicked, the system initiates Google OAuth authentication flow (same logic as regular referral signup).

4.2.6 Already Have an Account Link

• At the bottom of the form, the page displays: "Already have an account? Login" (with clickable "Login" link).
• Clicking the "Login" link redirects the user to the standard Pixally login page.
• Influencers log in using the same credentials as regular users, but their dashboard experience is restricted to referral-related features only.

4.3 Influencer Account Creation

4.3.1 Account Type Flag

• When an influencer account is created via the influencer signup flow, the system sets an "influencer" or "referral_partner" account type flag in the user database.
• This flag distinguishes influencer accounts from regular Pixally subscriber accounts.
• The flag determines which modules and features the user can access after login.

4.3.2 Account Creation Process

• The system creates a new user record in the database with the following information:
  • User's first name and last name
  • User's email address (unique identifier)
  • Hashed password (securely stored)
  • Account type: "Influencer" or "Referral Partner"
  • Account creation timestamp
  • User status: Active
• The system generates a unique referral link for the influencer following the same format as regular users: https://yourapp.com/ref/\[UNIQUE\_CODE\].

4.3.3 Post-Creation Actions

• Upon successful account creation, the system generates a session token to authenticate the influencer.
• The system logs the influencer in automatically (no additional login required).
• The system redirects the influencer to the Influencer Dashboard (Referral System tab).
• The system sends a welcome email to the influencer's registered email address with instructions on how to use the referral program.

4.4 Influencer Dashboard - Layout and Access Control

4.4.1 Simplified Navigation

• Unlike regular Pixally users who see a full left sidebar menu with multiple modules, influencers see a simplified interface with NO left sidebar menu.
• The influencer dashboard only displays two tabs in the top center navigation: "Referral System" and "Payment Details".
• The "Referral System" tab is selected by default when the influencer logs in.

4.4.2 Access Restrictions

• Influencers do not have access to other Pixally modules such as:
  • My Profile
  • General Settings
  • Business & Payment Details (for Pixally subscription)
  • Team Management
  • 2-Step Verification
  • AI Preferences
  • Notifications
  • Brands
  • Subscription (for Pixally plans)
• If an influencer attempts to access restricted URLs directly, the system redirects them to the Referral System dashboard with a message: "This feature is only available to Pixally subscribers. Visit our pricing page to learn more."

4.4.3 Top Navigation Bar

• The top navigation bar displays:
  • Pixally logo on the left (clicking it redirects to the Referral System dashboard).
  • Two tabs in the center: "Referral System" and "Payment Details".
  • User profile icon/name on the right with a dropdown menu for account settings and logout.

4.5 Influencer Dashboard - Referral System Tab

4.5.1 Dashboard Content

• The Referral System tab displays the exact same content and functionality as the regular Pixally user's referral dashboard:
  • Main heading: "Earn with Our Referral Program"
  • Three summary cards: "Next Payouts", "Total Earnings", "Total Referrals"
  • "Your Referral Tools" section with referral link, "Copy Link" button, and "Quick Share" buttons
  • "How it Works" button in the top-right corner
  • "Subscription Receipts" table displaying payout history

4.5.2 Functional Behavior

• All functional logic for the Referral System tab is identical to the regular Pixally user's referral dashboard (see "Referral System for Pixally User" FRD for detailed functional logic).
• Influencers earn the same payout structure as regular users:
  • Yearly plan referrals: $100 after 90 days active.
  • Monthly plan referrals: Milestone-based payouts ($15, $25, $60).
• Payouts are processed on the same monthly schedule via Stripe to the influencer's designated bank account.

4.6 Influencer Dashboard - Payment Details Tab

4.6.1 Tab Navigation

• When the influencer clicks the "Payment Details" tab in the top navigation, the system navigates to the Payment Details page.
• The "Payment Details" tab is highlighted to indicate the current active tab.

4.6.2 Payment Details Page Layout

• The page displays a heading: "Set Up Your Payout Details".
• Below the heading, a subtitle explains: "Add or update your payment information to ensure you receive your referral rewards quickly and securely."
• The page displays a form with three input fields:
  1. Business bank account number: Text input for bank account number.
  2. Business bank routing number: Text input for bank routing number.
  3. Business bank name: Text input for bank name.

4.6.3 Form Field Display and Input

• Each field has a label above it indicating the field name.
• Input fields display placeholder text to guide the user (e.g., "Enter account number", "Enter routing number", "Enter bank name").
• All fields are required for payout processing.

4.6.4 Save Changes and Cancel Buttons

• At the bottom of the form, two buttons are displayed:
  • "Cancel" button: Gray/neutral button that discards changes and returns the user to the Referral System tab.
  • "Save changes" button: Yellow/gold button that submits the form and saves the payment details.

4.6.5 Form Validation

• All three fields are required (cannot be empty).
• Bank account number must be numeric and meet minimum length requirements (typically 8-17 digits depending on the bank).
• Bank routing number must be exactly 9 digits (for US banks) and must be a valid routing number.
• Bank name is a text field with no strict validation (minimum 2 characters).

4.6.6 Form Submission and Saving

• When the influencer clicks "Save changes", the system validates all fields.
• If validation passes, the system saves the payment details securely in the database (encrypted).
• The system displays a success message: "Payment details saved successfully. You're all set to receive your referral earnings!".
• If validation fails, error messages are displayed below the corresponding fields with red styling.

4.6.7 Editing Existing Payment Details

• If the influencer has already saved payment details, the form fields are pre-filled with the existing data.
• The influencer can edit any field and click "Save changes" to update the information.
• The system validates and saves the updated details.

4.6.8 Cancel Button Behavior

• When the influencer clicks the "Cancel" button, the system discards any unsaved changes.
• The system navigates back to the Referral System tab.
• If the influencer had previously saved payment details, those details remain unchanged.

4.7 Payout Processing for Influencers

4.7.1 Same Payout Structure as Regular Users

• Influencers earn referral payouts using the exact same structure as regular Pixally users:
  • Yearly plan referrals: $100 flat payout after the referred user remains active for 90 consecutive days.
  • Monthly plan referrals: Milestone-based payouts:
    • $15 after 90 days active
    • $25 after 6 months active (total $40)
    • $60 after 12 months active (total $100)

4.7.2 Payout Schedule and Transfer

• Payouts are processed on the same monthly schedule as regular users (e.g., on the 1st of every month).
• All eligible payouts are transferred to the influencer's designated bank account via Stripe.
• Stripe processing fees are deducted from the payout amount (same as regular users).

4.7.3 Payment Details Requirement

• Before the first payout can be processed, the influencer must provide valid bank account information in the Payment Details section.
• If payment details are missing at payout time, the payout is held in "Unpaid" status and the influencer receives an email notification prompting them to add payment details.
• Once payment details are added, held payouts are processed in the next payout cycle.

4.8 Referral Link Attribution and Tracking

4.8.1 Same Attribution Logic

• Influencer referral links function identically to regular user referral links.
• When a new user clicks an influencer's referral link and signs up, the system attributes the referral to the influencer's account.
• Referral tracking, milestone calculations, and payout processing follow the same logic as described in the "Referral System for Pixally User" FRD.

4.8.2 No Duplicate Prevention

• The system does not block referrals based on IP address, device, payment card, or email domain (same as regular users).
• Each valid signup is counted as a separate referral regardless of source.

4.9 Login and Authentication

4.9.1 Login Process

• Influencers log in using the standard Pixally login page with their registered email and password.
• Alternatively, influencers can log in using Google OAuth if they signed up with Google.
• After successful login, the system checks the user's account type flag.
• If the account type is "Influencer" or "Referral Partner", the system redirects the user to the Influencer Dashboard (Referral System tab) with restricted access.
• If the account type is "Pixally Subscriber", the system redirects the user to the full Pixally platform dashboard with all modules accessible.

4.9.2 Session Management

• Influencer sessions are managed using the same authentication system as regular users.
• Session tokens expire based on the same timeout rules.
• Influencers can remain logged in across multiple devices if the platform supports multi-device sessions.

4.10 Influencer to Subscriber Conversion

4.10.1 Upgrade Path

• If an influencer decides to become a Pixally subscriber, they can navigate to the Pixally pricing page and purchase a subscription.
• Upon subscription purchase, the system updates the user's account type flag from "Influencer" to "Pixally Subscriber".
• The user retains their existing referral earnings and payout history.
• After upgrading, the user gains access to the full Pixally platform (all modules) in addition to the Referral System.
• The left sidebar menu becomes visible, providing access to all Pixally features.

4.10.2 Referral Earnings Continuity

• All previously earned referral payouts and ongoing milestone tracking continue seamlessly after the influencer upgrades to a subscriber.
• The referral link remains the same (no new link is generated).
• Total Earnings, Total Referrals, and Subscription Receipts history are fully preserved.

4.11 Empty State Handling

4.11.1 New Influencer with No Referrals

• When an influencer first logs in and has not generated any referrals, the dashboard displays:
  • "Next Payout" card showing $0.00 with "Expected: N/A".
  • "Total Earnings" card showing $0.00 with "0 active users".
  • "Total Referrals" card showing 0 with "0 active users".
  • The "Subscription Receipts" table displays an empty state message: "No referrals yet. Start sharing your link to earn rewards!".

4.11.2 Payment Details Not Added

• If an influencer has not yet added payment details, the Payment Details form displays empty input fields.
• A helper message is displayed: "Add your payment information to ensure you receive your referral rewards quickly and securely."
• If a payout becomes due before payment details are added, the influencer receives an email reminder to complete payment setup.

4.12 Impact on Other Modules

4.12.1 Integration with Referral System Module

• Influencer accounts integrate seamlessly with the existing Referral System module.
• All referral tracking, milestone calculations, and payout processing logic is shared between regular users and influencers (no separate logic required).
• The only difference is the user interface (simplified dashboard for influencers vs. full platform dashboard for regular users).

4.12.2 Integration with User Authentication Module

• Influencer signup and login are handled by the same User Authentication module as regular users.
• The account type flag is used to determine post-login redirection and feature access.

4.12.3 Integration with Payment Module

• Influencer payout processing uses the same Payment module and Stripe integration as regular users.
• Payment details are stored and validated using the same secure processes.

4.12.4 Integration with Notifications Module

• Influencers receive the same email notifications as regular users:
  • Welcome email upon signup
  • New referral signup notifications
  • Milestone reached notifications
  • Payout processed notifications
  • Payment details reminder notifications

5. Field Details & Validations

5.1 First Name Field (Signup Form)

• Field Name: First name
• Field Type: Text Input
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 2 characters.
  • Maximum length: 50 characters.
  • Must contain only alphabetic characters (letters, spaces, hyphens, apostrophes allowed).
  • No numbers or special characters (except hyphen and apostrophe).
• Error Message: "Please enter a valid first name."

5.2 Last Name Field (Signup Form)

• Field Name: Last name
• Field Type: Text Input
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 2 characters.
  • Maximum length: 50 characters.
  • Must contain only alphabetic characters (letters, spaces, hyphens, apostrophes allowed).
  • No numbers or special characters (except hyphen and apostrophe).
• Error Message: "Please enter a valid last name."

5.3 Email Address Field (Signup Form)

• Field Name: Email address
• Field Type: Email Input
• Validation Rules:
  • Required (cannot be empty).
  • Must be a valid email format (e.g., user@example.com).
  • Must contain "@" symbol and a valid domain.
  • Must not already exist in the Pixally user database (unique constraint).
• Error Messages:
  • Invalid format: "Please enter a valid email address."
  • Already registered: "This email is already registered. Please login or use a different email."

5.4 Password Field (Signup Form)

• Field Name: Password
• Field Type: Password Input (with show/hide toggle)
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 6 characters.
  • No maximum length (practical limit of 128 characters).
  • Can contain letters (uppercase and lowercase), numbers, and special characters.
• Error Message: "Password must be at least 6 characters long."

5.5 Business Bank Account Number Field (Payment Details)

• Field Name: Business bank account number
• Field Type: Text Input (Numeric)
• Validation Rules:
  • Required (cannot be empty).
  • Must contain only numeric digits.
  • Minimum length: 8 digits.
  • Maximum length: 17 digits.
  • No special characters or spaces allowed.
• Error Message: "Please enter a valid bank account number (8-17 digits)."

5.6 Business Bank Routing Number Field (Payment Details)

• Field Name: Business bank routing number
• Field Type: Text Input (Numeric)
• Validation Rules:
  • Required (cannot be empty).
  • Must be exactly 9 digits (for US banks).
  • Must be a valid routing number (checksum validation via Stripe or internal algorithm).
  • No special characters or spaces allowed.
• Error Messages:
  • Invalid length: "Routing number must be exactly 9 digits."
  • Invalid format: "Please enter a valid routing number."

5.7 Business Bank Name Field (Payment Details)

• Field Name: Business bank name
• Field Type: Text Input
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 2 characters.
  • Maximum length: 100 characters.
  • Can contain letters, numbers, spaces, and basic punctuation.
• Error Message: "Please enter your bank name."

5.8 Dashboard Summary Fields (Read-Only)

• All dashboard summary fields (Next Payout, Total Earnings, Total Referrals, Active Users) follow the same validation rules as described in the "Referral System for Pixally User" FRD.

6. Success Message Handling

6.1 Influencer Account Created Successfully

• Operation: User submits the signup form with valid data or completes Google OAuth signup.
• Success Message: No explicit success message on the signup page. User is immediately redirected to the Influencer Dashboard.
• Trigger Condition: Account creation is successful and the user record is saved in the database with "Influencer" account type flag.
• Post-Success Action:
  • User is automatically logged in with a session token.
  • User is redirected to the Influencer Dashboard (Referral System tab).
  • Welcome email is sent to the user's registered email address with instructions on using the referral program.

6.2 Payment Details Saved Successfully

• Operation: User submits the Payment Details form with valid bank account information.
• Success Message: "Payment details saved successfully. You're all set to receive your referral earnings!"
• Trigger Condition: All payment detail fields pass validation and are successfully saved in the database.
• Post-Success Action:
  • Success message is displayed as a green alert banner at the top of the page for 5 seconds.
  • User remains on the Payment Details page with the form fields pre-filled with saved data.
  • Any pending "Unpaid" payouts are now eligible for processing in the next payout cycle.

6.3 Referral Link Copied

• Operation: User clicks "Copy Link" button on the Referral System tab.
• Success Message: "Referral link copied to clipboard!"
• Trigger Condition: Referral link is successfully copied to the user's clipboard.
• Post-Success Action: Success message is displayed as a toast notification for 3-5 seconds and then auto-dismisses.

6.4 Payout Processed Successfully

• Operation: System processes a scheduled payout to the influencer's bank account.
• Success Message: Email notification sent: "Your referral payout of $[AMOUNT] has been successfully processed and will arrive in your bank account within 2-3 business days."
• Trigger Condition: Payout transfer is completed successfully by Stripe.
• Post-Success Action:
  • Corresponding row(s) in the Subscription Receipts table are updated from "Unpaid" to "Paid" status.
  • "Next Payout" card is recalculated to reflect remaining scheduled payouts.

6.5 New Referral Signup Notification

• Operation: A new user signs up using the influencer's referral link.
• Success Message: Email notification sent: "Great news! [USER_NAME] signed up for Pixally using your referral link. You'll start earning once they become an active subscriber."
• Trigger Condition: A new user completes signup and creates an account using the referral link.
• Post-Success Action: "Total Referrals" count is incremented by 1 on the dashboard.

6.6 Milestone Reached Notification

• Operation: A referred user reaches a payout milestone (90 days, 6 months, or 12 months active).
• Success Message: Email notification sent: "Congratulations! [USER_NAME] has reached the [MILESTONE] milestone. You've earned $[AMOUNT]! Your payout is scheduled for [DATE]."
• Trigger Condition: A referred user completes the required active duration for a milestone.
• Post-Success Action:
  • Payout amount is added to the "Next Payout" total.
  • New row is added to the Subscription Receipts table with "Unpaid" status.
  • "Total Earnings" card is updated with the pending amount.

7. Error Message Handling

7.1 Signup Form Validation Errors

• All signup form validation errors follow the same logic as described in the "Sign Up Flow for Normal User from Referral URL" FRD:
  • First name validation error
  • Last name validation error
  • Email format validation error
  • Email already registered error
  • Password too short error

7.2 Account Creation Failed (Server Error)

• Error Scenario: User submits valid form data, but the backend API fails to create the account due to a server error.
• Error Message: "We're sorry, something went wrong. Please try again or contact support if the issue persists."
• Trigger Condition: Backend API returns a 500 error or fails to complete account creation.
• Required Action: User attempts to submit the form again or contacts support.
• System Response: Generic error message is displayed at the top of the form as a red alert banner. "Create Account" button is re-enabled for retry.

7.3 Google OAuth Authentication Failed

• Error Scenario: User clicks "Sign Up with Google" but the OAuth authentication fails.
• Error Message: "Unable to sign up with Google. Please try again or use the manual signup form."
• Trigger Condition: Google OAuth flow returns an error or user cancels authorization.
• Required Action: User retries Google signup or uses the manual form.
• System Response: Error message is displayed as a red alert banner at the top of the form.

7.4 Payment Details Validation Errors

7.4.1 Bank Account Number Invalid

• Error Scenario: User submits the Payment Details form with an invalid bank account number (too short, contains non-numeric characters, etc.).
• Error Message: "Please enter a valid bank account number (8-17 digits)."
• Trigger Condition: Bank account number field fails validation.
• Required Action: User corrects the bank account number and resubmits.
• System Response: Red border appears around the field. Error message is displayed below the field in red text.

7.4.2 Routing Number Invalid

• Error Scenario: User submits the Payment Details form with an invalid routing number (not 9 digits, invalid checksum, etc.).
• Error Message: "Routing number must be exactly 9 digits." or "Please enter a valid routing number."
• Trigger Condition: Routing number field fails length or checksum validation.
• Required Action: User corrects the routing number and resubmits.
• System Response: Red border appears around the field. Error message is displayed below the field in red text.

7.4.3 Bank Name Missing

• Error Scenario: User submits the Payment Details form without entering a bank name.
• Error Message: "Please enter your bank name."
• Trigger Condition: Bank name field is empty.
• Required Action: User enters the bank name and resubmits.
• System Response: Red border appears around the field. Error message is displayed below the field in red text.

7.5 Payment Details Save Failed (Server Error)

• Error Scenario: User submits valid payment details, but the backend API fails to save the data due to a server error.
• Error Message: "Unable to save payment details. Please try again or contact support if the issue persists."
• Trigger Condition: Backend API returns an error during save operation.
• Required Action: User attempts to submit the form again or contacts support.
• System Response: Error message is displayed as a red alert banner at the top of the form. "Save changes" button is re-enabled for retry.

7.6 Payment Details Missing at Payout Time

• Error Scenario: A payout is scheduled but the influencer has not provided bank account information.
• Error Message: Email notification sent: "Action Required: Add your payment details to receive your referral earnings of $[AMOUNT]. Visit your Referral System settings to complete setup."
• Trigger Condition: Payout cycle is triggered but no valid bank account is on file.
• Required Action: Influencer navigates to Payment Details tab and adds bank account information.
• System Response: Payout remains in "Unpaid" status until payment details are provided. Once added, payout is processed in the next cycle.

7.7 Payout Processing Failure (Stripe Error)

• Error Scenario: System attempts to process payout but Stripe returns an error (e.g., invalid bank account, insufficient funds, account verification failed).
• Error Message: Email notification sent: "We encountered an issue processing your referral payout of $[AMOUNT]. Please verify your payment details and contact support if the issue persists."
• Trigger Condition: Stripe API returns an error during payout transfer.
• Required Action: Influencer reviews and updates payment details. May need to contact support for assistance.
• System Response: Payout remains in "Unpaid" status. System retries payout in the next cycle after details are corrected.

7.8 Dashboard Loading Failure

• Error Scenario: Influencer logs in but the dashboard fails to load due to network or server issues.
• Error Message: "Unable to load dashboard. Please check your connection and try again."
• Trigger Condition: API request to fetch dashboard data fails or times out.
• Required Action: User refreshes the page or checks internet connection.
• System Response: Error message is displayed on the page with a "Retry" button.

7.9 Unauthorized Access Attempt

• Error Scenario: Influencer attempts to access a restricted Pixally module URL directly (e.g., project management, client portal).
• Error Message: "This feature is only available to Pixally subscribers. Visit our pricing page to learn more."
• Trigger Condition: System detects that the logged-in user has an "Influencer" account type flag and is attempting to access a restricted module.
• Required Action: User remains on the Influencer Dashboard or navigates to the Pixally pricing page to purchase a subscription.
• System Response: Error message is displayed as a notification banner. User is redirected to the Influencer Dashboard (Referral System tab).

8. Edge Cases

8.1 Influencer Upgrades to Pixally Subscriber

• Scenario: An influencer decides to purchase a Pixally subscription.
• Handling: The system updates the user's account type from "Influencer" to "Pixally Subscriber". The user retains all referral earnings, payout history, and referral link. After upgrading, the user gains access to the full Pixally platform with all modules visible in the left sidebar menu. The referral dashboard remains accessible via the left sidebar.

8.2 Influencer Signs Up with Email Already Used by Regular User

• Scenario: An influencer attempts to sign up with an email address that is already registered as a Pixally subscriber account.
• Handling: The system displays an error message: "This email is already registered. Please login or use a different email." The influencer cannot create a duplicate account. They must either log in with the existing account or use a different email address.

8.3 Influencer Attempts to Access Full Pixally Platform Without Subscription

• Scenario: An influencer tries to navigate to a Pixally module URL (e.g., /dashboard, /projects, /clients) directly.
• Handling: The system checks the user's account type flag. Since the account is marked as "Influencer", access is denied. The system redirects the user to the Influencer Dashboard with an error message: "This feature is only available to Pixally subscribers. Visit our pricing page to learn more."

8.4 Influencer Shares Referral Link but Signs Up as Regular User

• Scenario: An influencer shares their referral link, and another influencer (not a regular user) signs up using that link to become an influencer.
• Handling: The system counts the signup as a valid referral. However, since the referred user is also an influencer (not a paying Pixally subscriber), no payout milestones will ever be reached unless the referred influencer upgrades to a Pixally subscription. The referrer's "Total Referrals" count is incremented, but no payouts are earned until the referred user becomes a paying subscriber.

8.5 Influencer Deletes Account After Earning Payouts

• Scenario: An influencer deletes their account after earning referral payouts that are still in "Unpaid" status.
• Handling: The system marks the account as inactive/deleted. Any "Unpaid" payouts are held and cannot be processed until the influencer reactivates their account or contacts support. "Paid" payouts that have already been transferred are not affected.

8.6 Influencer Adds Invalid Payment Details

• Scenario: Influencer enters an incorrect bank account number or routing number in the Payment Details form.
• Handling: The system performs basic validation (length, format checks) during form submission. If validation passes but the details are incorrect (e.g., account does not exist), Stripe will return an error during payout processing. The influencer receives an email notification prompting them to verify and update payment details. Payouts remain in "Unpaid" status until correct details are provided.

8.7 Influencer Clicks "Already Have an Account? Login" Link

• Scenario: An influencer who already has an account clicks the "Login" link on the signup page.
• Handling: The system redirects the influencer to the standard Pixally login page. After successful login, the system checks the account type flag and redirects the user to the Influencer Dashboard (Referral System tab).

8.8 Multiple People Sign Up as Influencers with Similar Links

• Scenario: Pixally shares the influencer signup link publicly, and multiple people sign up as influencers.
• Handling: Each person receives their own unique referral link. There is no limit to the number of influencers who can join the program. All influencers operate independently and earn payouts based on their own referral activity.

8.9 Influencer Submits Payment Details Multiple Times

• Scenario: Influencer saves payment details, then edits and saves them again multiple times.
• Handling: The system overwrites the previous payment details with the new data each time "Save changes" is clicked. Only the most recent payment details are stored and used for payout processing.

8.10 Influencer Logs in from Multiple Devices

• Scenario: Influencer logs in from desktop and mobile simultaneously.
• Handling: Both devices display the same dashboard data. Updates (e.g., new referral signups, milestone completions) are reflected on both devices upon page refresh or real-time sync (if implemented). No data conflicts occur.

8.11 Influencer Receives Referral Link Before Dashboard is Fully Configured

• Scenario: Influencer signs up but does not immediately add payment details or review the dashboard.
• Handling: The referral link is generated and functional immediately after account creation. The influencer can start sharing the link and tracking referrals. However, payouts cannot be processed until payment details are added. The system sends email reminders prompting the influencer to complete payment setup.

8.12 Influencer Shares Link on Platform with Link Previews (e.g., Facebook)

• Scenario: Influencer shares their referral link on a social media platform that generates automatic link previews.
• Handling: The referral link functions normally. When someone clicks the link from the preview, they are directed to the referral signup page. Attribution is tracked correctly regardless of how the link is displayed.

8.13 Influencer Attempts to Sign Up with Temporary/Disposable Email

• Scenario: Influencer uses a temporary email address (e.g., from Mailinator, TempMail) to sign up.
• Handling: The system does not block disposable emails by default. The account is created successfully. However, the influencer may not receive important email notifications (welcome email, payout notifications) if the temporary email address expires.

8.14 Influencer Forgets Password

• Scenario: Influencer cannot remember their password and needs to reset it.
• Handling: The influencer clicks "Forgot Password?" link on the login page. The system sends a password reset email to the registered email address. The influencer follows the reset link and creates a new password. After resetting, the influencer can log in with the new password.

8.15 Influencer Tries to Change Referral Link

• Scenario: Influencer wants to customize or regenerate their referral link.
• Handling: Referral links are permanent and cannot be edited or regenerated. The system does not provide an option to change the referral code. The influencer must use the assigned link.

9. Acceptance Criteria

9.1 Functional Requirements

• The influencer signup landing page must be accessible via a dedicated URL (e.g., https://yourapp.com/influencer/signup).
• The landing page must display the heading "Join the Referral Partner Program" with descriptive text explaining the program.
• The "Continue to Sign Up" button must navigate the user to the influencer signup form page.
• The signup form must display four fields: First name, Last name, Email address, and Password.
• All form fields must validate according to the specified validation rules.
• The "Create Account" button must create an influencer account with an "Influencer" account type flag.
• The "Sign Up with Google" button must initiate Google OAuth authentication and create an account using Google credentials.
• Upon successful account creation, the user must be automatically logged in and redirected to the Influencer Dashboard.
• The Influencer Dashboard must display only two tabs: "Referral System" and "Payment Details" with no left sidebar menu.
• The Referral System tab must display the same dashboard content as regular Pixally users (summary cards, referral tools, subscription receipts).
• Influencers must earn the same payout structure as regular users ($100 for yearly, milestone-based for monthly).
• The Payment Details tab must allow influencers to add or update bank account information.
• The "Save changes" button must validate and save payment details securely.
• Payouts must be processed on the same monthly schedule via Stripe to the influencer's designated bank account.

9.2 Validation Expectations

• First name and last name fields must accept only alphabetic characters with a minimum length of 2 characters.
• Email field must enforce valid email format and check for uniqueness in the database.
• Password field must enforce a minimum length of 6 characters.
• Bank account number must be numeric and between 8-17 digits.
• Bank routing number must be exactly 9 digits and pass checksum validation.
• If the email is already registered, the system must display the error: "This email is already registered. Please login or use a different email."

9.3 Data Consistency Rules

• Influencer accounts must be flagged with an "Influencer" or "Referral Partner" account type to restrict access to Pixally modules.
• Referral attribution, milestone tracking, and payout processing must function identically for influencers and regular users.
• Payment details must be stored securely and encrypted in the database.
• Referral links must be unique, permanent, and non-editable.
• Email addresses must be unique across all user accounts (influencers and regular users share the same user database).

9.4 User Actions and System Flow Validations

• Clicking the "Continue to Sign Up" button on the landing page must navigate to the signup form page.
• Clicking the "Create Account" button must trigger form validation before submission.
• Clicking the "Sign Up with Google" button must redirect the user to Google's OAuth consent screen.
• Clicking the "Save changes" button on the Payment Details page must validate and save payment information.
• Clicking the "Cancel" button on the Payment Details page must discard changes and return to the Referral System tab.
• After successful account creation, the system must automatically log the user in and redirect them to the Influencer Dashboard.
• Influencers must not be able to access restricted Pixally modules without upgrading to a subscription.

10. Dependencies

10.1 Internal Module Dependencies

• Referral System Module: The Influencer Dashboard relies on the Referral System module for all referral tracking, earnings calculations, and payout processing logic.
• User Authentication Module: The influencer signup and login process integrates with the User Authentication module to create user credentials, hash passwords, generate session tokens, and handle Google OAuth authentication.
• Payment Module: The Payment Details functionality integrates with the Payment module to store and validate bank account information and process payouts via Stripe.
• Notifications Module: The Notifications module sends email notifications to influencers for welcome messages, new referrals, milestone achievements, payout processing, and payment detail reminders.

10.2 External Service Dependencies

• Google OAuth API: Required for "Sign Up with Google" functionality. Google OAuth must be configured with valid API credentials (Client ID, Client Secret) and redirect URIs.
• Stripe API: Required for payout processing. Stripe must be configured to handle transfers to influencers' bank accounts. Stripe's processing fees are deducted from payouts.
• Email Service Provider (e.g., SendGrid, Mailgun): Required for sending transactional email notifications to influencers.
• reCAPTCHA (Optional but Recommended): Google reCAPTCHA can be integrated to prevent bot signups.

10.3 Configuration Requirements

• Influencer Signup URL: The system must have a configured URL for the influencer signup landing page (e.g., https://yourapp.com/influencer/signup).
• Account Type Flags: The database must support an account type field to distinguish between "Influencer" and "Pixally Subscriber" accounts.
• Google OAuth Credentials: Valid Google OAuth Client ID and Client Secret must be configured in the system's environment variables.
• Stripe Account Configuration: A valid Stripe account must be set up with payout capabilities enabled.
• Referral Link Base URL: The system must have a configured base URL (e.g., https://yourapp.com/ref/) to generate referral links.

10.4 Expected System Behavior if Dependencies Fail

• Referral System Module Failure: If the Referral System module is unavailable, the Influencer Dashboard cannot display earnings data. Users see an error message prompting them to try again later.
• User Authentication Module Failure: If the User Authentication module is unavailable, account creation and login fail. Users see an error message: "We're sorry, something went wrong. Please try again later."
• Google OAuth API Failure: If Google OAuth is down or returns errors, the "Sign Up with Google" button displays an error message. Users can still sign up using the manual form.
• Stripe API Failure: If Stripe is down or returns errors, payouts fail and remain in "Unpaid" status. Users are notified of the issue and the system retries in the next payout cycle.
• Email Service Failure: If the email service is unavailable, notification emails are queued and sent once the service is restored. The signup and payout processes are not blocked.
• Payment Module Failure: If the Payment module is unavailable, payment details cannot be saved or retrieved. Users see an error message prompting them to try again later. Payouts are delayed until the module is restored.

11. References

Figma Links:

https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=30399-30596&t=wFv4ZHUjf46R4nMC-0

✅ Sign Up Flow for Normal User from Referral URL

1. Module Overview

Module Name

Sign Up Flow for Normal User from Referral URL

Purpose

The Sign Up Flow for Normal User from Referral URL module enables new users who click on a referral link to create a Pixally account with exclusive referral discounts applied automatically. The module provides a customized signup experience that displays the referrer's name, the discount offer, and guides the user through account creation while ensuring proper referral attribution for payout tracking.

Business Goals

• Convert referred traffic into new Pixally subscribers by offering attractive signup incentives (50% off first year + extra 10% off first 3 months).
• Ensure accurate referral attribution to enable correct payout calculations for referrers.
• Provide a seamless, user-friendly signup experience that highlights the value proposition of the referral offer.
• Drive user acquisition through word-of-mouth marketing by incentivizing both referrers and referred users.

2. User Roles & Permissions

Roles with Access

• New User (Referred User): Any individual who clicks on a referral link and does not have an existing Pixally account.

Permissions

• View: New users can view the referral signup page displaying the referrer's name and discount offer.
• Create Account: New users can create a Pixally account by filling out the signup form with their personal information.
• Sign Up with Google: New users can create an account using Google OAuth authentication.
• Accept Terms & Conditions: New users must agree to Pixally's Terms & Conditions and Privacy Policy to proceed with signup.
• No Edit Permissions on Referral Attribution: Users cannot change or remove the referral attribution once they land on the referral signup page.

3. User Flow

Step-by-Step Navigation Sequence

1. Click Referral Link:
   • A potential new user receives a referral link from an existing Pixally user via email, social media, or direct message.
   • The referral link follows the format: https://yourapp.com/ref/\[UNIQUE\_CODE\].
   • The user clicks on the referral link.
2. Land on Referral Signup Page:
   • The system loads a customized signup page designed specifically for referral traffic.
   • The page displays the Pixally logo at the top center.
   • The page prominently displays the referrer's name and the discount offer: "[REFERRER_NAME] gave you 60% off first 3 months and 50% off first year".
3. View Signup Form:
   • The page displays a signup form on the right side with the following fields:
     • First name
     • Last name
     • Email address
     • Password
   • Below the form fields, a "Create Account" button is displayed.
4. Fill Out Signup Form:
   • The user enters their first name in the "First name" field.
   • The user enters their last name in the "Last name" field.
   • The user enters their email address in the "Email address" field.
   • The user enters a password (minimum 6+ characters) in the "Password" field with a show/hide toggle icon.
5. Alternative: Sign Up with Google:
   • Instead of filling out the manual form, the user can click the "Sign Up with Google" button located below the "Create Account" button.
   • The system redirects the user to Google's OAuth authentication screen.
   • The user authorizes Pixally to access their Google account information (name, email).
   • Upon successful authorization, the system automatically creates a Pixally account using the user's Google credentials and returns the user to the Pixally platform.
6. Review Terms and Conditions:
   • At the bottom of the form, the page displays a small text: "By signing up, you agree to our Terms & Conditions" (with "Terms & Conditions" as a clickable link).
   • Below that, another line reads: "This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply." (with clickable links for Privacy Policy and Terms of Service).
7. Submit Signup Form:
   • The user clicks the "Create Account" button to submit the form.
   • The system validates all form fields according to the validation rules.
8. Account Creation and Referral Attribution:
   • If all validations pass, the system creates a new Pixally account for the user.
   • The system stores the referral attribution by linking the new user's account to the referrer's unique code captured from the URL.
   • The system applies the referral discount to the user's account: 50% off first year + extra 10% off first 3 months.
9. Redirect to Subscription Selection:
   • After successful account creation, the system redirects the user to the subscription plan selection page where they can choose between monthly or yearly plans.
   • The discount is automatically applied and displayed on the pricing page.
10. Existing Account Login:
    • If the user already has an account, they can click the "Already have an account? Login" link at the bottom of the form.
    • The system redirects the user to the standard login page (referral attribution is not applied if the user logs into an existing account).

4. Functional Logic

4.1 Referral Link Processing

4.1.1 URL Parameter Capture

• When a user clicks a referral link (e.g., https://yourapp.com/ref/ALEX2024), the system captures the unique referral code (ALEX2024) from the URL path.
• The system validates that the referral code exists in the database and is associated with an active Pixally subscriber (referrer).
• If the referral code is valid, the system stores the code in the user's session/cookies to maintain referral attribution throughout the signup process.
• If the referral code is invalid or expired, the system redirects the user to the standard signup page without referral benefits.

4.1.2 Referrer Information Retrieval

• The system queries the database to retrieve the referrer's name (first name and last name or display name) associated with the referral code.
• The retrieved referrer name is used to personalize the signup page heading.

4.2 Referral Signup Page Display

4.2.1 Page Layout and Branding

• The referral signup page is divided into two sections: a left visual section and a right form section.
• The left section displays a hero image (lifestyle/creative professional image) to create an engaging visual experience.
• The right section contains the signup form and all related elements.
• The Pixally logo is displayed at the top center of the right section.

4.2.2 Personalized Heading

• The heading displays the text: "[REFERRER_NAME] gave you 60% off first 3 months and 50% off first year".
• The referrer's name is dynamically populated based on the referral code from the URL.
• The discount percentages are hardcoded as part of the referral offer structure.
• The heading is styled prominently to draw attention to the offer.

4.3 Signup Form Display and Interaction

4.3.1 Form Field Layout

• The form displays four input fields arranged vertically:
  1. First name: A text input field with placeholder text "First name" and pre-filled example "Aaron".
  2. Last name: A text input field with placeholder text "Last name" and pre-filled example "Sanders".
  3. Email address: A text input field with placeholder text "Email address" and pre-filled example "a.sanders@gmail.com".
  4. Password: A password input field with placeholder text "Password" and hint "6+ characters". Includes a show/hide toggle icon (eye icon) to reveal or mask the password.

4.3.2 Field Interaction and Validation

• Each field displays placeholder text to guide the user.
• When a user focuses on a field, the placeholder disappears and the user can begin typing.
• Real-time validation is performed as the user types or upon field blur (when the user clicks outside the field).
• If a validation error occurs, the field is highlighted with a red border and an error message is displayed below the field.

4.4 Form Validation Logic

4.4.1 First Name Validation

• The first name field is required and cannot be empty.
• The field must contain at least 2 characters.
• The field should only contain alphabetic characters (letters, spaces, hyphens, and apostrophes are allowed).
• Special characters and numbers are not allowed.
• If validation fails, the system displays an error message: "Please enter a valid first name."

4.4.2 Last Name Validation

• The last name field is required and cannot be empty.
• The field must contain at least 2 characters.
• The field should only contain alphabetic characters (letters, spaces, hyphens, and apostrophes are allowed).
• Special characters and numbers are not allowed.
• If validation fails, the system displays an error message: "Please enter a valid last name."

4.4.3 Email Address Validation

• The email address field is required and cannot be empty.
• The field must contain a valid email format (e.g., user@example.com).
• The email address must not already be registered in the Pixally system.
• If the email format is invalid, the system displays an error message: "Please enter a valid email address."
• If the email is already registered, the system displays an error message: "This email is already registered. Please login or use a different email."

4.4.4 Password Validation

• The password field is required and cannot be empty.
• The password must be at least 6 characters long.
• The password can contain letters, numbers, and special characters.
• If the password is shorter than 6 characters, the system displays an error message: "Password must be at least 6 characters long."

4.5 Create Account Button Functionality

4.5.1 Button State and Interaction

• The "Create Account" button is styled prominently in yellow/gold color to stand out.
• The button is enabled by default when the page loads.
• When the user clicks the "Create Account" button, the system performs the following actions:
  1. Validates all form fields according to the validation rules defined above.
  2. If any validation fails, the system highlights the problematic field(s) and displays corresponding error messages.
  3. If all validations pass, the system disables the button and displays a loading spinner to prevent duplicate submissions.

4.5.2 Account Creation Process

• The system sends the form data (first name, last name, email, password) to the backend API endpoint for account creation.
• The backend API creates a new user record in the database with the following information:
  • User's first name and last name
  • User's email address (used as the unique identifier)
  • Hashed password (securely stored using encryption)
  • Referral attribution (the referral code captured from the URL is stored and linked to the user's account)
  • Account creation timestamp
  • User status: Active (pending subscription)
• The system applies the referral discount eligibility to the user's account (50% off first year + extra 10% off first 3 months) so that the discount is automatically reflected when the user selects a subscription plan.

4.5.3 Post-Creation Actions

• Upon successful account creation, the system generates a session token/cookie to authenticate the user.
• The system logs the user into their new Pixally account automatically (no additional login required).
• The system redirects the user to the subscription plan selection page where they can choose a monthly or yearly plan.
• The system increments the referrer's "Total Referrals" count by 1 in the Referral System dashboard.
• The system sends a notification email to the referrer informing them of the new signup.

4.6 Sign Up with Google Functionality

4.6.1 Google OAuth Button

• Below the "Create Account" button, a separator line displays "OR" to indicate an alternative signup method.
• A "Sign Up with Google" button is displayed with the Google logo icon.
• When the user clicks the "Sign Up with Google" button, the system initiates Google OAuth authentication flow.

4.6.2 Google OAuth Flow

• The system redirects the user to Google's authentication page.
• The user logs into their Google account (if not already logged in) and grants permission for Pixally to access their basic profile information (name, email).
• Google returns the user to Pixally with an authorization code.
• The system exchanges the authorization code for an access token and retrieves the user's Google profile information (name, email).

4.6.3 Account Creation via Google

• The system checks if the retrieved Google email address is already registered in Pixally.
• If the email is not registered, the system creates a new Pixally account using the Google profile information:
  • First name and last name are extracted from the Google profile.
  • Email address is used as the unique identifier.
  • No password is stored (user will log in via Google OAuth in the future).
  • Referral attribution is applied by linking the referral code to the new account.
  • Referral discount eligibility is applied to the account.
• If the email is already registered, the system displays an error message: "This Google account is already registered. Please login instead."

4.6.4 Post-Google Signup Actions

• Upon successful account creation via Google, the system logs the user in automatically.
• The system redirects the user to the subscription plan selection page.
• The referrer's "Total Referrals" count is incremented by 1.
• The system sends a notification email to the referrer informing them of the new signup.

4.7 Terms & Conditions and Privacy Policy Links

4.7.1 Legal Disclaimers

• At the bottom of the signup form, the system displays the text: "By signing up, you agree to our Terms & Conditions".
• The "Terms & Conditions" text is styled as a clickable link.
• When the user clicks the "Terms & Conditions" link, the system opens the Terms & Conditions page in a new browser tab.
• Below that, the system displays: "This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply."
• "Privacy Policy" and "Terms of Service" are styled as clickable links that open the respective Google policy pages in new tabs.

4.8 Already Have an Account - Login Link

4.8.1 Login Redirect

• At the bottom of the form, the system displays the text: "Already have an account? Login".
• The "Login" text is styled as a clickable link in yellow/gold color.
• When the user clicks the "Login" link, the system redirects the user to the standard Pixally login page.
• If the user logs into an existing account, the referral attribution from the referral URL is not applied (referrals only apply to new account signups).

4.9 Referral Attribution Tracking

4.9.1 Session and Cookie Management

• When a user lands on the referral signup page, the system stores the referral code in both the session and a browser cookie.
• The session stores the referral code temporarily for the duration of the user's browsing session.
• The cookie stores the referral code for a longer period (e.g., 30 days) to ensure attribution is maintained even if the user navigates away and returns later.
• When the user completes the signup process, the system retrieves the referral code from the session/cookie and links it to the newly created account.

4.9.2 Multi-Link Attribution Logic

• If a user clicks multiple different referral links before signing up, the referral is attributed to the link from which the user actually completed the signup process.
• The most recent referral code stored in the session/cookie is used for attribution.
• For example, if User A clicks Referrer X's link, then later clicks Referrer Y's link and signs up from that session, Referrer Y receives the referral credit.

4.10 Discount Application Logic

4.10.1 Discount Eligibility Flag

• When a new user account is created via the referral signup flow, the system sets a "referral discount eligible" flag on the user's account.
• This flag indicates that the user is entitled to receive the referral discount: 50% off first year + extra 10% off first 3 months.

4.10.2 Discount Display on Subscription Page

• When the user is redirected to the subscription plan selection page, the system checks for the "referral discount eligible" flag.
• If the flag is present, the system displays the discounted pricing:
  • Yearly Plan: Original price with 50% off applied, plus a note indicating "Extra 10% off first 3 months" (though yearly plans do not have monthly breakdowns, the equivalent discount is factored into the calculation as per the logic document: 2 months free + 50% off + extra 10% off first 3 months).
  • Monthly Plan: Original monthly price with 50% off applied, plus a note indicating "Extra 10% off first 3 months".
• The discount is automatically applied at checkout when the user selects a plan and completes payment.

4.10.3 Discount Calculation for Yearly Plan

• Original yearly plan price: $39/month × 12 months = $468.
• Apply 2 months free offer: $39 × 10 months = $390.
• Apply 50% off first year: $390 × 50% = $195.
• Apply extra 10% off first 3 months: Calculate 10% discount on the already discounted monthly rate ($19.50) for 3 months = $1.95 × 3 = $5.85 total additional discount.
• Final first-year price: $195 - $5.85 = $189.15.

4.10.4 Discount Calculation for Monthly Plan

• Original monthly plan price: $39/month.
• Apply 50% off: $39 × 50% = $19.50/month.
• Apply extra 10% off for first 3 months: $19.50 × 10% = $1.95 discount per month for 3 months.
• First 3 months pricing: $19.50 - $1.95 = $17.55/month.
• Months 4-12 pricing: $19.50/month (50% off continues, but extra 10% off expires after 3 months).

4.11 Empty State Handling

4.11.1 Invalid or Missing Referral Code

• If a user lands on the referral signup URL but the referral code is invalid (e.g., the code does not exist in the database or the referrer's account is inactive), the system redirects the user to the standard non-referral signup page.
• The user can still create an account, but they will not receive the referral discount and no referral attribution is recorded.

4.11.2 Referral Code Expired (Edge Case)

• Referral codes are designed to be permanent and do not expire. However, if a referrer deletes their account or becomes inactive, their referral code may be deactivated.
• If a user clicks a deactivated referral link, the system redirects them to the standard signup page without referral benefits.

4.12 Impact on Other Modules

4.12.1 Integration with Referral System Module (Referrer Dashboard)

• When a new user signs up via a referral link, the system updates the referrer's Referral System dashboard:
  • Increments the "Total Referrals" count by 1.
  • Sends an email notification to the referrer.
  • Prepares the new referral for milestone tracking (payouts will be calculated once the referred user subscribes and remains active).

4.12.2 Integration with Subscription Module

• After account creation, the system redirects the user to the subscription plan selection page.
• The Subscription module reads the "referral discount eligible" flag and applies the appropriate discount to the pricing display and checkout process.
• The referred user's subscription status and payment activity are tracked by the Subscription module to determine when referral milestones are reached (for payout calculations).

4.12.3 Integration with User Authentication Module

• The signup process integrates with the User Authentication module to create secure user credentials (hashed passwords) and generate session tokens.
• Google OAuth integration relies on the Authentication module to handle third-party login flows.

4.12.4 Integration with Notifications Module

• Upon successful signup, the Notifications module sends a welcome email to the new user.
• The Notifications module also sends a referral signup notification email to the referrer.

5. Field Details & Validations

5.1 First Name Field

• Field Name: First name
• Field Type: Text Input
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 2 characters.
  • Maximum length: 50 characters.
  • Must contain only alphabetic characters (letters, spaces, hyphens, apostrophes allowed).
  • No numbers or special characters (except hyphen and apostrophe).
• Error Message: "Please enter a valid first name."

5.2 Last Name Field

• Field Name: Last name
• Field Type: Text Input
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 2 characters.
  • Maximum length: 50 characters.
  • Must contain only alphabetic characters (letters, spaces, hyphens, apostrophes allowed).
  • No numbers or special characters (except hyphen and apostrophe).
• Error Message: "Please enter a valid last name."

5.3 Email Address Field

• Field Name: Email address
• Field Type: Email Input
• Validation Rules:
  • Required (cannot be empty).
  • Must be a valid email format (e.g., user@example.com).
  • Must contain "@" symbol and a valid domain.
  • Must not already exist in the Pixally user database (unique constraint).
• Error Messages:
  • Invalid format: "Please enter a valid email address."
  • Already registered: "This email is already registered. Please login or use a different email."

5.4 Password Field

• Field Name: Password
• Field Type: Password Input (with show/hide toggle)
• Validation Rules:
  • Required (cannot be empty).
  • Minimum length: 6 characters.
  • No maximum length (but practical limit of 128 characters for security).
  • Can contain letters (uppercase and lowercase), numbers, and special characters.
• Error Message: "Password must be at least 6 characters long."

5.5 Referral Code (Hidden Field)

• Field Name: Referral Code (not visible to user)
• Field Type: Hidden Input / Session Variable
• Validation Rules:
  • Must be a valid alphanumeric string matching a referrer's unique code in the database.
  • Must be associated with an active referrer account.
  • Cannot be manually edited by the user.
• Error Handling: If invalid, redirect to standard signup page without referral benefits.

6. Success Message Handling

6.1 Account Created Successfully

• Operation: User submits the signup form with valid data or completes Google OAuth signup.
• Success Message: No explicit success message is displayed on the signup page. Instead, the user is immediately redirected to the subscription plan selection page.
• Trigger Condition: Account creation is successful and the user record is saved in the database.
• Post-Success Action:
  • User is automatically logged in with a session token.
  • User is redirected to the subscription plan selection page.
  • Welcome email is sent to the user's registered email address.
  • Referrer receives an email notification: "Great news! [USER_NAME] signed up for Pixally using your referral link. You'll start earning once they become an active subscriber."
  • Referrer's "Total Referrals" count is incremented by 1 in their dashboard.

6.2 Referral Link Clicked Successfully

• Operation: User clicks a valid referral link and lands on the referral signup page.
• Success Message: No explicit success message. The page loads with the personalized heading displaying the referrer's name and discount offer.
• Trigger Condition: Referral code in the URL is valid and associated with an active referrer.
• Post-Success Action: Referral code is stored in the user's session/cookie for attribution tracking.

6.3 Google OAuth Signup Completed

• Operation: User completes Google OAuth authentication and account creation.
• Success Message: No explicit success message. User is immediately redirected to the subscription plan selection page.
• Trigger Condition: Google returns user profile data successfully and account is created.
• Post-Success Action: Same as 6.1 (automatic login, redirect, welcome email, referrer notification).

7. Error Message Handling

7.1 First Name Validation Error

• Error Scenario: User submits the form with an empty, too short, or invalid first name.
• Error Message: "Please enter a valid first name."
• Trigger Condition: First name field fails validation (empty, <2 characters, or contains numbers/special characters).
• Required Action: User corrects the first name field and resubmits.
• System Response: Red border appears around the first name field. Error message is displayed below the field in red text.

7.2 Last Name Validation Error

• Error Scenario: User submits the form with an empty, too short, or invalid last name.
• Error Message: "Please enter a valid last name."
• Trigger Condition: Last name field fails validation (empty, <2 characters, or contains numbers/special characters).
• Required Action: User corrects the last name field and resubmits.
• System Response: Red border appears around the last name field. Error message is displayed below the field in red text.

7.3 Email Format Validation Error

• Error Scenario: User submits the form with an invalid email format (e.g., missing "@", invalid domain).
• Error Message: "Please enter a valid email address."
• Trigger Condition: Email address field fails format validation.
• Required Action: User corrects the email address and resubmits.
• System Response: Red border appears around the email field. Error message is displayed below the field in red text.

7.4 Email Already Registered Error

• Error Scenario: User submits the form with an email address that already exists in the Pixally database.
• Error Message: "This email is already registered. Please login or use a different email."
• Trigger Condition: Email uniqueness check fails during backend validation.
• Required Action: User either logs in using the existing account or enters a different email address.
• System Response: Red border appears around the email field. Error message is displayed below the field in red text. The "Login" link in the error message can be clicked to navigate to the login page.

7.5 Password Too Short Error

• Error Scenario: User submits the form with a password shorter than 6 characters.
• Error Message: "Password must be at least 6 characters long."
• Trigger Condition: Password field fails minimum length validation.
• Required Action: User enters a longer password (at least 6 characters) and resubmits.
• System Response: Red border appears around the password field. Error message is displayed below the field in red text.

7.6 Account Creation Failed (Server Error)

• Error Scenario: User submits valid form data, but the backend API fails to create the account due to a server error or database issue.
• Error Message: "We're sorry, something went wrong. Please try again or contact support if the issue persists."
• Trigger Condition: Backend API returns a 500 error or fails to complete account creation.
• Required Action: User attempts to submit the form again or contacts support.
• System Response: A generic error message is displayed at the top of the form as a red alert banner. The "Create Account" button is re-enabled for retry.

7.7 Google OAuth Authentication Failed

• Error Scenario: User clicks "Sign Up with Google" but the OAuth authentication fails (e.g., user denies permission, network error, Google API down).
• Error Message: "Unable to sign up with Google. Please try again or use the manual signup form."
• Trigger Condition: Google OAuth flow returns an error or user cancels the authorization.
• Required Action: User either retries the Google signup or uses the manual form.
• System Response: Error message is displayed as a red alert banner at the top of the form. User remains on the signup page.

7.8 Google Email Already Registered Error

• Error Scenario: User attempts to sign up with Google using an email address that is already registered in Pixally.
• Error Message: "This Google account is already registered. Please login instead."
• Trigger Condition: Email retrieved from Google OAuth already exists in the database.
• Required Action: User navigates to the login page and logs in with their existing account.
• System Response: Error message is displayed as a red alert banner. A "Login" link is provided to redirect the user to the login page.

7.9 Invalid or Expired Referral Code

• Error Scenario: User clicks a referral link with an invalid or deactivated referral code.
• Error Message: No explicit error message displayed to the user.
• Trigger Condition: Referral code in the URL does not exist in the database or is associated with an inactive referrer account.
• Required Action: No action required from the user.
• System Response: User is silently redirected to the standard non-referral signup page. The user can still create an account but will not receive referral benefits.

7.10 Session or Cookie Failure (Edge Case)

• Error Scenario: Referral code cannot be stored in session/cookie due to browser settings (e.g., cookies disabled).
• Error Message: "Please enable cookies in your browser to complete the signup process."
• Trigger Condition: System is unable to set session or cookie data.
• Required Action: User enables cookies in browser settings and reloads the page.
• System Response: Error message is displayed as a red alert banner. Signup form is disabled until cookies are enabled.

8. Edge Cases

8.1 User Clicks Referral Link But Already Has Account

• Scenario: A user who already has a Pixally account clicks a referral link.
• Handling: The system detects that the user is already logged in or has an existing account. The user is redirected to their dashboard or the login page. Referral attribution is not applied (referrals only count for new signups, not existing accounts).

8.2 User Clicks Multiple Referral Links Before Signing Up

• Scenario: A user clicks Referrer A's link, then later clicks Referrer B's link, and then signs up.
• Handling: The referral is attributed to Referrer B (the last referral code stored in the session/cookie). Only Referrer B receives credit for the signup.

8.3 User Navigates Away and Returns Later

• Scenario: A user clicks a referral link, lands on the signup page, navigates away without signing up, and returns days later.
• Handling: If the referral code cookie is still valid (e.g., set to expire after 30 days), the referral attribution is maintained. If the cookie has expired, the user lands on the standard signup page without referral benefits.

8.4 User Submits Form with All Fields Empty

• Scenario: User clicks "Create Account" button without filling out any fields.
• Handling: The system displays validation errors for all required fields (first name, last name, email, password) simultaneously. All fields are highlighted in red with corresponding error messages below each field.

8.5 User Enters Email with Extra Spaces

• Scenario: User enters email address with leading or trailing spaces (e.g., " user@example.com ").
• Handling: The system automatically trims whitespace from the email field during validation. The email is processed correctly without error.

8.6 User Attempts to Sign Up with Disposable/Temporary Email

• Scenario: User enters a temporary or disposable email address (e.g., from services like Mailinator, TempMail).
• Handling: The system does not block disposable emails by default. The account is created successfully. However, if the business decides to block disposable emails in the future, a validation rule can be added to reject known disposable email domains.

8.7 Google OAuth Returns Incomplete Profile Data

• Scenario: Google OAuth authentication succeeds but returns incomplete profile data (e.g., missing last name).
• Handling: The system uses whatever data is available from Google. If the last name is missing, the system may prompt the user to complete their profile after account creation or use the email prefix as a placeholder name.

8.8 User Cancels Google OAuth Authorization

• Scenario: User clicks "Sign Up with Google" but cancels the authorization on Google's consent screen.
• Handling: Google returns an error code. The system displays an error message: "Unable to sign up with Google. Please try again or use the manual signup form." The user remains on the signup page.

8.9 Network Failure During Form Submission

• Scenario: User submits the signup form but experiences a network failure or timeout before the backend API responds.
• Handling: The system displays an error message: "Network error. Please check your connection and try again." The "Create Account" button is re-enabled. Form data is retained so the user does not need to re-enter information.

8.10 Referrer Deletes Account After Sharing Link

• Scenario: A user shares their referral link, then deletes their Pixally account before the referred user signs up.
• Handling: When the referred user clicks the link, the referral code is no longer valid (referrer account is inactive). The system redirects the user to the standard signup page without referral benefits. No referral attribution is recorded.

8.11 User Opens Referral Link in Incognito/Private Mode

• Scenario: User clicks a referral link while browsing in incognito or private mode.
• Handling: The referral code is stored in the session/cookie as usual. The signup process works normally. However, if the user closes the incognito window before completing signup and returns later in a regular browsing session, the referral attribution may be lost (depending on cookie settings).

8.12 User Signs Up, Then Immediately Cancels Subscription

• Scenario: A user signs up via a referral link, selects a subscription plan, but cancels the subscription before completing payment or during the first few days.
• Handling: The referrer's "Total Referrals" count is incremented when the user signs up, but no payout milestones are reached because the user did not become an active paying subscriber. The referrer does not earn any money for this referral.

8.13 User Uses VPN or Proxy to Access Referral Link

• Scenario: User accesses the referral link through a VPN or proxy, masking their true IP address.
• Handling: The system does not block or flag referrals based on IP address, so the signup proceeds normally. Referral attribution is based on the referral code in the URL, not IP address.

8.14 User Signs Up with Same Email from Different Referral Links (Impossible Case)

• Scenario: User attempts to create multiple accounts with the same email using different referral links.
• Handling: This scenario is impossible because the system enforces email uniqueness. The second signup attempt will fail with the error: "This email is already registered. Please login or use a different email."

8.15 User Manually Types Referral URL with Typo in Code

• Scenario: User receives a referral link but manually types it into the browser with a typo in the referral code (e.g., ALEX2024 typed as ALEX2025).
• Handling: The system validates the referral code and determines it is invalid. The user is redirected to the standard signup page without referral benefits.

9. Acceptance Criteria

9.1 Functional Requirements

• The referral signup page must load when a user clicks a valid referral link with the format https://yourapp.com/ref/\[UNIQUE\_CODE\].
• The page must display the referrer's name and discount offer in the heading: "[REFERRER_NAME] gave you 60% off first 3 months and 50% off first year".
• The signup form must display four fields: First name, Last name, Email address, and Password.
• All form fields must validate according to the specified validation rules (required, minimum length, format checks).
• The "Create Account" button must submit the form only if all validations pass.
• If validation fails, error messages must be displayed below the corresponding fields with red styling.
• The "Sign Up with Google" button must initiate Google OAuth authentication and create an account using Google profile data.
• Upon successful account creation, the user must be automatically logged in and redirected to the subscription plan selection page.
• The referral discount (50% off first year + extra 10% off first 3 months) must be applied to the user's account.
• The referrer's "Total Referrals" count must increment by 1 when the new user signs up.
• A notification email must be sent to the referrer when a new user signs up via their referral link.

9.2 Validation Expectations

• First name and last name fields must accept only alphabetic characters with a minimum length of 2 characters.
• Email field must enforce valid email format and check for uniqueness in the database.
• Password field must enforce a minimum length of 6 characters.
• If the email is already registered, the system must display the error: "This email is already registered. Please login or use a different email."
• If a referral code is invalid or expired, the user must be redirected to the standard signup page without referral benefits.

9.3 Data Consistency Rules

• Referral attribution must be stored accurately and linked to the new user's account upon signup.
• The referral code must be captured from the URL and stored in the session/cookie to maintain attribution throughout the signup process.
• Only one referral code can be attributed per signup (the most recent code in the session/cookie).
• Email addresses must be unique across all user accounts (no duplicate emails allowed).

9.4 User Actions and System Flow Validations

• Clicking the "Create Account" button must trigger form validation before submission.
• Clicking the "Sign Up with Google" button must redirect the user to Google's OAuth consent screen.
• Clicking the "Already have an account? Login" link must redirect the user to the login page.
• Clicking the "Terms & Conditions" or "Privacy Policy" links must open the respective pages in new browser tabs.
• After successful account creation, the system must automatically log the user in and redirect them to the subscription plan selection page.

10. Dependencies

10.1 Internal Module Dependencies

• Referral System Module (Referrer Dashboard): The signup flow depends on the Referral System module to retrieve referrer information (name, referral code validation) and to update referral tracking metrics (Total Referrals count, new signup notifications).
• User Authentication Module: The signup flow integrates with the User Authentication module to create user credentials, hash passwords, generate session tokens, and handle Google OAuth authentication.
• Subscription Module: After account creation, the Subscription module is responsible for displaying the subscription plan selection page and applying the referral discount to the pricing.
• Notifications Module: The Notifications module sends welcome emails to new users and referral signup notifications to referrers.

10.2 External Service Dependencies

• Google OAuth API: Required for "Sign Up with Google" functionality. Google OAuth must be configured with valid API credentials (Client ID, Client Secret) and redirect URIs.
• Email Service Provider (e.g., SendGrid, Mailgun): Required for sending transactional emails (welcome emails to new users, signup notifications to referrers).
• reCAPTCHA (Optional but Recommended): Google reCAPTCHA can be integrated to prevent bot signups and ensure form submissions are from real users.

10.3 Configuration Requirements

• Referral Link Base URL: The system must have a configured base URL (e.g., https://yourapp.com/ref/) to process referral links.
• Google OAuth Credentials: Valid Google OAuth Client ID and Client Secret must be configured in the system's environment variables or configuration files.
• Redirect URIs: Google OAuth redirect URIs must be whitelisted in the Google Cloud Console (e.g., https://yourapp.com/auth/google/callback).
• Session/Cookie Settings: Session and cookie expiration times must be configured (e.g., session expires after browsing session ends, cookie expires after 30 days).
• Referral Discount Logic: Discount percentages (50% off first year, extra 10% off first 3 months) and duration must be hardcoded or configurable in the system.

10.4 Expected System Behavior if Dependencies Fail

• Referral System Module Failure: If the Referral System module is unavailable, the system cannot validate referral codes or retrieve referrer names. The user is redirected to the standard signup page without referral benefits.
• User Authentication Module Failure: If the User Authentication module is unavailable, account creation fails. The system displays an error message: "We're sorry, something went wrong. Please try again later."
• Google OAuth API Failure: If Google OAuth is down or returns errors, the "Sign Up with Google" button displays an error message. Users can still sign up using the manual form.
• Email Service Failure: If the email service is unavailable, welcome emails and referral notifications are queued and sent once the service is restored. The signup process itself is not blocked.
• Subscription Module Failure: If the Subscription module is unavailable after account creation, the user cannot proceed to select a plan. The user is redirected to their dashboard with a message to complete subscription setup later.
• reCAPTCHA Failure (if enabled): If reCAPTCHA fails to load or verify, the system may allow the signup to proceed (depending on configuration) or display an error message prompting the user to reload the page.

11. References

Figma Links:

https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=30399-7784&t=3JSY3xkiYbyHsEme-0

✅ Referral System for Pixally User

1. Module Overview

Module Name

Referral System for Pixally User

Purpose

The Referral System module enables existing Pixally subscribers (Studio/Agency owners) to earn monetary rewards by referring new customers to Pixally through a unique referral link. The module provides users with referral tools, earnings tracking, payout management, and detailed visibility into their referral history and subscription receipts.

Business Goals

• Incentivize existing Pixally users to promote the platform and acquire new customers through word-of-mouth marketing.
• Provide transparent tracking of referral earnings with milestone-based or flat payout structures depending on the referred user's subscription plan.
• Increase user engagement and retention by rewarding advocacy and successful referrals.
• Establish a clear revenue-sharing mechanism that aligns with Pixally's subscription business model.

2. User Roles & Permissions

Roles with Access

• Pixally Subscriber (Studio/Agency Owner): Any active Pixally subscriber who has a paid subscription plan (monthly or yearly).

Permissions

• View: Users can view their referral dashboard, including earnings summary, total referrals count, next payout date, referral link, and subscription receipts table.
• Copy: Users can copy their unique referral link to share with others.
• Share: Users can directly share their referral link via social media platforms (X, Facebook, LinkedIn) or email.
• Access "How it Works" Information: Users can view a modal explaining the referral program's payout structure and terms.
• Manage Payment Details: Users can add or update their bank account information to receive referral payouts (via the Payment Details tab).
• No Edit Permissions on Referral Link: Users cannot edit or regenerate their referral link once created.
• No Delete Permissions: Users cannot delete referral history or subscription receipt records.

3. User Flow

Step-by-Step Navigation Sequence

1. Access Referral System Module:
   • The user logs into their Pixally account.
   • The user navigates to the left sidebar menu and clicks on "Referral System".
2. View Referral Dashboard:
   • The system loads the Referral System dashboard page displaying the main heading "Earn with Our Referral Program" with a subtitle "We love when you share Pixally with friends — and we want to thank you for it!".
   • The dashboard displays three summary cards at the top: "Next Payout", "Total Earnings", and "Total Referrals".
3. Review Earnings and Referral Summary:
   • The user reviews the "Next Payout" card showing the upcoming payout amount and expected date.
   • The user reviews the "Total Earnings" card showing cumulative earnings and the count of active referred users.
   • The user reviews the "Total Referrals" card showing the total number of referrals and active user count.
4. Access Referral Tools:
   • The user scrolls to the "Your Referral Tools" section.
   • The user views their unique "Basic Referral Link" displayed in a non-editable text field.
5. Copy Referral Link:
   • The user clicks the "Copy Link" button adjacent to the referral link field.
   • The system copies the link to the clipboard and displays a success message.
6. Share Referral Link via Social Media or Email:
   • The user clicks one of the "Quick Share" buttons: "Share on X", "Share on Facebook", "Share on LinkedIn", or "Email".
   • The system opens the respective platform's sharing interface with the referral link pre-populated.
7. Access "How it Works" Modal:
   • The user clicks the "How it Works" button in the top-right corner of the dashboard.
   • The system opens a modal overlay displaying detailed information about payout structures for yearly and monthly plans.
8. Review Modal Content:
   • The user reads the three-step process: "Share your referral link with friends, colleagues, or fellow creatives", "They sign up for a Pixally plan", "Once they hit each milestone, your reward is automatically sent to you".
   • The user reviews the payout structure for yearly plans ($100 after 90 days active).
   • The user reviews the milestone-based payout structure for monthly plans (90 days = $15, 6 months = +$25, 12 months = +$60).
   • The user reads the tip: "The more friends you refer, the more you can earn — there's no limit!".
9. Close Modal:
   • The user clicks "Got It" button or the close icon to dismiss the modal.
10. Review Subscription Receipts:
    • The user scrolls to the "Subscription Receipts" section with subtitle "View history of payments".
    • The user reviews the table displaying columns: User, Email, Plan, Payout Date, Payment Status, and Amount.
11. Sort Subscription Receipts:
    • The user clicks on any column header (User, Email, Plan, Payout Date, Payment Status, Amount) to sort the table in ascending or descending order.
12. Navigate to Payment Details (Optional):
    • The user clicks the "Payment Details" tab in the top navigation bar.
    • The system navigates to the Payment Details page where the user can add or update bank account information.

4. Functional Logic

4.1 Module Access and Navigation

4.1.1 Left Sidebar Menu Access

• The "Referral System" menu item is visible in the left sidebar for all active Pixally subscribers with paid plans.
• When the user clicks "Referral System" in the left sidebar, the system navigates to the Referral System dashboard page.
• The system highlights the "Referral System" menu item to indicate the current active page.

4.2 Dashboard Display - Empty State

4.2.1 Initial State (No Referrals)

• When a user accesses the Referral System for the first time and has not generated any referrals, the dashboard displays:
  • "Next Payout" card showing $0.00 with "Expected: N/A" or "No upcoming payouts".
  • "Total Earnings" card showing $0.00 with "0 active users".
  • "Total Referrals" card showing 0 with "0 active users".
  • The "Your Referral Tools" section displays the user's unique referral link.
  • The "Subscription Receipts" table displays a message: "No referrals yet. Start sharing your link to earn rewards!" or an empty table state.

4.2.2 Referral Link Generation

• The system automatically generates a unique referral link for each Pixally subscriber upon account creation or first access to the Referral System module.
• The referral link follows the format: https://yourapp.com/ref/\[UNIQUE\_CODE\] where [UNIQUE_CODE] is a unique alphanumeric identifier tied to the user's account.
• The referral link is permanent and cannot be changed or regenerated by the user.
• The referral link remains valid indefinitely and does not expire.

4.3 Dashboard Display - With Referrals

4.3.1 Next Payout Card

• The "Next Payout" card displays the total amount scheduled for the next payout cycle.
• The card shows the payout amount in bold (e.g., "$300.00").
• Below the amount, the card displays "Expected: [DATE]" indicating the estimated payout date based on the monthly payout schedule.
• If no payout is scheduled (e.g., no referrals have reached a milestone), the card displays "$0.00" with "Expected: N/A".

4.3.2 Total Earnings Card

• The "Total Earnings" card displays the cumulative earnings the user has accrued from all successful referrals.
• The card shows the total earnings amount in bold (e.g., "$1,600.00").
• Below the amount, the card displays "[X] active users" indicating the count of referred users who are currently active paying subscribers.

4.3.3 Total Referrals Card

• The "Total Referrals" card displays the total count of users who have signed up using the user's referral link.
• The card shows the total referral count as a bold number (e.g., "23").
• Below the count, the card displays "[X] active users" indicating how many of those referrals are currently active paying subscribers.

4.4 Your Referral Tools Section

4.4.1 Basic Referral Link Display

• The "Your Referral Tools" section displays a heading "Basic Referral Link".
• Below the heading, a non-editable text field displays the user's unique referral link (e.g., https://yourapp.com/ref/ALEX2024).
• The text field is styled to prevent editing but allows text selection for manual copying.

4.4.2 Copy Link Button Functionality

• A "Copy Link" button is positioned to the right of the referral link text field.
• When the user clicks the "Copy Link" button, the system copies the referral link to the user's clipboard.
• Upon successful copy, the system displays a success message: "Referral link copied to clipboard!".
• The button remains functional for repeated copying actions.

4.4.3 Quick Share Buttons

• Below the referral link field, the system displays a "Quick Share" section with four social sharing buttons:
  • Share on X: Opens a new browser tab/window with X (formerly Twitter) compose interface pre-filled with the referral link and a default message.
  • Share on Facebook: Opens Facebook's sharing dialog with the referral link.
  • Share on LinkedIn: Opens LinkedIn's sharing interface with the referral link.
  • Email: Opens the user's default email client with a new message containing the referral link in the body.
• Each button displays the platform logo and corresponding text label.
• Clicking any button triggers the respective platform's native sharing mechanism.

4.5 How it Works Modal

4.5.1 Modal Trigger

• A "How it Works" button is positioned in the top-right area of the dashboard header.
• When the user clicks the "How it Works" button, the system displays a modal overlay on top of the current page.

4.5.2 Modal Content Structure

• The modal displays a heading "How It Works" at the top.
• The modal contains three main sections:
  1. General Process (3 Steps):
     • Step 1: "Share your referral link with friends, colleagues, or fellow creatives."
     • Step 2: "They sign up for a Pixally plan."
     • Step 3: "Once they hit each milestone, your reward is automatically sent to you."
  2. If Your Friend Chooses a Yearly Plan:
     • Displays "$100 payout" in bold.
     • Explanation text: "Once your friend has been active for 90 days (past our 90-day guarantee window), you'll receive your $100 reward — simple as that."
  3. If Your Friend Chooses a Monthly Plan:
     • Displays the heading "You'll earn rewards in 3 milestones as they continue using Pixally:".
     • Lists three milestones:
       • 90 Days Active: You earn $15
       • 6 Months Active: You earn $25
       • 12 Months Active: You earn $60
     • Displays total summary: "That's a total of $100 if they stay active for the full year!"
     • Displays a highlighted tip box: "Tip: The more friends you refer, the more you can earn — there's no limit!"

4.5.3 Modal Actions

• The modal includes a "Got It" button at the bottom.
• Clicking the "Got It" button closes the modal and returns the user to the dashboard view.
• The modal also includes a close icon (X) in the top-right corner for dismissal.
• Clicking outside the modal area or pressing the Escape key also closes the modal.

4.6 Subscription Receipts Table

4.6.1 Table Structure and Display

• The "Subscription Receipts" section is displayed below the referral tools section.
• The section heading reads "Subscription Receipts" with a subtitle "View history of payments".
• The table contains the following columns:
  • User: Displays the referred user's name and "Since [DATE]" indicating when they became a subscriber.
  • Email: Displays the referred user's email address (partially masked for privacy, e.g., "s***@gmail.com").
  • Plan: Displays the subscription plan type (e.g., "Yearly", "Monthly").
  • Payout Date: Displays the date when the payout was processed or is scheduled.
  • Payment Status: Displays the status as "Paid" (green badge) or "Unpaid" (gray/orange badge).
  • Amount: Displays the payout amount earned from this referral (e.g., "$100.00") with additional context text (e.g., "Active for 90 days", "3 of 3 (Active for 12 months)").

4.6.2 Table Population Logic

• The table displays all referred users who have signed up using the user's referral link and have met at least one payout milestone or have a scheduled payout.
• Each row represents a single payout event (for yearly plans) or a milestone payout (for monthly plans).
• For monthly plan referrals, multiple rows may appear for the same user representing each milestone reached (e.g., three separate rows for 90 days, 6 months, and 12 months milestones).
• The table is sorted by default in descending order of "Payout Date" (most recent at the top).

4.6.3 Sorting Functionality

• Each column header is clickable to enable sorting.
• Clicking a column header once sorts the table in ascending order based on that column.
• Clicking the same column header again toggles the sort to descending order.
• A visual indicator (up/down arrow icon) appears next to the active sorted column header to indicate sort direction.

4.6.4 Payment Status Logic

• Paid Status: Displayed when the payout has been successfully processed and transferred to the user's bank account. The badge is styled in green.
• Unpaid Status: Displayed when the payout is scheduled but has not yet been processed (e.g., waiting for the monthly payout cycle or pending milestone completion). The badge is styled in gray or orange.

4.6.5 Amount Display Logic

• For yearly plan referrals: The amount column displays "$100.00" with context text "Active for 90 days".
• For monthly plan referrals: The amount column displays the milestone-specific amount ($15, $25, or $60) with context text indicating the milestone reached:
  • First milestone: "$15.00" with "1 of 3 (Active for 90 days)".
  • Second milestone: "$25.00" with "2 of 3 (Active for 6 months)".
  • Third milestone: "$60.00" with "3 of 3 (Active for 12 months)".

4.7 Payout Calculation and Processing

4.7.1 Active User Definition

• A referred user is considered "active" if they maintain a paid subscription without cancellation.
• The active duration is calculated from the date the user completes their first successful payment (excluding any free trial or grace periods).
• A user remains active as long as their subscription payments are processed successfully without interruption.
• If a payment fails but is retried and succeeds within the billing grace period, the user continues to be considered active.

4.7.2 Yearly Plan Payout Logic

• When a referred user signs up for a yearly plan and completes 90 consecutive days as an active paying subscriber, the referrer becomes eligible for a $100 payout.
• The system calculates the 90-day period starting from the date of the referred user's first successful payment.
• On day 91, the payout is added to the referrer's "Next Payout" total and scheduled for the next monthly payout cycle.
• If the referred user cancels their subscription on or before day 89, the $100 payout is forfeited and the referrer does not earn any amount for that referral.

4.7.3 Monthly Plan Payout Logic - Milestone 1 (90 Days)

• When a referred user signs up for a monthly plan and completes 90 consecutive days as an active paying subscriber, the referrer becomes eligible for a $15 payout (Milestone 1).
• The system calculates the 90-day period starting from the date of the referred user's first successful payment.
• On day 91, the $15 payout is added to the referrer's "Next Payout" total and scheduled for the next monthly payout cycle.
• A new row is added to the "Subscription Receipts" table showing the $15 amount with "1 of 3 (Active for 90 days)" status.

4.7.4 Monthly Plan Payout Logic - Milestone 2 (6 Months)

• When a referred user on a monthly plan reaches 6 months (180 days) of active subscription, the referrer becomes eligible for an additional $25 payout (Milestone 2).
• The system calculates the 6-month period as 180 consecutive days from the date of the referred user's first successful payment.
• On day 181, the $25 payout is added to the referrer's "Next Payout" total and scheduled for the next monthly payout cycle.
• A new row is added to the "Subscription Receipts" table showing the $25 amount with "2 of 3 (Active for 6 months)" status.
• The referrer retains the previously earned $15 from Milestone 1 regardless of future activity.

4.7.5 Monthly Plan Payout Logic - Milestone 3 (12 Months)

• When a referred user on a monthly plan reaches 12 months (365 days) of active subscription, the referrer becomes eligible for an additional $60 payout (Milestone 3).
• The system calculates the 12-month period as 365 consecutive days from the date of the referred user's first successful payment.
• On day 366, the $60 payout is added to the referrer's "Next Payout" total and scheduled for the next monthly payout cycle.
• A new row is added to the "Subscription Receipts" table showing the $60 amount with "3 of 3 (Active for 12 months)" status.
• The total cumulative payout for this monthly referral reaches $100 ($15 + $25 + $60).
• The referrer retains all previously earned amounts ($15 + $25) regardless of future activity.

4.7.6 Cancellation Impact on Payouts

• If a referred user cancels their subscription before reaching the next milestone, the referrer forfeits any future payouts for that referral.
• Previously earned and paid milestone amounts are retained by the referrer and are not clawed back.
• For example, if a monthly plan user cancels after 200 days (after Milestone 1 and Milestone 2 have been paid), the referrer keeps the $15 and $25 already received but will not earn the $60 for Milestone 3.
• If a referred user cancels and then resubscribes, the milestone tracking does not restart; the system does not count the reactivated subscription toward new milestones.

4.7.7 Payout Schedule and Processing

• Payouts are processed on a monthly schedule on a fixed date each month (e.g., the 1st or 15th of every month).
• All eligible payouts that have reached their milestone criteria by the payout cutoff date are included in the next payout cycle.
• The "Next Payout" card displays the sum of all eligible payouts scheduled for the upcoming payout date.
• The system transfers the payout amount to the referrer's designated bank account using the payment details provided in the "Payment Details" section.
• After a payout is successfully processed, the corresponding rows in the "Subscription Receipts" table are updated to "Paid" status.
• Standard Stripe processing fees are deducted from the payout amount before transfer (referrer receives the net amount after fees).

4.7.8 Payment Details Requirement

• Before the first payout can be processed, the user must provide valid bank account information in the "Payment Details" section.
• If bank details are not provided by the scheduled payout date, the payout is held in a pending state and displayed as "Unpaid" in the Subscription Receipts table.
• The system sends a notification to the user prompting them to add payment details.
• Once payment details are added, the held payout is processed in the next available payout cycle.

4.8 Duplicate Prevention and Attribution

4.8.1 No Duplicate Blocking

• The system does not block referrals based on IP address, device fingerprint, payment card, or email domain.
• Multiple users from the same organization, household, or network can sign up using the same referral link and each will be counted as a separate valid referral.

4.8.2 Attribution Logic

• Referral attribution is determined by the referral link used during the signup process.
• When a new user clicks a referral link, the system captures the unique referral code from the URL and stores it in the user's session.
• If the user completes the signup and subscription process, the referral is attributed to the owner of that referral code.
• If a user clicks multiple different referral links before signing up, the referral is attributed to the link from which the user actually completed the signup and subscription (the final link used in the signup session).

4.9 Earnings Summary Updates

4.9.1 Real-Time Updates

• The "Total Earnings" card is updated in real-time when a payout milestone is reached and added to the user's account balance.
• The "Total Referrals" card is updated immediately when a new user signs up using the referral link.
• The "Next Payout" card is updated when new milestones are reached and payouts are added to the upcoming payout cycle.

4.9.2 Active User Count Updates

• The active user count displayed in the "Total Earnings" and "Total Referrals" cards is recalculated daily to reflect the current status of referred users.
• If a referred user cancels their subscription, the active user count decreases by one.
• If a previously canceled user resubscribes, the active user count does not automatically increase (resubscriptions do not restart milestone tracking for referral purposes).

4.10 Impact on Other Modules

4.10.1 Integration with Subscription Module

• The Referral System module integrates with the Subscription module to track referred users' subscription status, plan type, and payment activity.
• The system monitors subscription lifecycle events (signup, payment success, payment failure, cancellation, plan changes) to determine milestone eligibility.

4.10.2 Integration with Payment Module

• The Referral System module integrates with the Payment module to process monthly payouts to referrers' bank accounts.
• Payment details provided in the "Payment Details" tab are stored securely and used for payout transfers via Stripe.

4.10.3 Integration with Notifications Module

• The system sends email notifications to referrers when:
  • A new user signs up using their referral link.
  • A referred user reaches a payout milestone.
  • A payout is successfully processed.
  • Payment details are missing and need to be added before payout processing.

5. Field Details & Validations

5.1 Referral Link Field

• Field Name: Basic Referral Link
• Field Type: Text (Read-only)
• Validation Rules:
  • The field displays a permanent, system-generated unique URL.
  • The field is non-editable by the user.
  • The link must follow the format: https://yourapp.com/ref/\[UNIQUE\_CODE\] where [UNIQUE_CODE] is alphanumeric.
  • The field allows text selection for manual copying.

5.2 Next Payout Amount

• Field Name: Next Payout
• Field Type: Currency Display (Read-only)
• Validation Rules:
  • Displays monetary value formatted as "$X.XX" (e.g., "$300.00").
  • Value must be non-negative (minimum $0.00).
  • Updated automatically by the system based on milestone calculations.

5.3 Total Earnings Amount

• Field Name: Total Earnings
• Field Type: Currency Display (Read-only)
• Validation Rules:
  • Displays cumulative monetary value formatted as "$X.XX" (e.g., "$1,600.00").
  • Value must be non-negative (minimum $0.00).
  • Updated automatically by the system when payouts are processed.

5.4 Total Referrals Count

• Field Name: Total Referrals
• Field Type: Integer Display (Read-only)
• Validation Rules:
  • Displays whole number count (e.g., "23").
  • Value must be non-negative (minimum 0).
  • Updated automatically when new referrals sign up.

5.5 Active Users Count

• Field Name: Active Users (displayed in Total Earnings and Total Referrals cards)
• Field Type: Integer Display (Read-only)
• Validation Rules:
  • Displays whole number count (e.g., "18 active users").
  • Value must be non-negative (minimum 0).
  • Value cannot exceed Total Referrals count.
  • Updated daily based on subscription status of referred users.

5.6 Payout Date Field

• Field Name: Expected Payout Date (Next Payout card) / Payout Date (Subscription Receipts table)
• Field Type: Date Display (Read-only)
• Validation Rules:
  • Displays date in format "DD MMM YYYY" (e.g., "11 Sep 2025").
  • Must be a valid future date for scheduled payouts.
  • Can display "N/A" if no payout is scheduled.

5.7 Payment Status Field

• Field Name: Payment Status
• Field Type: Badge/Label Display (Read-only)
• Validation Rules:
  • Must display one of two values: "Paid" or "Unpaid".
  • "Paid" status is styled with green color.
  • "Unpaid" status is styled with gray or orange color.

5.8 User Email Field (Subscription Receipts)

• Field Name: Email
• Field Type: Text Display (Read-only, Partially Masked)
• Validation Rules:
  • Displays email in partially masked format for privacy (e.g., "s***@gmail.com", "j***@gmail.com", "m***@yahoo.com").
  • Must be a valid email format when stored in the system.

5.9 Plan Type Field (Subscription Receipts)

• Field Name: Plan
• Field Type: Text Display (Read-only)
• Validation Rules:
  • Must display one of two values: "Yearly" or "Monthly".
  • Value is determined by the referred user's selected subscription plan.

5.10 Amount Field (Subscription Receipts)

• Field Name: Amount
• Field Type: Currency Display (Read-only)
• Validation Rules:
  • Displays monetary value formatted as "$X.XX" (e.g., "$100.00", "$15.00", "$25.00", "$60.00").
  • Must be one of the valid payout amounts: $15, $25, $60 (for monthly milestones), or $100 (for yearly plan).
  • Includes context text below the amount (e.g., "Active for 90 days", "2 of 3 (Active for 6 months)").

6. Success Message Handling

6.1 Referral Link Copied

• Operation: User clicks "Copy Link" button
• Success Message: "Referral link copied to clipboard!"
• Trigger Condition: The referral link is successfully copied to the user's clipboard.
• Post-Success Action: The message is displayed as a toast notification for 3-5 seconds and then auto-dismisses. No page refresh or navigation occurs.

6.2 Modal Acknowledged

• Operation: User clicks "Got It" button in the "How it Works" modal
• Success Message: No explicit message displayed (modal simply closes).
• Trigger Condition: User clicks the "Got It" button or close icon.
• Post-Success Action: The modal closes and the user returns to the main dashboard view.

6.3 Payout Processed Successfully

• Operation: System processes a scheduled payout to the user's bank account
• Success Message: Email notification sent: "Your referral payout of $[AMOUNT] has been successfully processed and will arrive in your bank account within 2-3 business days."
• Trigger Condition: Payout transfer is completed successfully by Stripe.
• Post-Success Action: The corresponding row(s) in the Subscription Receipts table are updated from "Unpaid" to "Paid" status. The "Next Payout" card is recalculated to reflect remaining scheduled payouts.

6.4 Payment Details Added

• Operation: User adds bank account information in the Payment Details section
• Success Message: "Payment details saved successfully. You're all set to receive your referral earnings!"
• Trigger Condition: User submits valid bank account information and it is successfully saved.
• Post-Success Action: The system enables payout processing for any pending "Unpaid" amounts. User is redirected back to the Referral System tab or remains on the Payment Details page.

6.5 New Referral Signup Notification

• Operation: A new user signs up using the user's referral link
• Success Message: Email notification sent: "Great news! [USER_NAME] signed up for Pixally using your referral link. You'll start earning once they become an active subscriber."
• Trigger Condition: A new user completes signup and creates an account using the referral link.
• Post-Success Action: The "Total Referrals" count is incremented by 1. A new entry is prepared for tracking in the system (visible in Subscription Receipts once milestones are reached).

6.6 Milestone Reached Notification

• Operation: A referred user reaches a payout milestone (90 days, 6 months, or 12 months active)
• Success Message: Email notification sent: "Congratulations! [USER_NAME] has reached the [MILESTONE] milestone. You've earned $[AMOUNT]! Your payout is scheduled for [DATE]."
• Trigger Condition: A referred user completes the required active duration for a milestone.
• Post-Success Action: The payout amount is added to the "Next Payout" total. A new row is added to the Subscription Receipts table with "Unpaid" status. The "Total Earnings" card is updated with the pending amount.

7. Error Message Handling

7.1 Copy to Clipboard Failure

• Error Scenario: User clicks "Copy Link" button but the clipboard API fails (e.g., browser permissions issue).
• Error Message: "Unable to copy link. Please manually select and copy the referral link."
• Trigger Condition: Browser clipboard API returns an error or is unavailable.
• Required Action: User manually selects the text from the referral link field and copies it using keyboard shortcuts (Ctrl+C / Cmd+C).
• System Response: Display error message as a toast notification for 5 seconds. The referral link field remains accessible for manual selection.

7.2 Social Share Popup Blocked

• Error Scenario: User clicks a "Quick Share" button but browser blocks the popup window.
• Error Message: "Pop-up blocked. Please allow pop-ups for this site or manually copy and share your referral link."
• Trigger Condition: Browser's popup blocker prevents the social sharing window from opening.
• Required Action: User enables popups in browser settings or manually copies the referral link to share via the platform.
• System Response: Display error message as a toast notification. Provide fallback instructions to manually copy the link.

7.3 Payment Details Missing at Payout Time

• Error Scenario: A payout is scheduled but the user has not provided bank account information.
• Error Message: Email notification sent: "Action Required: Add your payment details to receive your referral earnings of $[AMOUNT]. Visit your Referral System settings to complete setup."
• Trigger Condition: Payout cycle is triggered but no valid bank account is on file.
• Required Action: User navigates to Payment Details tab and adds bank account information.
• System Response: Payout remains in "Unpaid" status until payment details are provided. Once added, payout is processed in the next cycle.

7.4 Payout Processing Failure (Stripe Error)

• Error Scenario: System attempts to process payout but Stripe returns an error (e.g., invalid bank account, insufficient funds, account verification failed).
• Error Message: Email notification sent: "We encountered an issue processing your referral payout of $[AMOUNT]. Please verify your payment details and contact support if the issue persists."
• Trigger Condition: Stripe API returns an error during payout transfer.
• Required Action: User reviews and updates payment details in the Payment Details section. User may need to contact support for assistance.
• System Response: Payout remains in "Unpaid" status. User is prompted to update payment information. System retries payout in the next cycle after details are corrected.

7.5 Referred User Payment Failure Before Milestone

• Error Scenario: A referred user's payment fails (e.g., card declined) before reaching a milestone.
• Error Message: No direct error message to referrer (internal system tracking only).
• Trigger Condition: Referred user's subscription payment fails and they do not become an active subscriber.
• Required Action: No action required from referrer. System continues tracking if the referred user resolves payment and reactivates.
• System Response: Milestone countdown pauses or resets depending on whether the referred user successfully resumes payments within the grace period. If the user remains inactive for an extended period, they may not contribute to milestone calculations.

7.6 Dashboard Loading Failure

• Error Scenario: User navigates to the Referral System dashboard but the page fails to load due to network or server issues.
• Error Message: "Unable to load referral dashboard. Please check your connection and try again."
• Trigger Condition: API request to fetch dashboard data fails or times out.
• Required Action: User refreshes the page or checks internet connection.
• System Response: Display error message on the page with a "Retry" button. Clicking "Retry" re-attempts to load the dashboard data.

7.7 Subscription Receipts Table Load Failure

• Error Scenario: Subscription Receipts table fails to load or display data.
• Error Message: "Unable to load subscription receipts. Please try again later."
• Trigger Condition: API request to fetch subscription receipt data fails.
• Required Action: User refreshes the page or tries again after a few minutes.
• System Response: Display error message in place of the table with a "Retry" button.

7.8 Invalid Referral Link (Edge Case)

• Error Scenario: User's referral link is malformed or missing from the database (rare system error).
• Error Message: "Your referral link could not be generated. Please contact support for assistance."
• Trigger Condition: Database query returns no referral link for the user or the link format is invalid.
• Required Action: User contacts Pixally support to resolve the issue.
• System Response: Display error message in place of the referral link field. Disable "Copy Link" and "Quick Share" buttons until resolved.

8. Edge Cases

8.1 Referred User Cancels on Day 89

• Scenario: A referred user cancels their subscription on day 89 (one day before the 90-day milestone).
• Handling: The referrer does not earn the payout for that referral. The cancellation occurs before the milestone is reached, so no amount is added to "Next Payout" or "Total Earnings". The referral count remains in "Total Referrals" but the active user count decreases.

8.2 Referred User Downgrades from Yearly to Monthly Before 90 Days

• Scenario: A referred user signs up for a yearly plan but downgrades to a monthly plan before completing 90 days.
• Handling: The system recalculates the payout structure based on the new plan type (monthly). The milestone tracking resets and follows the monthly milestone schedule (90 days = $15, 6 months = $25, 12 months = $60). The user does not receive the $100 yearly payout.

8.3 Referred User Upgrades from Monthly to Yearly After First Milestone

• Scenario: A referred user signs up for a monthly plan, reaches the 90-day milestone ($15 earned), and then upgrades to a yearly plan.
• Handling: The referrer keeps the $15 already earned from the first milestone. Future milestone tracking is discontinued as the user is now on a yearly plan. No additional payouts are earned for this referral (the yearly $100 payout only applies if the user starts with a yearly plan, not if they upgrade mid-cycle).

8.4 Payment Details Added After Multiple Payouts Are Due

• Scenario: A user has multiple payouts in "Unpaid" status because they did not add payment details for several months.
• Handling: Once payment details are added, all accumulated "Unpaid" payouts are processed together in the next payout cycle. The user receives a single transfer containing the sum of all pending amounts (minus Stripe fees).

8.5 Referred User Resubscribes After Cancellation

• Scenario: A referred user cancels their subscription after earning the referrer $15 (Milestone 1) and then resubscribes a few months later.
• Handling: The referrer retains the $15 already earned. However, milestone tracking does not restart or resume. The resubscription is not counted as a new referral, and no additional payouts are earned from this user.

8.6 Same User Signs Up Multiple Times with Different Emails

• Scenario: The same individual creates multiple Pixally accounts using different email addresses and the same referral link.
• Handling: The system does not block based on IP, device, or payment card, so each signup is counted as a separate referral. Each account is tracked independently for milestone payouts. If this behavior is flagged as fraudulent by internal monitoring, support may investigate and invalidate fraudulent referrals.

8.7 Referrer Cancels Their Own Subscription

• Scenario: A Pixally user who has active referrals and pending payouts cancels their own Pixally subscription.
• Handling: The user retains access to the Referral System module as long as they have pending payouts or a grace period. Earned payouts that are already in "Paid" status are not affected. Unpaid payouts are still processed according to the payout schedule. If the user fully terminates their account, pending payouts may be held until the account is reactivated or handled according to the terms of service.

8.8 No Payment Details Provided for Extended Period

• Scenario: A user accumulates significant referral earnings but does not add payment details for 6+ months.
• Handling: All payouts remain in "Unpaid" status indefinitely. The system sends periodic email reminders prompting the user to add payment details. Once details are added, all accumulated payouts are processed in the next cycle. No payouts are lost or expire due to lack of payment details.

8.9 Stripe Account Verification Fails

• Scenario: User adds bank account information, but Stripe cannot verify the account (e.g., incorrect routing number, closed account).
• Handling: The system displays an error message prompting the user to correct the payment details. Payouts remain in "Unpaid" status. Support may reach out to assist with resolving verification issues.

8.10 Multiple Referrers Claim the Same Signup

• Scenario: A new user clicks multiple referral links from different referrers before signing up.
• Handling: Referral attribution is assigned to the referral link from which the user completed the final signup and subscription process. Only one referrer receives credit for the signup. The system tracks the referral code used during the account creation session to determine attribution.

8.11 Referred User Payment Fails Midway Through Milestone

• Scenario: A referred user's payment fails on day 120 (after earning the referrer $15 for the 90-day milestone) and they do not resume payments.
• Handling: The referrer retains the $15 already earned and paid from Milestone 1. The countdown for Milestone 2 (6 months) pauses. If the user does not reactivate their subscription, no further payouts are earned. The active user count is decremented.

8.12 Dashboard Accessed from Multiple Devices Simultaneously

• Scenario: User accesses the Referral System dashboard from two devices at the same time (e.g., desktop and mobile).
• Handling: Both devices display the same dashboard data based on the latest state from the server. Updates (such as new referral signups or milestone completions) are reflected on both devices upon page refresh or real-time sync (if implemented). No data conflicts occur.

8.13 User Shares Referral Link on Public Forum

• Scenario: User posts their referral link on a public forum or social media platform, resulting in a large number of signups.
• Handling: All signups using the referral link are counted as valid referrals, regardless of volume. There is no limit to the number of referrals a user can generate. Each valid referral that meets milestone criteria earns the corresponding payout.

8.14 Referred User Subscribes During a Promotional Period

• Scenario: A referred user signs up using a referral link while Pixally is running an additional promotional discount (e.g., 60% off instead of 50% off).
• Handling: The referral discount (50% off first year + extra 10% off first 3 months) is applied on top of any existing promotional offer if allowed by system business rules. The referrer's payout structure remains unchanged ($100 for yearly, milestone-based for monthly). Payouts are not affected by the amount the referred user actually pays.

8.15 Referral Link Shared via Email Attachment or PDF

• Scenario: User copies their referral link into a document, PDF, or email attachment and shares it.
• Handling: As long as the recipient clicks the link from the document or attachment and completes signup, the referral is attributed correctly. The link functions the same way regardless of how it is shared.

9. Acceptance Criteria

9.1 Functional Requirements

• The Referral System module must be accessible from the left sidebar menu for all active Pixally subscribers.
• The dashboard must display the three summary cards: "Next Payout", "Total Earnings", and "Total Referrals" with accurate real-time data.
• The system must generate a unique, permanent referral link for each user that follows the format https://yourapp.com/ref/\[UNIQUE\_CODE\].
• The "Copy Link" button must successfully copy the referral link to the user's clipboard and display a success message.
• The "Quick Share" buttons must open the respective social platform or email client with the referral link pre-populated.
• The "How it Works" button must open a modal displaying detailed information about the referral program's payout structure.
• The modal must include the 3-step process, yearly plan payout details, monthly plan milestone details, and a "Got It" button to close.
• The "Subscription Receipts" table must display all referral payouts with columns: User, Email, Plan, Payout Date, Payment Status, and Amount.
• Each column in the Subscription Receipts table must be sortable in ascending and descending order.
• The system must correctly calculate and display payouts: $100 for yearly plans after 90 days, and milestone-based payouts ($15, $25, $60) for monthly plans.
• The system must process monthly payouts to users' bank accounts via Stripe after payment details are provided.
• The system must update the "Payment Status" from "Unpaid" to "Paid" after successful payout processing.

9.2 Validation Expectations

• Referral links must be unique, non-editable, and permanent for each user.
• All monetary amounts must be displayed in the format "$X.XX" with two decimal places.
• The "Next Payout" card must only display scheduled payouts that have reached milestone eligibility.
• Active user counts must be updated daily and must not exceed the total referral count.
• Email addresses in the Subscription Receipts table must be partially masked for privacy.
• Payment Status badges must be color-coded correctly: green for "Paid", gray/orange for "Unpaid".

9.3 Data Consistency Rules

• The sum of all individual payouts in the Subscription Receipts table must equal the "Total Earnings" displayed in the summary card.
• The "Next Payout" amount must accurately reflect the sum of all eligible unpaid milestones scheduled for the next cycle.
• Milestone tracking must pause or reset if a referred user's subscription is canceled before reaching the next milestone.
• Previously earned and paid milestone amounts must not be clawed back if a referred user cancels their subscription.
• Referral attribution must be consistent and assigned to the referral link used during the signup session.

9.4 User Actions and System Flow Validations

• Users must be able to navigate between "Referral System" and "Payment Details" tabs without data loss.
• The "How it Works" modal must be dismissible via the "Got It" button, close icon, clicking outside the modal, or pressing Escape.
• Social sharing buttons must trigger native platform sharing mechanisms or default email client.
• Error messages must be displayed as toast notifications and must auto-dismiss after 3-5 seconds.
• The system must send email notifications for new referrals, milestone achievements, and payout processing.

10. Dependencies

10.1 Internal Module Dependencies

• Subscription Module: The Referral System relies on the Subscription module to track referred users' subscription status, plan type (yearly or monthly), payment success/failure events, and cancellation events to determine milestone eligibility.
• Payment Module: The Referral System integrates with the Payment module to process monthly payouts to referrers' bank accounts and to store/retrieve payment details (bank account information).
• User Authentication Module: The Referral System requires the User Authentication module to verify logged-in users and ensure only active Pixally subscribers can access the referral dashboard.
• Notifications Module: The Referral System depends on the Notifications module to send email alerts for new referrals, milestone achievements, payout processing, and payment detail reminders.

10.2 External Service Dependencies

• Stripe API: The system uses Stripe for payout processing. Stripe must be configured to handle transfers to referrers' bank accounts. Stripe's processing fees are deducted from payouts.
• Email Service Provider (e.g., SendGrid, Mailgun): Required for sending transactional email notifications to referrers regarding referral activity and payout status.
• Social Media APIs (Optional): For seamless social sharing, the system may integrate with X (Twitter), Facebook, and LinkedIn sharing APIs to pre-populate share content.

10.3 Configuration Requirements

• Referral Link Base URL: The system must have a configured base URL (e.g., https://yourapp.com/ref/) to generate referral links.
• Payout Schedule Configuration: The system must have a defined monthly payout schedule date (e.g., payouts processed on the 1st of every month).
• Milestone Criteria: The system must have hardcoded or configurable milestone criteria: 90 days, 180 days (6 months), and 365 days (12 months).
• Payout Amounts: The system must have configured payout amounts: $100 for yearly plans, $15/$25/$60 for monthly milestones.
• Stripe Account Configuration: A valid Stripe account must be set up with payout capabilities enabled.

10.4 Expected System Behavior if Dependencies Fail

• Subscription Module Failure: If the Subscription module is unavailable, milestone tracking cannot occur. Payouts are delayed until subscription data is accessible. Users see outdated data on the dashboard.
• Payment Module Failure: If the Payment module is unavailable, payouts cannot be processed. Payouts remain in "Unpaid" status and are retried in the next cycle. Users receive error notifications.
• Stripe API Failure: If Stripe is down or returns errors, payouts fail and remain in "Unpaid" status. Users are notified of the issue and prompted to verify payment details. The system retries in the next payout cycle.
• Email Service Failure: If the email service is unavailable, notification emails are queued and sent once the service is restored. Users do not receive real-time notifications but can view updates on the dashboard.
• Social Media API Failure: If social sharing APIs are unavailable, the "Quick Share" buttons may open generic share interfaces or display an error. Users can still manually copy the referral link to share.

11. References

Figma Links: https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=29836-190482&t=3JSY3xkiYbyHsEme-0