Chunks — 24. Invoices

Invoices

#

#

#

#

#

# **Invoices**

**Functional Requirement Document**

**BA & Ideation: Deval Chauhan**

**Reviewed By: Keval Gajjar**

**Updated Date:10 December 2025  
Status:**

**Version: 1.0**

## **FRD #1: Invoice Template Listing**

**Purpose:** Centralized template management via Templates → Invoices

**Key Features**

**Business Rules**

Table view with search, filter (Draft/Published), sort, pagination

Only Published templates available for invoice creation

Actions: Edit, Duplicate, Delete, Publish/Unpublish, Preview

Published with Times Used > 0 cannot be deleted

Two tabs: Invoice Templates & Payment Schedules

Unpublish = soft-disable (not revert to Draft)

## **FRD #2: Invoice Template Creation & Builder**

**Purpose:** Visual builder for creating invoice templates with drag-and-drop

**Key Features**

**Business Rules**

5 mandatory blocks: Logo, Title, Contact Info, Items, Payment Terms

Unlimited line items per invoice

Custom sections: Text, Image (deletable)

Payment terms must equal invoice total

4 date types: Smart, Invoice, Custom, Event

Discount applied before tax

3 payment types: Custom Amount, Percentage, Equal Payment

Equal Payment auto-recalculates when new one added

Styling: Colors, Fonts, "Use Brand Colors" toggle

Auto-suggest from Packages & Services

## **FRD #3: Edit Invoice Template with Conditions**

**Purpose:** Define editing rules based on template status and permissions

**Key Features**

**Business Rules**

Draft: Full edit by owner

Published: Admin/Manager only can edit

Future-Effect Rule: Edits don't affect existing invoices

Template snapshot preserved with each sent invoice

Version history (internal audit only)

No version restoration in Phase 1

Concurrent editing: Last save wins

Team Members cannot edit Published templates

## **FRD #4: Payment Schedule Templates**

**Purpose:** Reusable payment schedule presets for invoices

**Key Features**

**Business Rules**

5 default presets: 50/50 Split, Full Upfront, Deposit+Final, VIP Terms, One-Time

Percentage presets must total exactly 100%

Apply Preset: Loads as independent copy

Save as Preset: Creates Published preset immediately

Smart Date conditions: before/after event, after invoice sent

Applied presets are copies (no link to original)

## **FRD #5: Use Invoice in Project & Auto-Generation**

**Purpose:** Create invoices within projects manually or auto-generate from proposals

**Key Features**

**Business Rules**

Entry: Project → Files/Documents → Create File → Invoice

Only Published templates shown for selection

Auto-generation triggered when client signs proposal

Uses Pixally Default Template (no user choice Phase 1)

Auto-maps packages, services, pricing, discounts from proposal

Invoice Number: BRAND-INV-###-YYYYMMDD (global sequence)

Share Invoice: Email, Copy Link, Preview

Unlimited invoices per project; Project Total = SUM of all

## **FRD #6: Edit Sent Invoice & Impact**

**Purpose:** Rules for modifying sent invoices based on payment status

**Key Features**

**Business Rules**

Status-based edit matrix (Draft → Voided)

**Paid payments are immutable** - cannot edit/delete

Balance validation: Payment total must equal invoice total

Cannot reduce total below paid amount (must refund first)

Deactivate: Reversible (can reactivate)

Void: Permanent (cannot reactivate)

Project warning banner after amount changes

Invoice number never changes after edits

## **FRD #7: Invoice Integration & Impact**

**Purpose:** Integration with Project, Finance, Stripe, QuickBooks, Notifications

**Key Features**

**Business Rules**

Finance → Billing → Invoices/Transactions tabs

6 status tabs: Unpaid, Processing, Paid, Overdue, Failed, Refunds

Stripe: Credit Card, Debit, ACH; webhooks update status

Partial refund: Invoice stays "Paid" with refund note

QuickBooks: Auto-sync on payment; manual retry if failed

Reminder limit: 1 per payment per day

Audit logs: All events logged (backend only Phase 1)

Processing = In Progress (same status)

## **Quick Reference: Key Business Rules**

**Rule**

**Description**

**Payment Balance**

Payment terms must exactly equal invoice total (blocking validation)

**Paid Immutability**

No user can edit or delete paid payment entries

**Template Snapshot**

Sent invoices preserve template snapshot; future edits don't affect them

**Calculation Order**

Total = (Subtotal - Discount) + Tax

**Project Total**

SUM of all invoice amounts (excludes Deactivated/Voided)

**Equal Payment**

Auto-recalculates all equal entries when new one added

## **Permissions Quick View**

**Action**

**Admin**

**Manager**

**Team Member**

Create/Edit Draft Template

✅

✅

✅ (own)

Edit Published Template

✅

✅

❌

Deactivate/Void Invoice

✅

✅

❌

Edit Paid Payment

❌

❌

❌

Issue Refund

✅

✅

❌

☑️ 1. Invoice Template List

# **FRD #1: Invoice Template Listing**

**Version:** 1.0  
**Date:** December 18, 2025

## **1\. Module Overview**

**Purpose:  
**The Invoice Template Listing module provides a centralized management interface for all invoice templates within the Pixally CRM system. This module enables users to view, search, filter, sort, and manage invoice templates from a single location, ensuring standardized invoicing across the organization.

**Business Goals:**

*   Standardize invoice creation across all brands and projects.
*   Enable reuse of professionally designed templates to reduce manual effort.
*   Ensure brand consistency across all client-facing invoices.
*   Provide clear visibility into template usage and status.

**Scope:**

*   Template listing page display and navigation.
*   Search, filter, sort, and pagination functionality.
*   Template actions including Edit, Duplicate, and Delete.
*   Create New Template modal and redirect to Template Builder.
*   Navigation between Invoice Templates and Payment Schedules tabs.
*   Empty state handling and default template provisioning.

## **2\. User Roles & Permissions**

**Permission**

**Admin**

**Manager**

**Project Manager**

View Template Listing

✅

✅

✅

Search Templates

✅

✅

✅

Filter Templates

✅

✅

✅

Sort Templates

✅

✅

✅

Create New Template

✅

✅

❌

Open Template (click name)

Editor mode

Editor mode

View-only mode

Edit Template

✅

✅

❌

Duplicate Template

✅

✅

❌

Delete Template

✅

✅

❌

**Permission Notes:**

*   Only Agency Owner, Admin, and Project Manager roles have access to the Templates section.
*   Editor, Supervisor Editor, Team Member, Contractor, and Client roles have no access to the Templates section.
*   Only Agency Owner and Admin can create, edit, duplicate, or delete templates.
*   Project Manager has read-only access. Clicking a template name opens the template in view-only mode.
*   For Project Manager, the "+ Create Invoice Template" button and the three-dot actions menu are hidden.
*   The system enforces these permissions at both UI and API levels.

## **3\. User Flow**

### 3.1 Access Template Listing

*   The user navigates to the left sidebar menu and clicks on "Templates."
*   The system expands the Templates submenu revealing available template categories.
*   The user clicks on "Invoices" from the submenu options.
*   The system loads the Invoice Template Listing page and displays the default "Invoices" tab.
*   The system retrieves all invoice templates from the database that the user has permission to view.
*   The system displays the templates in a table format sorted by Modified Date in descending order by default.

### 3.2 View and Browse Templates

*   The user views the template listing table displaying all available templates.
*   The user can scroll vertically through the list if templates exceed the visible area.
*   The user can click on column headers to sort the data by that column.
*   The user can use pagination controls at the bottom to navigate between pages.
*   The user can switch between "Invoices" and "Payment Schedules" tabs to view different template types.

### 3.3 Search for Templates

*   The user locates the search input field positioned above the template table.
*   The user types a search query into the search field.
*   The system filters the template list in real-time as the user types.
*   The system displays only templates whose names contain the search query.
*   The user can clear the search field to return to the full template list.

### 3.4 Filter Templates by Status

*   The user locates the status filter dropdown next to the search field.
*   The user clicks on the filter dropdown to reveal available options.
*   The user selects one of the available options: "All," "Draft," or "Published."
*   The system filters the template list to show only templates matching the selected status.
*   The filter works in combination with any active search query.

### 3.5 Create New Template

*   The user clicks the "+ Create Invoice Template" button located in the top-right area of the page.
*   The system opens a modal dialog titled "Create Invoice Template."
*   The user enters a template name in the required "Template Name" field.
*   The user selects a brand from the "Brand" dropdown field.
*   The user clicks the "Create" button to proceed.
*   The system validates that all required fields are completed.
*   The system creates a new template record with status "Draft."
*   The system redirects the user to the Template Builder interface (FRD #2).

### 3.6 Perform Template Actions

*   The user locates a template row in the listing table.
*   The user clicks the three-dot action menu icon in the "Actions" column.
*   The system displays a dropdown menu with available actions: Edit, Duplicate, and Delete.
*   The visibility of each action depends on template status and user permissions.
*   The user selects the desired action from the menu.
*   The system executes the selected action and provides appropriate feedback.

## **4\. Functional Logic**

### 4.1 Template Listing Display

#### **4.1.1 Page Layout and Structure**

*   The Invoice Template Listing page is divided into a header section, tab navigation, toolbar section, and content area.
*   The header section displays the page title "Invoice Templates" aligned to the left.
*   The tab navigation displays two tabs: "Invoices" (selected by default) and "Payment Schedules."
*   The toolbar section contains the search input, status filter dropdown, and "+ Create Invoice Template" button.
*   The content area displays the template table with column headers and data rows.
*   The footer area contains pagination controls for navigating through large datasets.

#### **4.1.2 Tab Navigation Behavior**

*   The "Invoices" tab displays the list of invoice templates when selected.
*   The "Payment Schedules" tab navigates to the Payment Schedule Template listing (covered in FRD #4).
*   The currently selected tab is visually highlighted with an underline and bold text.
*   Clicking on a tab loads the corresponding content without a full page refresh.
*   The system preserves the selected tab state during the user's session.

#### **4.1.3 Template Table Structure**

*   The template table displays the following columns in order: Template Icon, Template Name, Brand, Times Used, Status, Modified Date, and Actions.
*   The Template Icon column displays a visual document icon representing the template type.
*   The Template Name column displays the user-defined name of the template as a clickable link.
*   The Brand column displays the brand name associated with the template.
*   The Times Used column displays a numeric count of how many invoices have been created using this template. This counter reflects the total count of invoices ever created from this template, including invoices that have since been deleted; the count never decrements.
*   The Status column displays a badge indicating "Draft" (gray) or "Published" (green).
*   The Modified Date column displays the date and time when the template was last updated.
*   The Actions column displays a three-dot menu icon that reveals available actions when clicked.

#### **4.1.4 Empty State Handling**

*   When no templates exist in the system, the table area displays an empty state message.
*   The empty state message reads: "No invoice templates yet. Click '+ Create Invoice Template' to get started."
*   The empty state includes an illustrative icon or graphic to provide visual context.
*   The "+ Create Invoice Template" text within the message is styled as a clickable link that triggers the create modal.

#### **4.1.5 Default Templates**

*   \* The system provides default templates upon account creation.
*   \* Default templates are created with Published status and are immediately available for use.
*   \* Default templates can be duplicated but cannot be deleted by any user.
*   \* Default templates are owned by the system and do not have a user-specific owner.
*   \* The default template includes standard invoice blocks with placeholder content.
*   \* \*\*\[To be discussed with client\]\*\* The exact number, naming, and content of default templates will be provided by the client and finalized before launch.

### 4.2 Search Functionality

#### **4.2.1 Search Input Behavior**

*   The search input field is positioned in the toolbar area above the template table.
*   The search input displays placeholder text "Search templates..." when empty.
*   The search input includes a magnifying glass icon on the left side as a visual indicator.
*   When the user begins typing, the system applies search filtering after a 300-millisecond debounce delay.
*   The debounce prevents excessive API calls while the user is still typing.

#### **4.2.2 Search Logic**

*   The system performs a case-insensitive search on the Template Name field only.
*   The search matches any template name that contains the entered search query as a substring.
*   The system does not search within Brand names, descriptions, or other template content.
*   Search results update in real-time without requiring a page refresh or button click.
*   The search filter combines with any active status filter to produce the final result set.

#### **4.2.3 Search Results Display**

*   When search results are found, the table displays only matching templates.
*   The pagination updates to reflect the filtered result count.
*   \* When no results match the search query (alone or combined with the status filter), the system displays a unified message: "No results found."
*   \* The no-results message includes a "Clear search" link that resets the search field.
*   The search query text is preserved in the input field while viewing results.

#### **4.2.4 Clear Search**

*   The user can clear the search by deleting all text from the search input field.
*   When the search field is cleared, the system displays all templates matching the current status filter.
*   A clear icon (X) appears inside the search field when text is present, allowing one-click clearing.
*   Clearing the search does not affect the selected status filter.

### 4.3 Filter Functionality

#### **4.3.1 Status Filter Dropdown**

*   The status filter dropdown is positioned next to the search input in the toolbar area.
*   The dropdown displays the currently selected filter value as its label.
*   The default selected value is "All" which shows templates of all statuses.
*   Clicking the dropdown reveals three options: "All," "Draft," and "Published."
*   The currently selected option displays a checkmark indicator.

#### **4.3.2 Filter Options Behavior**

*   Selecting "All" displays both Draft and Published templates in the listing.
*   Selecting "Draft" displays only templates with Draft status.
*   Selecting "Published" displays only templates with Published status.
*   The filter selection is applied immediately upon selection without requiring a separate action.
*   The filter combines with any active search query to produce the final result set.

#### **4.3.3 Filter Persistence**

*   The selected filter value persists during the user's browsing session on this page.
*   Navigating to another page and returning resets the filter to "All" by default.
*   The filter selection is not stored in the URL or user preferences in Phase 1.

### 4.4 Sort Functionality

#### **4.4.1 Sortable Columns**

*   The following columns support sorting: Template Name, Times Used, and Modified Date.
*   Sortable column headers display a sort indicator icon when hovered.
*   Non-sortable columns (Template Icon, Brand, Status, Actions) do not respond to header clicks.
*   The default sort order is Modified Date in descending order (newest first).

#### **4.4.2 Sort Interaction**

*   The user clicks on a sortable column header to apply sorting by that column.
*   The first click sorts the column in ascending order (A-Z for text, lowest-highest for numbers, oldest-newest for dates).
*   A second click on the same column header reverses the sort to descending order.
*   A third click on the same column header returns to ascending order.
*   The active sort column displays an arrow icon indicating the current sort direction.

#### **4.4.3 Sort Behavior**

*   Only one column can be sorted at a time; clicking a new column replaces the previous sort.
*   Sorting is applied to the entire dataset, not just the currently visible page.
*   Sorting preserves any active search query and status filter.
*   The pagination resets to page 1 when sort order is changed.

### 4.5 Pagination Functionality

#### **4.5.1 Pagination Controls**

*   Pagination controls are displayed at the bottom of the template table.
*   The controls include: rows per page selector, current range indicator, and navigation buttons.
*   The rows per page selector offers options: 10, 25, and 50 rows per page.
*   The default rows per page value is 10.
*   The current range indicator displays in the format "1-10 of 45" showing the current range and total count.

#### **4.5.2 Navigation Buttons**

*   The pagination includes "Previous" and "Next" buttons for sequential navigation.
*   The pagination includes "First" and "Last" buttons for jumping to extremes.
*   The "Previous" and "First" buttons are disabled when viewing the first page.
*   The "Next" and "Last" buttons are disabled when viewing the last page.
*   Clicking a navigation button scrolls the table to the top of the new page.

#### **4.5.3 Rows Per Page Change**

*   When the user changes the rows per page value, the system recalculates the total number of pages.
*   The current page resets to page 1 when rows per page is changed.
*   The selection persists during the user's session on this page.

### 4.6 Template Actions

#### **4.6.1 Actions Menu Display**

*   \* Each template row displays a three-dot icon (⋮) in the Actions column for Agency Owner and Admin users only.
*   \* For Project Manager users, the three-dot icon is hidden entirely
*   \* Clicking the three-dot icon opens a dropdown menu with available actions.
*   \* The menu displays three actions: Edit, Duplicate, and Delete.
*   \* All three actions are available to Agency Owner and Admin for any template regardless of status (subject to deletion protection rules in Section 4.8.2).
*   \* Clicking outside the menu or pressing Escape closes the menu without taking action.
*   \* Only one actions menu can be open at a time; opening another closes the previous one.

**\*\*4.6.1.1 Template Name Click Behavior\*\***

*   \* Clicking the Template Name link in any row opens the template.
*   \* For Agency Owner and Admin: the template opens in the Template Builder (Edit mode).
*   \* For Project Manager: the template opens in view-only mode. All edit controls are disabled and no Save/Publish actions are available

**4.6.2 Edit Action**

*   \* The "Edit" action is displayed in the actions menu for Agency Owner and Admin only.
*   \* Project Manager does not see the actions menu at all and cannot edit templates from any entry point.
*   \* Edit is available for templates of any status (Draft or Published).
*   \* Clicking "Edit" navigates the user to the Template Builder interface (FRD #2) with the template loaded.
*   \* The system passes the template ID to the Builder to load the existing template data.

#### **4.6.3 Duplicate Action**

*   \* The "Duplicate" action is available to Agency Owner and Admin only via the three-dot kebab menu in the Actions column.
*   \* Project Manager cannot duplicate templates.
*   \* Duplicate is available for templates of any status (Draft or Published), including default templates.
*   \* Clicking "Duplicate" creates a full copy of the template
*   \* The duplicated template name follows this naming convention:
*   \* First duplicate of "Wedding Invoice" → "Copy of Wedding Invoice"
*   \* Second duplicate of "Wedding Invoice" → "Copy of Wedding Invoice (1)"
*   \* Third duplicate → "Copy of Wedding Invoice (2)", and so on
*   \* If "Copy of Wedding Invoice (1)" is itself duplicated, the system creates "Copy of Wedding Invoice (2)" by incrementing the highest existing number for that base name
*   \* The duplicated template status is set to Draft regardless of the source template's status.
*   \* The duplicated template's "Times Used" count is set to 0.
*   \* The duplicated template's owner is set to the user who performed the duplication.
*   \* After the user clicks Duplicate, the action menu closes immediately and the Duplicate option is disabled until the API response is received, to prevent duplicate API calls from rapid double-clicks.
*   \* The duplicated template appears in the listing immediately after creation; the user remains on the listing page (no redirect to the Builder).
*   \* The system displays a success toast: "Template duplicated successfully."

**4.6.4 Delete Action**

*   The "Delete" action is available to Agency Owner and Admin only.
*   \* Project Manager cannot delete templates.
*   \* Delete is available for any template that is not protected by the Template Protection Rule (see Section 4.8.2).
*   \* Default templates cannot be deleted by any user, regardless of role.
*   \* Clicking "Delete" displays a confirmation modal before proceeding.
*   \* The confirmation modal displays: "Are you sure you want to delete '\[Template Name\]'? This action cannot be undone."
*   \* The modal includes "Cancel" and "Delete" buttons, with "Delete" styled in red to indicate destructive action.
*   \* Upon confirmation, the system permanently removes the template from the database.
*   \* The system displays a success toast: "Template '\[Template Name\]' deleted successfully."
*   \* The template is immediately removed from the listing table.

### 4.7 Create New Template Modal

#### **4.7.1 Modal Display**

*   Clicking "+ Create Invoice Template" opens a modal dialog centered on the screen.
*   The modal includes a semi-transparent backdrop that dims the page behind it.
*   The modal title displays "Create Invoice Template" at the top.
*   The modal can be closed by clicking the X icon, clicking the backdrop, or pressing Escape.
*   Closing the modal without saving discards any entered data without warning.

#### **4.7.2 Modal Form Fields**

*   The modal contains two form fields: "Template Name" and "Brand."
*   The "Template Name" field is a text input marked as required with an asterisk (\*).
*   The "Template Name" field displays placeholder text "Enter template name."
*   The "Brand" field is a dropdown selector marked as required with an asterisk (\*).
*   The "Brand" dropdown is populated with all brands configured in the user's account.
*   If only one brand exists, it is pre-selected by default.
*   If multiple brands exist, the dropdown displays "Select a brand" as the default placeholder.

#### **4.7.3 Modal Actions**

*   The modal footer contains two buttons: "Cancel" and "Create."
*   \* The "Cancel" button closes the modal without creating a template.
*   \* The "Create" button is enabled when both required fields are non-empty.
*   \* Validation is triggered on Create button click. On submit, the system trims whitespace from the Template Name and validates. If only whitespace was entered, the system displays the "Template name is required" error inline below the field and does not submit.
*   \* Clicking "Create" with valid data submits the form to create the template.
*   \* The system creates a new template record with the provided name (trimmed) and brand.
*   \* The new template is assigned Draft status and the current user as owner.
*   \* Upon successful creation, the system redirects to the Template Builder (FRD #2).
*   \* A success toast displays: "Template '\[Template Name\]' created successfully."
*   \* If the create request fails for any reason (server error, network error, backend validation error), the system displays an error toast: "Something went wrong." The modal remains open with the entered data preserved so the user can retry.

### 4.8 Key Business Rules

#### **4.8.1 Template Status Rules**

*   Templates exist in one of two statuses: Draft or Published.
*   Only Published templates are available for selection when creating invoices in projects.
*   Draft templates are visible in the listing but cannot be used to create invoices.
*   The status is displayed as a colored badge: gray for Draft, green for Published.
*   Once a template is Published, it remains Published permanently; there is no unpublish feature.

#### **4.8.2 Template Protection Rules**

*   Published templates with "Times Used" greater than 0 cannot be deleted by any user.
*   This protection ensures that historical invoice records maintain their template reference integrity.
*   The delete option is hidden (not disabled) for protected templates to avoid user confusion.
*   If a user attempts to delete via API, the system returns an error: "Cannot delete template that has been used for invoices."

#### **4.8.3 Template Snapshot Rule**

*   When an invoice is created using a template, the system captures a complete snapshot of the template at that moment.
*   Any subsequent modifications to the template do not affect invoices that were already created.
*   This ensures invoice consistency and prevents retroactive changes to sent invoices.
*   The snapshot is stored with the invoice record, not as a reference to the template.

#### **4.8.4 Default Template Rules**

*   The system provides default templates upon account creation. \*\*\[To be discussed with client\]\*\* The exact number, naming, and content of default templates will be provided by the client and finalized before launch.
*   \* Default templates are owned by the system (no user owner) and cannot be deleted.
*   \* Default templates can be duplicated to create user-owned copies for modification.
*   \* Default templates are pre-configured with standard invoice structure and placeholder content.

## **5\. Field Details & Validations**

**Field**

**Type**

**Required**

**Validation Rules**

**Max Length**

**Error Message**

Template Name

Text Input

✅

Cannot be empty; must contain at least one non-space character

100

"Template name is required."

Brand

Dropdown

✅

Must select a valid brand from the list

N/A

"Please select a brand."

Search Query

Text Input

❌

No validation; accepts any characters

N/A

N/A

Status Filter

Dropdown

❌

Must be one of: All, Draft, Published

N/A

N/A

Rows Per Page

Dropdown

❌

Must be one of: 10, 25, 50

N/A

N/A

## **6\. Success Message Handling**

**Action**

**Success Message**

**Display Method**

**Duration**

**Post-Action Behavior**

Create Template

"Template '\[Name\]' created successfully."

Toast notification (green, top-right)

3 seconds

Redirect to Template Builder

Duplicate Template

"Template duplicated successfully."

Toast notification (green, top-right)

3 seconds

New template appears in listing

Delete Template

"Template '\[Name\]' deleted successfully."

Toast notification (green, top-right)

3 seconds

Template removed from listing

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Display Method**

**User Action Required**

Empty or whitespace-only template name on create

"Template name is required."

Inline error below field (red text)

Enter a valid template name

No brand selected on create

"Please select a brand."

Inline error below field (red text)

Select a brand from the dropdown

Create template failed (server / network / backend error)

"Something went wrong."

Toast notification (red)

Retry the action; modal data remains preserved

Delete published template (in use)

"Cannot delete. This template has been used in \[X\] invoice(s)."

Error modal dialog

Acknowledge and close

Edit template without permission

"You don't have permission to edit this template."

Toast notification (red)

Contact the Agency Owner or Admin

Search or filter returns no results

"No results found."

Inline message in table area

Modify or clear the search/filter

Network error during action

"An error occurred. Please check your connection and try again."

Toast notification (red)

Retry the action

## **8\. Edge Cases**

**Edge Case**

**Description**

**Expected System Behavior**

Empty State (No Templates)

User accesses listing when no templates exist.

The system displays the empty state message with a prompt to create the first template. Default templates should prevent this scenario.

Concurrent Edit Conflict

Two users attempt to edit the same template simultaneously.

In Phase 1, the last save wins. No conflict detection or merge is implemented. Users should coordinate to avoid simultaneous edits.

Delete While Another User Editing

User A deletes a template while User B has it open in Builder.

When User B attempts to save, the system displays: "Template no longer exists. Your changes could not be saved."

Duplicate Template Name

User creates or duplicates a template with a name that already exists.

The system allows duplicate names since templates are uniquely identified by internal ID, not name.

Large Dataset (1000+ Templates)

Organization has a very large number of templates.

Pagination and server-side filtering ensure performance. The system retrieves only the current page's data from the server.

Special Characters in Search

User enters special characters (e.g., @, #, %) in search query.

The system treats special characters as literal search text and attempts to match them in template names.

Browser Back Button

User clicks browser back button while in Template Builder.

The browser navigates back to the Template Listing. Unsaved changes in Builder may be lost (see FRD #2 for Builder behavior).

Session Timeout

User's session expires while viewing the listing.

On next action, the system redirects to the login page. After login, user returns to the listing.

Network Disconnection

User loses network connection while performing an action.

The system displays a network error toast and the action fails. Data remains unchanged until successfully retried.

Pagination Stale Data

User A is viewing page 2 of results while User B deletes a template from page 1, causing User A's view to become off-by-one.

Pagination data is fetched per request. Users may see shifted results if other users modify the dataset between page navigations. No real-time sync is implemented in Phase 1.

## **9\. Acceptance Criteria**

*   ✅ The Invoice Template Listing page loads successfully when navigating to Templates → Invoices.
*   ✅ The template table displays all expected columns: Icon, Name, Brand, Times Used, Status, Modified Date, Actions.
*   ✅ Default templates are present for new accounts.
*   ✅ The search field filters templates by name in real-time with appropriate debounce.
*   ✅ The status filter correctly filters templates by Draft, Published, or All.
*   ✅ Search and filter work in combination to produce accurate results.
*   ✅ Sortable columns (Name, Times Used, Modified Date) respond to header clicks with correct sort behavior.
*   ✅ Pagination controls function correctly with 10/25/50 rows per page options.
*   ✅ The "+ Create Invoice Template" button opens the create modal.
*   ✅ The create modal validates required fields and displays appropriate errors.
*   ✅ Successfully created templates redirect to the Template Builder.
*   ✅ The three-dot action menu displays Edit, Duplicate, and Delete options based on permissions.
*   ✅ The Edit action opens the Template Builder with the template loaded.
*   ✅ The Duplicate action creates a copy with "(Copy)" suffix and Draft status.
*   ✅ The Delete action shows confirmation and removes the template upon confirmation.
*   ✅ Published templates with Times Used > 0 cannot be deleted (option hidden).
*   ✅ All actions respect user role permissions as defined in the permissions matrix.
*   ✅ Success and error messages display appropriately for all actions.

## **10\. Dependencies**

**Dependency Type**

**Dependency Name**

**Description**

**Impact if Unavailable**

Internal Module

Template Builder (FRD #2)

Required for creating and editing template content.

Users cannot create or modify template content; only viewing is possible.

Internal Module

Brand Module

Provides list of brands for template association.

Users cannot create templates without brand selection.

Internal Module

User & Permissions Module

Enforces role-based access control.

All users may see all actions; security compromised.

Internal Module

Invoice Module (FRD #5)

Consumes templates for invoice creation; tracks Times Used.

Times Used count will not increment; template usage not tracked.

Database

Invoice\_Templates Table

Stores template metadata and content.

No templates can be stored or retrieved.

Database

Brands Table

Stores brand configuration.

Brand dropdown will be empty.

API

Template CRUD Endpoints

Handles create, read, update, delete operations.

No template operations possible.

Frontend

Toast Notification Component

Displays success and error messages.

Users receive no feedback on action results.

## **11\. References**

**Figma Designs:**

*   1-Invoice\_template\_listing.png - Main listing page layout
*   1-payment\_schedule\_template\_listing.png - Payment Schedules tab reference

**Related FRDs:**

*   FRD #2: Invoice Template Creation & Template Builder
*   FRD #3: Edit Invoice Template with Conditions
*   FRD #4: Payment Schedule Template Listing & Create New Payment Schedule

**Source Documents:**

*   Module Logic Explanation - Meeting Transcript (December 2025)
*   Client Meeting MOM - Invoice Module Discussion
*   Clarifying Questions & Answers Document

☑️ 2. Invoice Template Creation & Template Builder

# **FRD #2: Invoice Template Creation & Template Builder**

**Version:** 1.0  
**Date:** December 10, 2025

## **1\. Module Overview**

**Purpose:  
**The Invoice Template Builder provides a visual interface for creating and customizing invoice templates. Users can configure invoice structure, add line items with auto-suggest from existing Packages and À la Carte services, set up payment terms, apply styling (colors and fonts), and publish templates for use across projects.

**Business Goals:**

*   Enable professional invoice design without technical expertise.
*   Ensure brand consistency through customizable styling options.
*   Reduce invoice creation time through reusable templates and payment presets.
*   Support flexible payment configurations with multiple date and payment types.
*   Streamline line item entry through auto-suggest from existing service catalog.

**Scope:**

*   Template Builder interface layout and navigation.
*   Invoice Structure configuration with 5 mandatory blocks.
*   Custom section addition (Text and Image blocks).
*   Line item management with auto-suggest functionality.
*   Payment Terms configuration with 4 date types and 3 payment types.
*   Tax configuration per line item and discount configuration.
*   Colors and Fonts styling tabs.
*   Save as Template (draft) and Publish actions.
*   Preview functionality.
*   Unsaved changes warning on exit.

## **2\. User Roles & Permissions**

**Permission**

**Admin**

**Manager**

**Team Member**

Access Template Builder (Edit Mode)

✅

✅

❌

Create New Template

✅

✅

❌

Edit Template (Draft or Published)

✅

✅

❌

Publish Template

✅

✅

❌

Re-Publish Template (Already Published)

✅

✅

❌

Configure Line Items

✅

✅

❌

Configure Payment Terms

✅

✅

❌

Apply Payment Preset

✅

✅

❌

Save Payment Preset

✅

✅

❌

Configure Styling (Colors, Fonts)

✅

✅

❌

Configure Settings (Expiration)

✅

✅

❌

Preview Template

✅

✅

✅

**Permission Notes:**

*   \* Only Agency Owner, Admin, and Project Manager roles have access to the Templates section.
*   \* Editor, Supervisor Editor, Contractor, and Client roles have no access to the Templates section.
*   \* Only Agency Owner and Admin can edit, publish, or configure any template settings.
*   \* Project Manager has read-only access. When clicking a template name from the listing (FRD #1), the Template Builder opens in view-only mode with all edit controls disabled and no Publish action available. Preview remains available.
*   \* Publishing a template makes it available for use in invoice creation across all projects.
*   \* The system enforces these permissions at both UI and API levels.

## **3\. User Flow**

### 3.1 Access Template Builder

*   The user clicks "+ Create Invoice Template" from the Template Listing page (FRD #1).
*   The system opens the Create Invoice Template modal.
*   The user enters a template name and selects a brand.
*   The user clicks "Create" to proceed.
*   The system creates a new template record with Draft status and redirects to the Template Builder.
*   The Template Builder loads with the default invoice structure displaying all 5 mandatory blocks.

### 3.2 Edit Existing Template

*   The user clicks "Edit" from the three-dot menu on a template in the listing.
*   The system loads the Template Builder with the selected template's existing configuration.
*   All previously saved content, styling, and payment terms are displayed for editing.

### 3.3 Configure Invoice Structure

*   The user views the left sidebar with the "Invoice Structure" tab selected by default.
*   The user sees the list of 5 mandatory blocks: Logo, Title, Contact Information, Items, and Payment Terms.
*   The user clicks on a block name in the left sidebar to highlight the corresponding section in the builder.
*   The user configures each block's content directly in the main builder area.
*   The user can add custom Text or Image sections by hovering over any block and clicking the "+" button.
*   The user can reorder blocks by dragging and dropping them in the builder.

### 3.4 Configure Line Items

*   The user locates the Items section in the builder.
*   The user clicks on the Item Name field to begin adding a line item.
*   The user types in the Item Name field, and the system displays auto-suggest results from Packages and À la Carte services.
*   The user selects an item from the suggestions or enters a custom item name.
*   The system auto-populates the Description, Qty, Unit, and Price fields if a suggestion is selected.
*   The user can override any auto-populated field values as needed.
*   The user toggles the Tax switch if the item is taxable.
*   The user clicks "Add New Item" to add additional line items.
*   The user can delete a line item by clicking the trash icon on the item row.
*   The user can reorder line items by dragging and dropping.

### 3.5 Configure Tax and Discount

*   The user views the Subtotal displayed below the line items.
*   The user clicks "Add Discount" to apply a discount to the invoice.
*   The user enters the discount value as a percentage or fixed amount.
*   The Tax amount is calculated automatically based on taxable line items.
*   The Total Amount is displayed as: (Subtotal - Discount) + Tax.

### 3.6 Configure Payment Terms

*   The user scrolls to the Payment Terms section in the builder.
*   The user clicks the "Add Payment" button to open the Payment Terms modal.
*   The user configures one or more payment entries with date type and payment type.
*   The user can click "Apply Preset" to load a saved payment schedule configuration.
*   The user can click "Save as Preset" to save the current configuration for future use.
*   The user saves the payment terms and returns to the builder.

### 3.7 Apply Styling

*   The user clicks the "Colors" tab in the left sidebar to access color settings.
*   The user configures Text Color, Button Text Color, Button Color, and Background Color.
*   The user can check "Use Brand Colors" to auto-fill colors from the brand settings.
*   The user clicks the "Fonts" tab to access font settings.
*   The user selects a Font Family and Font Size.
*   Changes are reflected in the builder in real-time.

### 3.8 Preview Template

*   The user clicks the "Preview" button in the header.
*   The system displays a full preview of the template on the same page.
*   The user reviews the template appearance with sample data.
*   The user closes the preview to return to editing.

### 3.9 Publish

*   The user clicks "Publish" to publish the template.
*   \* The system validates the template configuration.
*   \* If validation passes, the system commits the changes and publishes the template.
*   \* If the template was already Published and unpublished changes exist, an alert banner with a "Publish Changes" button is shown in the canvas area (see Section 4.13.6).
*   \* If validation fails, the system displays an error message indicating what needs to be corrected.

### 3.10 Exit Builder

*   The user clicks the Back arrow (←) in the header to exit the builder.
*   All changes are auto-saved, so the system navigates directly back to the Template Listing page without any confirmation prompt.

## **4\. Functional Logic**

### 4.1 Template Builder Layout

#### **4.1.1 Overall Page Structure**

*   The Template Builder page consists of a header bar and a main content area divided into a left sidebar and a builder canvas.
*   The header bar spans the full width of the page and contains navigation and action buttons.
*   The left sidebar contains tabs for configuring different aspects of the template.
*   The builder canvas displays the actual invoice template that the user is constructing.

#### **4.1.2 Header Bar Elements**

*   \* The header bar displays a Back arrow (←) button on the far left for exiting the builder.
*   \* The template name is displayed next to the Back button and is inline editable.
*   \* The user can click on the template name to edit it directly in the header.
*   \* A status badge displays next to the template name showing "Draft" (gray) or "Published" (green).
*   \* The "Preview" button is displayed on the right side of the header.
*   \* The "Publish" button is displayed next to the Preview button.
*   \* The Publish button is always visible regardless of template status.

**\*\*Cross-Builder Consistency:\*\***

*   \* The header layout (Back arrow + template name + status badge + Preview + Publish) follows the same pattern across all template builders in the system (Invoice, Proposal, Contract, Questionnaire, Email, Package, etc.).
*   \* The format used to display the template name in the header is consistent across all template builders, ensuring a uniform experience when opening any template type.

#### **4.1.3 Left Sidebar Tabs**

*   The left sidebar displays four tabs represented by icons: Invoice Structure, Colors, Fonts, and Settings.
*   The Invoice Structure tab icon is a document/list icon and is selected by default when the builder loads.
*   The Colors tab icon is a palette/paint icon.
*   The Fonts tab icon is a typography/text icon.
*   The Settings tab icon is a gear/cog icon.
*   Clicking on a tab icon switches the sidebar content to display the corresponding configuration options.
*   The currently selected tab is visually highlighted.

#### **4.1.4 Builder Canvas**

*   The builder canvas occupies the main area of the page to the right of the left sidebar.
*   The canvas displays the invoice template with all configured blocks in a WYSIWYG (What You See Is What You Get) manner.
*   The canvas is scrollable if the content exceeds the visible area.
*   Each block in the canvas is interactive and can be clicked to edit its content.
*   Hovering over a block displays a border highlight and reveals the "+" button for adding sections.

### 4.2 Invoice Structure Tab

#### **4.2.1 Block List Display**

*   The Invoice Structure tab displays a list of all blocks in the template.
*   The 5 mandatory blocks are always displayed: Logo, Title, Contact Information, Items, and Payment Terms.
*   Each block is displayed with an icon and the block name.
*   Mandatory blocks display a lock icon indicating they cannot be deleted.
*   Custom sections (Text, Image) appear in the list when added.
*   The blocks are listed in the same order as they appear in the builder canvas.

#### **4.2.2 Block Selection Behavior**

*   Clicking on a block name in the left sidebar highlights the corresponding block in the builder canvas.
*   The highlighted block displays a colored border to indicate selection.
*   The canvas automatically scrolls to bring the selected block into view if it is not visible.
*   Only one block can be highlighted at a time.

#### **4.2.3 Adding Custom Sections**

*   When the user hovers over any block in the builder canvas, the block displays a border highlight.
*   A "+" button appears on the bottom border of the hovered block.
*   Clicking the "+" button opens a dropdown menu with two options: "Text" and "Image."
*   Selecting "Text" inserts a new Text section below the hovered block.
*   Selecting "Image" inserts a new Image section below the hovered block.
*   The newly added section appears immediately in both the canvas and the left sidebar block list.
*   Custom sections can be deleted by clicking the delete/trash icon that appears when the section is selected.

#### **4.2.4 Block Reordering**

*   All blocks (mandatory and custom) can be reordered via drag-and-drop.
*   The user clicks and holds on a block in the builder canvas to initiate dragging.
*   A visual indicator shows where the block will be placed when dropped.
*   Releasing the mouse button drops the block in the new position.
*   The block list in the left sidebar updates to reflect the new order.
*   There are no up/down arrow buttons for reordering; drag-and-drop is the only method.

### 4.3 Mandatory Blocks Configuration

#### **4.3.1 Logo Block**

*   The Logo block displays the brand logo at the top of the invoice.
*   The logo is automatically pulled from the brand settings associated with the template.
*   The user can click on the logo area to upload a different logo for this specific template.
*   Supported image formats include PNG, JPG, and SVG.
*   The logo is displayed at a standardized size to maintain consistency.
*   If no logo is configured, a placeholder with "Add Logo" text is displayed.

#### **4.3.2 Title Block**

*   \* The Title block displays the invoice title text.
*   \* The default title is "INVOICE" and is displayed in a prominent font size.
*   \* The user can click on the title to edit the text inline.
*   \* The title text is customizable (e.g., "TAX INVOICE," "PROFORMA INVOICE").
*   \* The title block also displays the "ISSUED ON" date and "DUE DATE" fields.
*   \* In the template builder, ISSUED ON and DUE DATE display as non-editable placeholder text (e.g., "Auto-filled on send") since actual dates are determined at invoice creation time.
*   \* When the template is used to create an invoice in a project, ISSUED ON is set to the date the invoice is sent, and DUE DATE is calculated based on the configured payment terms.

#### **4.3.3 Contact Information Block**

*   The Contact Information block displays the "FROM" (agency) and "BILL TO" (client) sections.
*   The FROM section displays the company name, address, and email from the brand settings.
*   The user can click "Add Address" to add or edit the company address.
*   The BILL TO section displays placeholder fields for client name and email.
*   In the template builder, these fields show placeholder text since no client is assigned.
*   When the template is used to create an invoice in a project, the client details auto-populate.

#### **4.3.4 Items Block**

*   The Items block displays the line items table with columns for Item Name, Qty, Unit, Price, and Tax toggle.
*   The block displays "Add New Item" link for adding additional line items.
*   Below the line items, the block displays Subtotal, Add Discount link, Tax amount, and Total Amount.
*   The Items block is the primary area for configuring the invoice's financial content.
*   This block cannot be deleted as it is mandatory.

#### **4.3.5 Payment Terms Block**

*   The Payment Terms block displays the configured payment schedule.
*   The block shows a table with columns for payment name/label, due date, amount, and status.
*   The block displays "Save as Preset" and "Apply Preset" buttons in the header area.
*   An "Add Payment" button is available for adding payment entries via the Payment Terms modal.
*   The descriptive text "Specify when and how you will be paid" is displayed below the block title.
*   This block cannot be deleted as it is mandatory.

### 4.4 Line Items Management

#### **4.4.1 Line Item Table Structure**

*   Each line item row displays the following fields from left to right: Item Name, Qty, Unit, Price, Tax toggle, and Delete icon.
*   The Item Name field is a text input that supports auto-suggest functionality.
*   The Qty field is a numeric input defaulting to 1.
*   The Unit field is a text input for specifying the unit type (e.g., "hours," "each," "package").
*   The Price field displays the unit price in currency format.
*   The Tax toggle is a switch that enables or disables tax calculation for this item.
*   The Delete icon (trash) removes the line item when clicked.
*   A description field is displayed below the Item Name on a second row within the same item entry.

#### **4.4.2 Auto-Suggest Functionality**

*   When the user clicks on the Item Name field and begins typing, the system triggers auto-suggest.
*   The system searches the Packages and À la Carte Items configured in the system.
*   The auto-suggest dropdown displays matching results in two sections: "PACKAGES" and "A LA CARTE ITEMS."
*   Each suggestion displays the item name, price, description, and event tags (e.g., "WEDDING," "REHEARSAL DINNER").
*   The search is case-insensitive and matches partial text within item names.
*   If no matches are found, the user can continue typing to enter a custom item name.
*   The dropdown closes when the user clicks outside or presses Escape.

#### **4.4.3 Selecting from Auto-Suggest**

*   When the user clicks on a suggestion from the dropdown, the system auto-populates the line item fields.
*   The Item Name field is populated with the selected item's name.
*   The Description field is populated with the selected item's description.
*   The Qty field is populated with the default quantity (typically 1).
*   The Unit field is populated with the item's unit type if defined.
*   The Price field is populated with the selected item's price.
*   The user can modify any of the auto-populated fields after selection.
*   Modifying a field does not affect the original Package or À la Carte Item in the catalog.

#### **4.4.4 Adding New Line Items**

*   The user clicks "Add New Item" link displayed below the last line item.
*   The system adds a new empty line item row at the bottom of the items list.
*   The cursor automatically focuses on the Item Name field of the new row.
*   There is no limit to the number of line items that can be added to a template.

#### **4.4.5 Deleting Line Items**

*   Each line item row displays a trash icon on the right side.
*   Clicking the trash icon removes the line item from the template.
*   The system does not display a confirmation prompt for line item deletion.
*   The Subtotal and Total recalculate immediately after deletion.
*   If all line items are deleted, the template will fail validation on publish.

#### **4.4.6 Reordering Line Items**

*   Line items can be reordered by dragging and dropping.
*   The user clicks and holds on a line item row to initiate dragging.
*   A visual indicator shows the target position while dragging.
*   Releasing the mouse button drops the item in the new position.
*   The order of line items determines how they appear on the final invoice.

### 4.5 Tax Configuration

#### **4.5.1 Per-Item Tax Toggle**

*   Each line item row includes a Tax toggle switch on the right side.
*   The toggle has two states: Off (gray) and On (yellow/active).
*   When the toggle is On, the item's amount is included in tax calculation.
*   When the toggle is Off, the item's amount is excluded from tax calculation.
*   The default state of the toggle is Off for new line items.

#### **4.5.2 Tax Calculation Display**

*   The tax amount is displayed below the Subtotal in the Items block.
*   The tax is displayed in the format "\[X\]% Tax" followed by the calculated amount (e.g., "8.5% Tax $42.50").
*   The tax percentage rate is configured at the invoice level (not per item).
*   Tax is calculated on the sum of all line items where the Tax toggle is On.
*   If a discount is applied, tax is calculated on (Subtotal - Discount) for taxable items.

#### **4.5.3 Tax Rate Configuration**

*   The tax rate can be configured as a percentage (e.g., 8.5%).
*   The tax rate can be configured as a fixed amount.
*   The tax rate can be set to "Auto-Calculate" which uses Stripe Tax integration.
*   Auto-Calculate requires Stripe to be connected to the account.
*   If Stripe is not connected and Auto-Calculate is selected, an error message is displayed.

### 4.6 Discount Configuration

#### **4.6.1 Add Discount Link**

*   The "Add Discount" link is displayed below the Subtotal amount.
*   The link text is styled in yellow/gold color to indicate an action.
*   Clicking "Add Discount" expands the discount configuration area.

#### **4.6.2 Discount Options**

*   The discount can be configured as a percentage of the Subtotal.
*   The discount can be configured as a fixed dollar amount.
*   The user can toggle between percentage and fixed amount modes.
*   For percentage discount, the value must be between 0 and 100.
*   For fixed amount discount, the value cannot exceed the Subtotal.

#### **4.6.3 Discount Display**

*   Once configured, the discount is displayed as a line below the Subtotal.
*   The discount shows the value (e.g., "-10%" or "-$50") and the calculated amount.
*   The discount amount is subtracted from the Subtotal before tax calculation.

### 4.7 Invoice Calculations

#### **4.7.1 Subtotal Calculation**

*   The Subtotal is the sum of all line item totals.
*   Line Item Total = Qty × Price.
*   The Subtotal is displayed below the line items table.
*   The Subtotal updates automatically as line items are added, modified, or deleted.

#### **4.7.2 Tax Calculation**

*   Tax is calculated on the taxable amount after discounts are applied.
*   **Taxable Amount** = Sum of (**Qty × Price**) for line items where the **Tax** toggle is enabled.
*   Tax applies only to taxable line items (items with the **Tax** toggle enabled).

### 4.7.2.1 Flat Discount Calculation

*   A flat discount is proportionally distributed across all line items (taxable and non-taxable) before tax calculation.
*   Formula:

Tax = (T − (D × T / S)) × R

Where:

*   **T** = Taxable subtotal
*   **D** = Flat discount amount
*   **S** = Overall subtotal before discount
*   **R** = Tax rate
*   Example:  
    *   Subtotal (**S**) = $60
    *   Taxable subtotal (**T**) = $20
    *   Flat discount (**D**) = $15
    *   Tax rate (**R**) = 8.75%
*   Calculation:  
    *   Discount allocated to taxable portion = 15 × (20 / 60) = $5
    *   Adjusted taxable amount = 20 − 5 = $15
    *   Tax = 15 × 8.75% = **$1.31**

### 4.7.2.2 Percentage Discount Calculation

*   The taxable subtotal is reduced by the same percentage before tax calculation.
*   Formula:

Tax = T × (1 − P) × R

Where:

*   **T** = Taxable subtotal
*   **P** = Discount percentage (decimal format)
*   **R** = Tax rate
*   Example:  
    *   **T** = $20
    *   **P** = 15%
    *   **R** = 8.75%
*   Calculation:  
    *   Tax = 20 × (1 − 0.15) × 0.0875 = **$1.49**

### 4.7.2.3 Edge Cases

*   If the subtotal is **$0**, the taxable base is **$0**, and no proportional calculation is performed.
*   If no line items have the **Tax** toggle enabled, the **Tax Amount** is **$0** regardless of any applied discount.
*   The **Tax Amount** is displayed below the **Discount** field (or below **Subtotal** if no discount is applied).

#### **4.7.3 Total Amount Calculation**

*   Total Amount = Subtotal - Discount + Tax.
*   The Total Amount is prominently displayed at the bottom of the Items block.
*   The Total Amount is styled in bold to emphasize its importance.
*   The Total Amount updates in real-time as any values change.

**4.7.4 Proposal-to-Invoice Discount Conversion (Backend Logic)**

This section applies when an invoice is auto-generated from a proposal (see FRD #5 for the complete auto-generation flow).  
The logic below ensures consistent discount handling between proposals and the invoices generated from them.

## **4.7.4.1 Proposal Discount Structure**

Proposals support two discount groups:

*   Bundle Discount
*   Regular Discount

Each discount group supports two discount types:

*   Flat Discount
*   Percentage Discount

Each discount can apply to one of the following scopes:

1.  Packages only
2.  Packages + A La Carte

## **4.7.4.2 Conversion Rule**

Invoices display discounts as monetary (**flat**) values.  
When a proposal-level percentage discount is converted into an invoice, the system must convert it into a flat amount under specific conditions.

### 4.7.4.3 Conversion is required if ALL of the following are true:

*   Discount type = **Percentage**
*   Discount scope = **Packages only**
*   A La Carte items exist in the proposal

### 4.7.4.4 In this case, the system must:

*   Calculate the percentage discount using the **package subtotal only**
*   Convert the calculated result into a flat discount amount
*   Store the invoice discount as a flat monetary value

## **Example**

**Item Type**

**Amount**

Package 1

$100

Package 2

$100

A La Carte

$50

### Configuration

*   Discount Group = Regular Discount
*   Discount Scope = Packages Only
*   Discount Type = Percentage
*   Discount Value = 10%

### Calculation

*   Package subtotal = 100 + 100 = $200
*   Discount amount formula:

**Discount Amount=Package Subtotal×Discount Percentage**

*   Discount amount = 200 × 10% = $20

### Invoice Result

*   The generated invoice stores the discount as a flat **$20** discount.

## **4.7.4.5 When Conversion Is NOT Required**

### Case 1 — No A La Carte Items Exist

If the proposal contains only packages:

*   The percentage discount remains percentage-based

### Case 2 — Discount Applies to Packages + A La Carte

If the discount scope includes all items:

*   The percentage discount remains percentage-based

## **Final Backend Rules Summary**

**Scenario**

**Expected Behavior**

Flat discount + packages only

Apply directly

Flat discount + packages + a la carte

Apply directly

Percentage discount + packages + a la carte

Keep as percentage

Percentage discount + packages only + no a la carte

Keep as percentage

Percentage discount + packages only + a la carte exists

Convert percentage to flat before invoice generation

## **4.7.4.6 Rationale**

If percentage discounts remain percentage-based when only packages participate in the discount calculation:

*   Invoice recalculations may become inconsistent
*   A La Carte items may incorrectly participate in discount calculations
*   Tax distribution may become inaccurate
*   Invoice editing behavior may become unpredictable

Converting the discount into a flat monetary amount before invoice generation ensures:

*   Mathematically accurate invoice totals
*   Correct taxable calculations
*   Predictable invoice editing behavior
*   Consistent proposal-to-invoice conversion logic

### 4.8 Payment Terms Configuration

#### **4.8.1 Payment Terms Modal Access**

*   The Payment Terms block displays an "Add Payment" button.
*   Clicking "Add Payment" opens the Payment Terms modal.
*   The modal overlays the builder and dims the background.
*   The modal can be closed by clicking the X icon, clicking outside, or pressing Escape.

#### **4.8.2 Payment Entry Configuration**

*   Each payment entry consists of a date configuration and a payment amount configuration.
*   The user can add multiple payment entries to create a payment schedule.
*   Payment entries are displayed as rows in the modal.
*   Each row shows the date type, date value, payment type, and amount.

#### **4.8.3 Date Types**

*   **Smart Date:** The user configures a number, unit (Days/Weeks/Months), and condition (before event date, after event date, after invoice sent).
*   **Invoice Date:** The payment is due on the date the invoice is sent to the client.
*   **Custom Date:** The user selects a specific date using a date picker.
*   **Event Date:** The payment is due on the project's primary event date.

#### **4.8.4 Payment Types**

*   **Custom Amount:** The user enters a fixed dollar amount for this payment.
*   **Percentage:** The user enters a percentage of the invoice total (e.g., 50%).
*   **Equal Payment:** The system automatically calculates equal portions for all Equal Payment entries.

#### **4.8.5 Equal Payment Recalculation Logic**

*   When a user adds a new payment entry with "Equal Payment" type, the system recalculates all Equal Payment entries.
*   Example: If there are 3 Equal Payment entries totaling $900, each is $300.
*   If the user adds a 4th Equal Payment entry, all 4 entries recalculate to $225 each.
*   Custom Amount and Percentage entries are not affected by Equal Payment recalculation.
*   The recalculation occurs immediately upon adding or removing Equal Payment entries.

**\*\*Conversion Between Payment Types (Equal → Custom):\*\***

*   \* When the user changes one of the Equal Payment entries to a Custom Amount, the remaining Equal Payment entries automatically recalculate to split the remaining balance equally.
*   \* Example: On a $900 invoice with 3 Equal Payment entries ($300 each), if one entry is changed to a Custom Amount of $400, the remaining two Equal Payment entries recalculate to $250 each ($900 − $400 = $500, split equally).

**\*\*Recalculation on Invoice Total Change:\*\***

*   \* When the invoice total changes (e.g., a line item is edited, added, or deleted after payment terms are configured):
    *   \* Custom Amount entries remain fixed at their original values.
    *   \* Percentage entries recalculate based on the new invoice total.
    *   \* Equal Payment entries recalculate based on the remaining balance after Custom Amount and Percentage entries are accounted for.
*   \* If the fixed Custom Amount entries now exceed the new invoice total, an inline validation error is shown on the Payment Terms section.

**\*\*Balance Match Rule:\*\***

\* The payment schedule total must always match the invoice grand total, including taxes and discounts.

\* If the totals do not match, an inline error is displayed and the template cannot be published until the totals are reconciled.

\* The same validation applies when the resulting invoice is shared from a project; the smart file (invoice) cannot be shared with the client until the payment schedule total matches the invoice grand total.

#### **4.8.6 Payment Terms Validation**

*   The sum of all payment entry amounts must equal the invoice Total Amount.
*   For Percentage-based schedules, all percentages must sum to exactly 100%.
*   If the payment terms do not equal the invoice total, a validation error is displayed.
*   The validation is performed in real-time as the user configures payment entries.
*   The validation is also performed when attempting to publish the template.

#### **4.8.7 Apply Preset Functionality**

*   The "Apply Preset" button is displayed in the Payment Terms block header.
*   Clicking "Apply Preset" opens a dropdown showing available payment schedule presets.
*   Only Published payment schedule templates are displayed in the dropdown.
*   Selecting a preset replaces the current payment term configuration.
*   The applied preset is an independent copy; changes do not affect the original preset.
*   After applying, the user can modify the payment terms as needed.
*   If no Published payment schedule presets exist in the system, no dropdown is opened. Instead, a toast notification is displayed: "No presets available."

#### **4.8.8 Save as Preset Functionality**

*   The "Save as Preset" button is displayed in the Payment Terms block header.
*   Clicking "Save as Preset" opens a modal prompting for a preset name.
*   The user enters a name and clicks "Save" to create the preset.
*   The system creates a new Published payment schedule template.
*   A success message confirms the preset was saved.
*   The new preset becomes available in the "Apply Preset" dropdown.

### 4.9 Colors Tab

#### **4.9.1 Color Settings Display**

*   \* Clicking the Colors tab in the left sidebar displays color configuration options.
*   \* The Colors tab is organized into the following grouped sections:
*   \* \*\*BUTTON:\*\* Button Text, Button Color
*   \* \*\*BACKGROUND:\*\* Background Color
*   \* \*\*BRAND:\*\* "Use Brand Colors" checkbox
*   \* The BODY section (Text Color) is \*\*not\*\* displayed in the Template Builder.
*   \* Each color setting displays a color swatch preview and the hex code value.

#### **4.9.2 Color Input Methods**

*   Clicking on a color swatch opens a color picker interface.
*   The color picker allows selection from a color spectrum.
*   The color picker includes a hex code input field for precise color entry.
*   The user can enter a hex code directly (e.g., "#FF5500") without using the picker.
*   Preset color swatches may be available for quick selection.

#### **4.9.3 Use Brand Colors Checkbox**

*   A "Use Brand Colors" checkbox is displayed at the top of the Colors tab.
*   The brand colors are sourced from the brand that was selected during template creation (in the Create Invoice Template modal — see FRD #1).
*   Checking this box auto-fills all color fields with the brand's configured colors.
*   After auto-fill, the color fields remain editable.
*   If the user modifies any color after checking "Use Brand Colors," the checkbox is automatically unchecked.
*   This indicates that the template no longer uses the exact brand colors.

#### **4.9.4 Real-Time Preview**

*   Color changes are reflected in the builder canvas in real-time.
*   The user can see immediately how the color changes affect the invoice appearance.
*   No save action is required to preview color changes.

### 4.10 Fonts Tab

#### **4.10.1 Font Settings Display**

*   Clicking the Fonts tab in the left sidebar displays font configuration options.
*   Two settings are displayed: Font Family and Font Size.

#### **4.10.2 Font Family Selection**

*   The Font Family setting is a dropdown selector.
*   Available font families include: Inter (default), Arial, Helvetica, Times New Roman, Georgia, Verdana, Trebuchet MS, Courier New, Palatino Linotype, and Garamond.
*   Selecting a font family updates the invoice text throughout the template.
*   The font change is applied to all text elements in the invoice.

#### **4.10.3 Font Size Selection**

*   The Font Size setting offers three options: Small, Medium, and Large.
*   The default font size is Medium.
*   Font size affects the overall text scaling of the invoice.
*   Headings and body text scale proportionally based on the selected size.

#### **4.10.4 Real-Time Preview**

*   Font changes are reflected in the builder canvas in real-time.
*   The user can see immediately how font changes affect the invoice appearance.
*   No save action is required to preview font changes.

###

### 4.11 Settings Tab

#### **4.11.1 Settings Display**

*   Clicking the Settings tab (gear icon) in the left sidebar displays configuration options.
*   The primary setting displayed is Set Expiration Date.

#### **4.11.2 File Expiration Toggle**

*   The "Turn on file expiration" toggle controls whether the invoice has a validity period.
*   When OFF (default), the invoice remains accessible indefinitely after sending.
*   When ON, additional expiration configuration fields are revealed.

#### **4.11.3 Expiration Duration Configuration**

*   The "Expires in" field allows users to set the validity period.
*   Two input components are displayed: a numeric input field and a duration unit dropdown.
*   Default value is 10 days.
*   Duration units available: Days (default) and Weeks
*   Helper text displays: "after sending to client" to clarify when the countdown begins.
*   The expiration duration is stored as a template setting (a rule), not as a fixed expiration date.
*   \* When an invoice is created and sent from this template, the system calculates the actual expiration date as: \`\[invoice send date + configured duration\]\`.
*   \* Each invoice generated from the template captures its own expiration date based on its individual send date; the template stores only the rule.

#### **4.11.4 Expiration Behavior — Agency Side**

*   Expired invoices remain viewable in the system for record-keeping.
*   An "Expired" status tag is displayed at the top of the document (e.g., "Expired on \[Date\]").
*   No payment actions are available on expired invoices — only a "Go Back" button for navigation.

### 4.12 Preview Functionality

#### **4.12.1 Opening Preview**

*   The user clicks the "Preview" button in the header bar.
*   The system generates a preview of the invoice template.
*   The preview displays the template with sample/placeholder data.
*   The preview opens on the same page, replacing or overlaying the builder canvas.

#### **4.12.2 Preview Display**

*   The preview shows the invoice exactly as it will appear when generated.
*   Sample data is used for client information, dates, and other dynamic fields.
*   All styling (colors, fonts) is applied in the preview.
*   All blocks and line items are displayed in their configured order.
*   The payment terms are displayed as configured.

#### **4.12.3 Closing Preview**

*   A "Close Preview" or "Back to Editor" button is displayed in the preview.
*   Clicking the button returns the user to the builder canvas.
*   No changes are lost when entering or exiting preview mode.

### 4.13 Save and Publish Actions

#### **4.13.1 Save Behaviour**

*   \* The "Save as Template" button has been removed from the header bar.
*   \* The Template Builder uses \*\*auto-save\*\*. There is no manual draft-save action exposed in the UI.
*   \* All changes made in the builder (content edits, line item changes, payment terms, styling, settings) are automatically saved as the user makes them.
*   \* For Draft templates, auto-save commits changes directly to the template record; the template remains in Draft status until Publish is clicked.
*   \* For already-Published templates, auto-save captures changes as unpublished edits without overwriting the live Published version. The user must click "Publish Changes" via the alert banner (Section 4.13.6) to make these edits live.
*   \* No success toast is displayed for individual auto-save events.

#### **4.13.2 Publish Button**

*   The "Publish" button is displayed in the header bar next to "Save as Template."
*   The Publish button is always visible regardless of template status.
*   Clicking "Publish" triggers validation of the template configuration.
*   If validation passes, the system saves any unsaved changes and sets the status to Published.
*   If validation fails, the system displays an error message and does not publish.

#### **4.13.3 Publish Validation Rules**

*   All 5 mandatory blocks (Logo, Title, Contact Information, Items, Payment Terms) must be present.
*   At least one line item must be configured in the Items block.
*   Each line item must have a valid Item Name and Price.
*   Payment terms must be configured with at least one payment entry.
*   The sum of payment terms must equal the invoice Total Amount.
*   For percentage-based payment terms, percentages must sum to exactly 100%.

#### **4.13.4 Publish Success**

*   Upon successful publish, the status badge updates from "Draft" to "Published" (green).
*   A success toast message displays: "Template published successfully."
*   The template is now available for selection when creating invoices in projects.

#### **4.13.5 Publish Failure**

*   If validation fails, a toast message displays: "Cannot publish: \[specific reason\]."
*   The specific reason indicates what needs to be corrected (e.g., "Please add at least one line item").
*   The template remains in Draft status.
*   The user must correct the issue and try publishing again.

#### **4.13.6 Re-Publishing Unsaved Changes (Already-Published Templates)**

*   When a **Published** template contains unpublished changes (i.e., modifications have been made after the last publish), the system displays an alert banner at the top of the **Template Builder** canvas area.
*   The banner includes:
    *   A yellow warning icon
    *   The message:  
        **"Unpublished changes detected. Publish to update with your latest edits."**
*   A **"Publish Changes"** button is displayed on the right side of the banner.
*   Clicking **"Publish Changes"** triggers the standard publish validation and workflow defined in **Sections 4.13.2** and **4.13.3**.
*   The banner is hidden when:
    *   The template is in **Draft** status (never published), or
    *   No changes exist since the last publish
*   The banner is not displayed in **view-only mode** (Project Manager role).

### 4.14 Exit and Unsaved Changes

#### **4.14.1 Exit via Back Button**

*   \* The user clicks the Back arrow (←) button in the header to exit the builder.
*   \* For Draft templates: all changes are auto-saved, so the user navigates directly to the Template Listing without any prompt.
*   For already-Published templates with unpublished edits, the edits remain captured and the unpublished-changes banner (Section 4.13.6) will reappear when the user opens the template again.

**\*\*4.14.2 Browser Navigation\*\***

\* For all navigation attempts (Back button, close tab, browser back/forward, refresh), no custom warning is shown.

\* All edits are persisted via auto-save before navigation completes.

\* Standard browser confirmations may still appear in rare cases (e.g., if an auto-save request is mid-flight at the moment of navigation), but these are browser-native and not controlled by the application.

### 4.15 Inline Template Name Editing

#### **4.15.1 Edit Trigger**

*   The template name is displayed in the header bar.
*   The user clicks on the template name to enter edit mode.
*   The name text becomes an editable input field.

#### **4.15.2 Edit Behavior**

*   The input field is pre-populated with the current template name.
*   The user can modify the name using standard text editing.
*   Pressing Enter or clicking outside the field confirms the change.
*   Pressing Escape cancels the edit and reverts to the original name.

#### **4.15.3 Validation**

*   The template name cannot be empty.
*   If the user clears the name and confirms, an error message displays.
*   The maximum length for template name is 100 characters.

### 4.16 Key Business Rules

#### **4.16.1 Mandatory Blocks Rule**

*   The 5 mandatory blocks cannot be deleted from the template.
*   The delete action is not available for mandatory blocks.
*   Mandatory blocks display a lock icon in the left sidebar block list.

#### **4.16.2 Unlimited Line Items Rule**

*   There is no limit to the number of line items that can be added.
*   Performance may be affected with very large numbers of items (50+), but the system does not enforce a limit.

#### **4.16.3 Payment Terms Balance Rule**

*   The sum of all payment term amounts must exactly equal the invoice Total Amount.
*   This is a blocking validation that prevents publishing if not satisfied.
*   The validation is displayed inline in the Payment Terms section and on publish attempt.

#### **4.16.4 Discount Before Tax Rule**

*   Discount is always applied to the Subtotal before tax is calculated.
*   Tax is calculated on the discounted amount (Subtotal - Discount).
*   This calculation order is fixed and cannot be changed by the user.

#### **4.16.5 Auto-Suggest Independence Rule**

*   When a user selects an item from auto-suggest, a copy of the data is made.
*   Changes to the line item in the template do not affect the original Package or À la Carte Item.
*   If the original item is later modified in the catalog, existing templates are not affected.

#### **4.16.6 Template Snapshot Rule**

*   When a template is published, subsequent edits do not affect invoices already created.
*   Each invoice captures a snapshot of the template at the time of invoice creation.
*   This ensures historical invoices remain consistent.

## **5\. Field Details & Validations**

### 5.1 Header Fields

**Field**

**Type**

**Required**

**Validation Rules**

**Max Length**

**Error Message**

Template Name

Text (inline edit)

✅

Cannot be empty

100

"Template name is required."

### 5.2 Line Item Fields

**Field**

**Type**

**Required**

**Validation Rules**

**Max Length**

**Error Message**

Item Name

Text with auto-suggest

✅

Cannot be empty

200

"Item name is required."

Description

Textarea

❌

Optional

1000

N/A

Qty

Number

✅

Must be positive number

N/A

"Quantity must be a positive number."

Unit

Text

❌

Optional

50

N/A

Price

Currency

✅

Must be non-negative

N/A

"Price cannot be negative."

Tax Toggle

Switch

❌

On/Off

N/A

N/A

### 5.3 Tax and Discount Fields

**Field**

**Type**

**Required**

**Validation Rules**

**Max Length**

**Error Message**

Tax Rate (%)

Number

❌

0-100

N/A

"Tax rate must be between 0 and 100."

Tax Rate (Fixed)

Currency

❌

Non-negative

N/A

"Tax amount cannot be negative."

Discount (%)

Number

❌

0-100

N/A

"Discount must be between 0 and 100%."

Discount (Fixed)

Currency

❌

Cannot exceed Subtotal

N/A

"Discount cannot exceed subtotal."

### 5.4 Payment Terms Fields

**Field**

**Type**

**Required**

**Validation Rules**

**Max Length**

**Error Message**

Date Type

Dropdown

✅

Smart/Invoice/Custom/Event

N/A

"Please select a date type."

Smart Date Number

Integer

If Smart

Positive integer

N/A

"Please enter a valid number."

Smart Date Unit

Dropdown

If Smart

Days/Weeks/Months

N/A

"Please select a unit."

Smart Date Condition

Dropdown

If Smart

before event/after event/after invoice

N/A

"Please select a condition."

Custom Date

Date Picker

If Custom

Valid future date

N/A

"Please select a valid date."

Payment Type

Toggle

✅

Custom/Percentage/Equal

N/A

"Please select a payment type."

Amount (Custom)

Currency

If Custom

Positive, ≤ remaining balance

N/A

"Amount exceeds remaining balance."

Percentage

Number

If %

0-100, total must = 100%

N/A

"Percentages must total 100%."

### 5.5 Styling Fields

**Field**

**Type**

**Required**

**Validation Rules**

**Max Length**

**Error Message**

Text Color

Color Picker / Hex

❌

Valid hex code

7

"Invalid color code."

Button Text Color

Color Picker / Hex

❌

Valid hex code

7

"Invalid color code."

Button Color

Color Picker / Hex

❌

Valid hex code

7

"Invalid color code."

Background Color

Color Picker / Hex

❌

Valid hex code

7

"Invalid color code."

Font Family

Dropdown

❌

Must be from available list

N/A

N/A

Font Size

Radio/Toggle

❌

Small/Medium/Large

N/A

N/A

## **6\. Success Message Handling**

**Action**

**Success Message**

**Post-Action Behavior**

Publish

"Template published successfully."

Status badge updates to Published

Re-Publish (Already-Published with Changes)

"Template updated successfully."

Alert banner is hidden; status remains Published

Save as Preset

"Payment preset '\[Name\]' saved successfully."

Preset becomes available in the Apply Preset dropdown

Apply Preset

"Payment preset '\[Name\]' applied."

Existing payment terms are replaced with the selected preset

Template Name Updated

"Template name updated."

Template name updates in the header

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Display Method**

**User Action Required**

Empty Template Name

"Template name is required."

Inline error below field

Enter a valid template name

Empty Item Name

"Item name is required."

Inline error on line item

Enter item name or delete item

Invalid Quantity

"Quantity must be a positive number."

Inline error on field

Enter valid quantity

Negative Price

"Price cannot be negative."

Inline error on field

Enter valid price

No Line Items on Publish

"Please add at least one line item."

Toast notification (red)

Add at least one line item

Payment Terms ≠ Total

"Payment terms total must equal invoice total."

Inline error + Toast on publish

Adjust payment amounts

Percentage ≠ 100%

"Payment percentages must total 100%."

Inline error in Payment Terms

Adjust percentages

Discount > Subtotal

"Discount cannot exceed subtotal."

Inline error on discount field

Reduce discount amount

Auto-tax without Stripe

"Connect Stripe to enable auto-calculate tax."

Toast notification (red)

Connect Stripe or use manual tax

No Payment Terms on Publish

"Please configure payment terms."

Toast notification (red)

Add at least one payment entry

Invalid Hex Color

"Invalid color code."

Inline error below field

Enter valid hex code

No presets available

"No presets available."

Info toast notification

Configure presets in the Payment Schedules section

Custom Amounts exceed invoice total

"Fixed payment amounts exceed the invoice total. Please adjust amounts."

Inline error in the Payment Terms section

Reduce Custom Amount entries or increase the invoice total

Cannot share — payment schedule mismatch

"Payment schedule total does not match invoice total. Cannot share."

Red toast notification

Adjust payment terms so the payment schedule total matches the invoice grand total

## **8\. Edge Cases**

**Edge Case**

**Description**

**Expected System Behavior**

Zero Dollar Invoice

User creates an invoice with $0 total (promotional).

The system allows $0 invoices. Payment terms must also be $0 or configured accordingly.

50+ Line Items

User adds more than 50 line items.

The system allows unlimited items but may experience slower performance. No hard limit enforced.

Equal Payment Fractions

Equal Payment results in fractional amounts (e.g., $100/3).

The system rounds to 2 decimal places. The remainder is added to the last payment entry.

Delete Only Line Item

User deletes the only line item in the template.

The system allows deletion. Subtotal becomes $0. Template cannot be published without items.

Session Timeout

User's session expires while editing.

On next action, the system redirects to login. Unsaved changes are lost.

Concurrent Edit

Two users edit the same template simultaneously.

Last save wins. No conflict detection in Phase 1.

Auto-Suggest No Results

User types in Item Name but no matching items exist.

The dropdown shows "No results found." User can continue typing for manual entry.

Very Long Description

User enters a very long description for a line item.

The system truncates display but stores full text. Maximum 1000 characters.

Browser Refresh

User refreshes the page with unsaved changes.

All edits are auto-saved continuously, so refreshing reloads the latest saved state with no data loss. No browser confirmation is shown unless an auto-save is mid-flight at the moment of refresh.

Apply Preset to Non-Empty Terms

User applies a preset when payment terms already exist.

The preset replaces all existing payment terms without warning.

## **9\. Acceptance Criteria**

*   ✅ The Template Builder loads successfully after creating or editing a template.
*   \* ✅ The header displays Back button, template name (editable), status badge, Preview, and Publish buttons.
*   \* ✅ The three-dot (⋮) menu icon is not displayed in the header.
*   \* ✅ The "Save as Template" button is not displayed in the header.
*   \* ✅ Header layout (Back + name + status badge + Preview + Publish) is consistent across all template builders in the system.
*   \* ✅ Colors tab displays BUTTON, BACKGROUND, and BRAND sections; the BODY section (Text Color) is not shown.
*   \* ✅ "Use Brand Colors" pulls from the brand selected during template creation.
*   \* ✅ ISSUED ON and DUE DATE display as non-editable placeholder text in the builder.
*   \* ✅ Currency values display in \`\[symbol\]\[amount.00\]\` format throughout the builder.
*   \* ✅ Apply Preset shows "No presets available." toast when no published presets exist.
*   \* ✅ Tax calculation handles Flat and Percentage discounts per Section 4.7.2 formulas.
*   \* ✅ When Subtotal is $0, no tax proportional calculation is performed.
*   \* ✅ Proposal-to-invoice discount conversion follows the rules in Section 4.7.4.
*   \* ✅ Changing an Equal Payment to Custom Amount recalculates remaining Equal entries.
*   \* ✅ When invoice total changes, Custom stays fixed, Percentage recalculates, and Equal redistributes.
*   \* ✅ Payment schedule total must equal invoice grand total (incl. taxes/discounts) before publish or share.
*   \* ✅ Re-publishing an already-Published template shows a banner with "Publish Changes" button.
*   \* ✅ Project Manager opens the Template Builder in view-only mode with all edit actions disabled.
*   \* ✅ All edits, configuration, and publishing actions are restricted to Agency Owner and Admin only.
*   ✅ The Publish button is always visible regardless of template status.
*   ✅ The left sidebar displays four tabs: Invoice Structure, Colors, Fonts, and Settings.
*   ✅ The Invoice Structure tab lists all 5 mandatory blocks.
*   ✅ Mandatory blocks display a lock icon and cannot be deleted.
*   ✅ Clicking a block in the sidebar highlights the corresponding section in the builder.
*   ✅ Custom sections (Text, Image) can be added via the "+" button on hover.
*   ✅ Blocks can be reordered via drag-and-drop.
*   ✅ Line items can be added with auto-suggest from Packages and À la Carte Items.
*   ✅ Auto-suggest displays items in two sections: PACKAGES and A LA CARTE ITEMS.
*   ✅ Selecting from auto-suggest populates Item Name, Description, Qty, Unit, and Price.
*   ✅ Auto-populated fields can be overridden by the user.
*   ✅ Tax toggle on each line item controls tax calculation inclusion.
*   ✅ Discount can be added as percentage or fixed amount below Subtotal.
*   ✅ Total calculation follows: (Subtotal - Discount) + Tax.
*   ✅ Payment Terms modal opens when clicking Add Payment.
*   ✅ Payment Terms support 4 date types: Smart Date, Invoice Date, Custom Date, Event Date.
*   ✅ Payment Terms support 3 payment types: Custom Amount, Percentage, Equal Payment.
*   ✅ Equal Payment entries auto-recalculate when new Equal Payment is added.
*   ✅ Apply Preset loads a saved payment sche

dule configuration.
*   ✅ Save as Preset creates a new payment schedule template.
*   ✅ "Use Brand Colors" checkbox auto-fills colors from brand settings.
*   ✅ Modifying colors after "Use Brand Colors" unchecks the checkbox.
*   ✅ Fonts tab allows selection of Font Family and Font Size.
*   ✅ Color and font changes reflect in real-time on the builder canvas.
*   ✅ Preview button displays the template with sample data on the same page.
*   ✅ Publish validates the template and changes status to Published if valid.
*   ✅ Publish validation requires: mandatory blocks, at least one line item, valid payment terms.
*   ✅ Back button navigates directly to the Template Listing without any confirmation modal (auto-save handles persistence).
*   \* ✅ Auto-save persists all edits in the background without explicit user action.
*   \* ✅ No exit confirmation or unsaved-changes warning modal is shown under any circumstances.
*   \* ✅ For already-Published templates, unpublished edits persist across sessions and are surfaced via the alert banner (Section 4.13.6) on reopening.
*   ✅ Template name can be edited inline in the header.

## **10\. Dependencies**

**Dependency Type**

**Dependency Name**

**Description**

**Impact if Unavailable**

Internal Module

Template Listing (FRD #1)

Entry point for creating/editing templates.

User cannot access builder without listing.

Internal Module

Brand Module

Provides brand colors and logo for templates.

"Use Brand Colors" and default logo unavailable.

Internal Module

Packages Catalog

Provides Packages for line item auto-suggest.

Auto-suggest shows only À la Carte items.

Internal Module

À la Carte Services

Provides services for line item auto-suggest.

Auto-suggest shows only Packages.

Internal Module

Payment Schedule Templates (FRD #4)

Provides presets for Apply Preset functionality.

Apply Preset dropdown is empty.

External

Stripe

Required for Auto-Calculate Tax feature.

Auto-tax unavailable; manual tax only.

Database

Invoice\_Templates Table

Stores template configuration.

Cannot save or load templates.

Database

Packages Table

Stores package catalog.

No packages in auto-suggest.

Database

Services Table

Stores à la carte services.

No services in auto-suggest.

Frontend

Drag-and-Drop Library

Enables block and item reordering.

Reordering functionality unavailable.

Frontend

Color Picker Component

Enables color selection interface.

Must use hex code input only.

Frontend

Date Picker Component

Enables date selection for Custom Date.

Must type date manually.

## **11\. References**

**Figma Designs:**

*   2-create\_invoice.png - Template Builder main interface
*   2-create\_invoice-step1.png - Invoice Structure tab
*   2-create\_invoice-step2.png - Colors tab
*   2-create\_invoice-step3.png - Fonts tab
*   3-add\_edit\_line\_item.png - Line item configuration
*   3-pkg\_as\_line\_item.png - Auto-suggest with Packages
*   4-payment\_terms.png - Payment Terms modal
*   4-payment\_terms\_apply\_preset.png - Apply Preset dropdown
*   4-payment\_terms\_save\_preset.png - Save as Preset modal
*   5-tax\*.png - Tax configuration options
*   6-discount\*.png - Discount configuration
*   9-addsection.png - Add custom section

**Related FRDs:**

*   FRD #1: Invoice Template Listing
*   FRD #3: Edit Invoice Template with Conditions
*   FRD #4: Payment Schedule Template Listing & Create New Payment Schedule
*   FRD #5: Use Invoice in Project & Auto-Generation from Proposal

**Source Documents:**

*   Module Logic Explanation - Meeting Transcript (December 2025)
*   Client Meeting MOM - Invoice Module Discussion
*   Clarifying Questions & Answers Document
*   Additional Screenshots (Auto-suggest, Line Items, Totals)

☑️ 3. Edit Invoice Template with Conditions

# **FRD #3: Edit Invoice Template with Conditions**

**Version:** 1.0  
**Date:** December 10, 2025

## **1\. Module Overview**

**Purpose:  
**This document defines the rules, restrictions, and conditions that govern how invoice templates can be edited based on their status (Draft or Published), user permissions, and ownership. It ensures template integrity while allowing authorized modifications and provides guidance on safe editing practices for Published templates.

**Business Goals:**

*   Protect template consistency and integrity across the organization.
*   Enable controlled modifications by authorized users only.
*   Maintain audit trail for compliance and historical tracking.
*   Preserve existing invoice integrity through the Future-Effect Rule.
*   Provide clear guidance on safe editing workflows for Published templates.

**Scope:**

*   Draft template editing rules and restrictions.
*   Published template editing rules and restrictions.
*   Permission enforcement based on user role and ownership.
*   Future-Effect Rule implementation.
*   Warning messages and confirmations for Published template edits.
*   Version history (internal audit only).
*   Concurrent editing behavior.

## **2\. User Roles & Permissions**

**Permission**

**Admin**

**Manager**

**Team Member**

Edit Draft Template (any)

✅

✅

❌

Edit Published Template

✅

✅

❌

Re-Publish Edited Template

✅

✅

❌

View Version History (Internal)

❌

❌

❌

**Permission Notes:**

*   Only Agency Owner, Admin, and Project Manager roles have access to the Templates section.
*   Editor, Supervising Editor, Team Member, Contractor, and Client roles do not have access.
*   Only Agency Owner and Admin roles can edit templates (Draft or Published).
*   Project Manager has read-only access through view-only mode (defined in FRD #2).
*   Template ownership is stored internally but does not impact edit permissions.
*   Both Agency Owner and Admin can edit any template regardless of the original creator.
*   Version history is maintained internally for audit purposes only.
*   No UI exists to view, browse, or restore previous versions in any phase.
*   Deletion permissions are defined in FRD #1 (Template Listing).

## **3\. User Flow**

### 3.1 Edit Own Draft Template (Agency Owner / Admin)

*   \* The Agency Owner or Admin navigates to Templates → Invoices.
*   \* The user locates a Draft template in the Template Listing.
*   \* The user clicks the three-dot menu in the listing row and selects "Edit." (The three-dot menu in the listing is described in FRD #1; the Template Builder header itself does not have a three-dot menu.)
*   \* The system opens the Template Builder with the template loaded.
*   \* The user makes desired changes; all changes are auto-saved continuously (see FRD #2 Section 4.13.1).
*   \* The user can click "Publish" at any time to validate and publish the template.

### 3.2 Edit Published Template(Agency owner/Admin)

*   \* The Agency Owner or Admin navigates to Templates → Invoices.
*   \* The user locates a Published template in the Template Listing.
*   \* The user clicks the three-dot menu in the listing row and selects "Edit."
*   \* The system displays the "Edit Published Template" warning modal (see Section 4.3.1).
*   \* The user reads the warning and clicks "Continue" to proceed.
*   \* The system opens the Template Builder with the template loaded.
*   \* The user makes desired changes; changes are auto-saved as unpublished edits without overwriting the live Published version (see FRD #2 Section 4.13.1).
*   \* The Re-Publish Banner (FRD #2 Section 4.13.6) appears at the top of the canvas, indicating unpublished changes exist.
*   \* The user clicks "Publish Changes" in the banner to run publish validation and make the edits live.
*   \* On successful publish, the system updates the live template; existing invoices created before this publish are not affected (Future-Effect Rule).

### 3.3 View Template (project manager)

*   The Project Manager navigates to Templates → Invoices.
*   \* The Project Manager clicks on a template name in the listing.
*   \* The system opens the Template Builder in view-only mode (see FRD #2). All edit controls are disabled and the Publish action is not available. Preview remains available.

### 3.4 Attempt to Edit Without Permission

*   A user without edit permission (e.g., Project Manager, or any role outside the Templates-access list) does not see the "Edit" option in the listing's three-dot menu.
*   \* If such a user attempts to access an edit URL directly, the system returns an authorization error and redirects the user to the Template Listing.

## **4\. Functional Logic**

### 4.1 Edit Permission Determination

#### **4.1.1 Permission Check Logic**

*   \* When a user views the Template Listing, the system evaluates each template's edit permission.
*   \* The system checks the current user's role (Agency Owner, Admin, Project Manager, or other).
*   \* Template status (Draft or Published) does not affect edit permission visibility — both can be edited by Agency Owner and Admin.
*   \* Template ownership is recorded internally but does not affect edit permission.
*   \* Based on the user's role, the system determines whether to display the "Edit" action.

#### **4.1.2 Edit Permission Rules**

*   \* Agency Owner and Admin can edit any template (Draft or Published) regardless of who created it.
*   \* Project Manager cannot edit any template; the Edit action is hidden in the listing's three-dot menu. Clicking the template name opens it in view-only mode.
*   \* All other roles (Editor, Supervisor Editor, Team Member, Contractor, Client) have no access to the Templates section at all.

#### **4.1.3 API-Level Permission Enforcement**

*   \* If a user attempts to edit a template via direct API call without proper permissions, the system returns a 403 Forbidden error.
*   \* The error response includes the message: "You do not have permission to edit this template."

### 4.2 Draft Template Editing

#### **4.2.1 Full Edit Capability**

*   \* Agency Owner and Admin have unrestricted access to modify all aspects of a Draft template.
*   \* All mandatory blocks (Logo, Title, Contact Information, Items, Payment Terms) can be modified.
*   \* All custom sections (Text, Image) can be added, modified, or deleted.
*   \* All line items can be added, modified, reordered, or deleted.
*   \* All payment terms can be added, modified, or deleted.
*   \* All styling options (Colors, Fonts, Settings) can be changed.
*   \* The template name can be modified.

#### **4.2.2 Save Behavior for Draft**

*   \* All edits are auto-saved continuously (see FRD #2 Section 4.13.1). There is no manual "Save as Template" action.
*   \* The template remains in Draft status throughout editing until Publish is clicked.
*   \* The Modified Date is updated to the current timestamp with each auto-save.
*   \* The internal version snapshot is updated on each auto-save event; the publicly tracked version number increments only on Publish (see Section 4.5).

#### **4.2.3 Publish Behavior from Draft**

*   \* Clicking "Publish" triggers validation of the template configuration (validation rules defined in FRD #2 Section 4.13.3).
*   \* If validation passes, the template status changes from Draft to Published.
*   \* The template becomes available for selection when creating invoices in projects (FRD #5).
*   \* A success message displays: "Template published successfully."
*   \* The status badge updates from gray "Draft" to green "Published."
*   \* The version number increments on successful publish.

### 4.3 Published Template Editing

#### **4.3.1 Edit Warning Modal**

*   When an Admin or Manager clicks "Edit" on a Published template, the system displays a warning modal.
*   The modal title displays: "Edit Published Template."
*   The modal message displays: "This template has been published and may be in use. Any changes you make will only affect invoices created after this update. Existing invoices will not be affected."
*   The modal includes two buttons: "Cancel" and "Continue."
*   Clicking "Cancel" closes the modal and returns to the Template Listing.
*   Clicking "Continue" proceeds to open the Template Builder.

#### **4.3.2 Full Edit Capability**

*   Once in the Template Builder, Admin and Manager have unrestricted access to modify all aspects of the Published template.
*   All mandatory blocks can be modified.
*   All custom sections can be added, modified, or deleted.
*   All line items can be added, modified, reordered, or deleted.
*   All payment terms can be added, modified, or deleted.
*   All styling options can be changed.
*   The template name can be modified.
*   There are no fields or sections that are locked or restricted from editing.

#### **4.3.3 Save Behavior for Published**

*   All edits are auto-saved continuously, but for an already-Published template, edits are captured as \*\*unpublished edits\*\* that do not overwrite the live Published version (see FRD #2 Section 4.13.1).
*   \* The live Published version continues to be the version used for any new invoices created during the editing session.
*   \* The Modified Date for the unpublished-edit state is updated to the current timestamp on each auto-save.
*   \* The "Times Used" counter is unaffected by editing and continues to reflect actual usage.

#### **4.3.4 Re-Publish Behavior**

*   When unpublished edits exist on a Published template, the Re-Publish Banner is displayed at the top of the canvas (see FRD #2 Section 4.13.6).
*   \* The banner reads: "Unpublished changes detected. Publish to update with your latest edits." with a "Publish Changes" button.
*   \* Clicking "Publish Changes" triggers the standard publish validation (FRD #2 Section 4.13.3).
*   \* If validation passes, the system commits the unpublished edits as the new live Published version. The status remains Published.
*   \* On successful re-publish, the version number increments (see Section 4.5).
*   \* A success message displays: "Template updated successfully."
*   \* The Re-Publish Banner is hidden after a successful publish until new edits are made.

### 4.4 Future-Effect Rule

#### **4.4.1 Rule Definition**

*   When a Published template is edited and saved, the changes apply only to invoices created after the save.
*   Invoices that were created before the edit retain the template configuration that existed at the time of their creation.
*   This is called the "Future-Effect Rule" and ensures historical invoice consistency.

#### **4.4.2 Technical Implementation**

*   When an invoice is created using a template, the system captures a complete snapshot of the template configuration.
*   The snapshot includes all block content, line items, payment terms, and styling settings.
*   The snapshot is stored with the invoice record, independent of the template.
*   Subsequent template modifications do not trigger updates to existing invoice snapshots.

#### **4.4.3 User Communication**

*   The warning modal displayed before editing a Published template explains this behavior.
*   Users are informed that "existing invoices will not be affected."
*   This ensures users understand the impact of their edits before proceeding.

### 4.5 Version History

#### **4.5.1 Internal Version Tracking**

*   \* The system maintains an internal version number for each template.
*   \* Version 1 is the initial state created when the template record is first created via the Create modal (FRD #1). The first save in the Template Builder creates Version 2.
*   \* The version number increments on each successful Publish action (both initial Publish and Re-Publish of an edited Published template).
*   \* Auto-save events update the working snapshot but do not increment the version number.

#### **4.5.2 Version Snapshot Storage**

*   \* Each time the version number increments (i.e., on Publish), the system stores a complete snapshot of the template configuration.
*   \* The snapshot includes all block content, line items, payment terms, styling, and settings.
*   \* The snapshot is associated with the version number, timestamp, and the user who triggered the publish.

#### **4.5.3 Audit Purpose Only**

*   Version history is maintained for internal audit and compliance purposes.
*   Version history is not accessible through the user interface in Phase 1.
*   Users cannot view previous versions of a template.
*   Users cannot restore a template to a previous version.
*   Future phases may introduce version history UI features.

#### **4.5.4 Retention Policy**

*   Version history is retained indefinitely for compliance purposes.
*   The system does not automatically purge old versions.
*   Storage considerations may be addressed in future phases.

### 4.6 Concurrent Editing

#### **4.6.1 No Locking Mechanism**

*   The system does not implement template locking in Phase 1.
*   Multiple users can open the same template for editing simultaneously.
*   The system does not display warnings about other users editing the template.

#### **4.6.2 Last Save Wins**

*   If two users edit the same template simultaneously, the last save overwrites previous changes.
*   User A opens template → User B opens template → User A saves → User B saves → User B's changes persist.
*   User A's changes are lost in this scenario.
*   No merge or conflict resolution is attempted.

#### **4.6.3 Recommended Practice**

*   Organizations should establish internal processes to coordinate template editing.
*   Only one user should edit a template at a time to avoid data loss.
*   Communication between team members is recommended before editing shared templates.

### 4.7 Template Ownership

#### **4.7.1 Ownership Assignment**

*   When a user creates a new template, they become the owner of that template.
*   Ownership is recorded in the template record with the user's ID.
*   Ownership is permanent and cannot be transferred to another user.

#### **4.7.2 Ownership and Permissions**

*   \* Ownership does \*\*not\*\* affect edit permissions. Both Agency Owner and Admin can edit any template regardless of who created it.
*   \* Ownership is used for internal audit and reporting only.

#### **4.7.3 Ownership Display**

*   The template owner is not displayed in the Template Listing UI in Phase 1.
*   Ownership information is stored in the database but not exposed to users.
*   Future phases may introduce an "Owner" column in the listing.

### 4.8 Key Business Rules

**\*\*4.8.1 Edit Restriction Rule\*\***

\* Only Agency Owner and Admin can edit templates (Draft or Published).

\* Project Manager has view-only access.

\* All other roles have no access to the Templates section.

\* This restriction ensures organization-wide templates are controlled by senior roles only.

**\*\*4.8.2 Ownership Permanence Rule\*\***

\* Template ownership is assigned at creation and cannot be changed or transferred.

\* Ownership is recorded internally for audit purposes and does not affect edit rights.

\* If the original creator leaves the organization, Agency Owner and Admin retain full edit access.

**\*\*4.8.3 Future-Effect Rule\*\***

\* Edits to Published templates affect only invoices created after the edits are published live (via the Re-Publish Banner).

\* Auto-saved edits on a Published template do not affect live invoice creation until they are explicitly published.

\* Existing invoices snapshot the template at the time of their creation and are protected from any subsequent template modifications.

\* This is a core principle of the invoice template system.

**\*\*4.8.4 Last Save Wins Rule\*\***

\* In concurrent editing scenarios between two authorized users, the most recent auto-save overwrites prior changes.

\* No conflict detection or resolution is implemented in Phase 1.

**\*\*4.8.5 Version History Audit Rule\*\***

\* Version snapshots are recorded internally on each Publish action for audit purposes.

\* Version history is never exposed in the UI in any phase.

\* No version restoration capability exists.

## **5\. Field Details & Validations**

**Field**

**Type**

**Required**

**Validation Rules**

**Error Message**

Template Name

Text

✅

Cannot be empty; max 100 characters

"Template name is required."

All Other Fields

Various

Various

Same validations as FRD #2

See FRD #2

**Note:** Field validations for the Template Builder are defined in FRD #2. This document focuses on permission and condition rules for editing.

## **6\. Success Message Handling**

**Action**

**Success Message**

**Display Method**

**Post-Action Behavior**

Publish Draft Template

"Template published successfully."

Green toast notification (top-right)

Status badge updates to Published

Re-Publish Edited Template

"Template updated successfully."

Green toast notification (top-right)

Warning banner is hidden; status remains Published

Auto-Save (background)

None (no toast displayed for individual auto-saves)

Silent

See FRD #2, Section 4.13.1

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Display Method**

**User Action Required**

Edit Without Permission (UI)

Action not displayed

N/A (action hidden in listing three-dot menu)

None; user cannot initiate the action

Edit Without Permission (API)

"You do not have permission to edit this template."

Red toast notification

Contact the Agency Owner or Admin

Concurrent Edit Data Loss

No warning displayed (last save wins)

N/A

Coordinate edits with team members

Template Not Found

"Template no longer exists."

Red toast notification

Return to the Template Listing

##

##

## **8\. Edge Cases**

**Edge Case**

**Description**

**Expected System Behavior**

Admin edits template created by another Admin

An Admin edits a template originally created by another Admin.

Changes are saved successfully. The original creator record remains unchanged. Both users retain equal edit rights.

Concurrent edit conflict

Two Admins edit the same template simultaneously and auto-saves overlap.

Last auto-save wins per field. No warning is displayed. The final template state reflects the most recent auto-save for each field.

Delete template being edited

Admin A deletes a template while Admin B still has it open in the builder.

On Admin B’s next auto-save attempt, the system displays: "Template no longer exists. Your changes could not be saved." The user is redirected to the Template Listing.

Original creator leaves organization

The user who originally created the template is deactivated or removed.

The template remains accessible. Agency Owner and Admin retain full edit permissions. The internal creator record remains unchanged.

Edit template during invoice creation

An Admin edits a Published template while another user is creating an invoice using it.

The invoice captures a snapshot of the template at the time invoice creation begins. Subsequent template edits do not affect that in-progress or completed invoice (Future-Effect Rule). Auto-saved unpublished edits remain invisible until re-published.

Session timeout during edit

The user session expires while editing a template.

On the next interaction, the user is redirected to the login page. Auto-saved edits up to the moment of expiry remain preserved.

Cancel from pre-entry warning modal

Admin clicks Cancel on the "Edit Published Template" warning modal.

The modal closes and the user returns to the Template Listing. No editing session begins, and the template remains unchanged.

Re-publish with failed validation

Admin clicks "Publish Changes" but validation fails (e.g., payment schedule totals no longer match after edits).

Standard publish validation errors are displayed. The currently Published version remains unchanged. Unpublished edits remain auto-saved, and the warning banner stays visible.

## **9\. Acceptance Criteria**

*   ✅ Only Agency Owner and Admin can edit templates (Draft or Published).
*   \* ✅ Project Manager opens templates in view-only mode (no edit capability).
*   \* ✅ Editor, Supervisor Editor, Team Member, Contractor, and Client roles have no access to the Templates section.
*   \* ✅ Template ownership does not affect edit permissions; both Owner and Admin can edit any template.
*   \* ✅ Pre-entry warning modal is displayed when Agency Owner or Admin clicks "Edit" on a Published template.
*   \* ✅ The pre-entry modal explains that changes affect future invoices only.
*   \* ✅ Clicking "Cancel" on the pre-entry modal returns to the Template Listing without opening the builder.
*   \* ✅ Clicking "Continue" on the pre-entry modal opens the Template Builder.
*   \* ✅ The pre-entry modal is shown only once per edit session and is not re-displayed inside the builder.
*   \* ✅ All aspects of a Published template can be modified once inside the builder (no locked fields).
*   \* ✅ Edits to a Published template are auto-saved as unpublished edits and do not affect the live Published version.
*   \* ✅ The Re-Publish Banner (FRD #2 Section 4.13.6) appears when unpublished edits exist on a Published template.
*   \* ✅ Clicking "Publish Changes" in the banner runs validation and makes edits live on success.
*   \* ✅ The "Times Used" counter is unaffected by editing.
*   \* ✅ Existing invoices are not affected by template edits (Future-Effect Rule); each invoice retains its snapshot at the time of creation.
*   \* ✅ Version number increments only on Publish (both initial publish and re-publish).
*   \* ✅ Version 1 is the initial creation state; Version 2 is the first save in the builder.
*   \* ✅ Version history is stored internally for audit purposes only; no UI exposure in any phase.
*   \* ✅ No version restoration capability exists.
*   \* ✅ Concurrent edits follow "last save wins" behavior without warnings.
*   \* ✅ Template ownership is fixed at creation and cannot be transferred.
*   \* ✅ API enforces the same permission rules as the UI.

## **10\. Dependencies**

**Dependency Type**

**Dependency Name**

**Description**

**Impact if Unavailable**

**Dependency Type**

**Dependency**

**Purpose**

**Failure Impact**

Internal Module

Template Listing (FRD #1)

Provides the entry point for template editing via the three-dot menu in the listing.

Users cannot access templates for editing.

Internal Module

Template Builder (FRD #2)

Provides the interface for editing template content, including Auto-Save and Re-Publish Banner functionality.

Users cannot modify template content; re-publish banner functionality becomes unavailable.

Internal Module

User & Permissions Module

Provides role information (Agency Owner, Admin, Project Manager).

Edit permissions cannot be enforced.

Internal Module

Invoice Module (FRD #5)

Tracks **Times Used** and captures template snapshots during invoice creation.

The **Future-Effect Rule** cannot be enforced.

Database

Invoice\_Templates Table

Stores template data, creator ID, and current template state.

Templates cannot be saved or loaded.

Database

Template\_Versions Table

Stores template version snapshots for internal audit purposes.

No audit trail exists for template changes.

Database

Users Table

Stores user role information.

User edit permissions cannot be determined.

## **11\. References**

**Figma Designs:**

*   Template Listing actions menu
*   Template Builder interface (see FRD #2)

☑️ 4. Payment Schedule

# **FRD #4: Payment Schedule Template Listing & Create New Payment Schedule**

**Version:** 1.0  
**Date:** December 10, 2025

## **1\. Module Overview**

**Purpose:  
**The Payment Schedule Template module enables users to create, manage, and reuse payment schedule configurations (presets) across invoice templates. Users can define payment schedules with multiple payment entries, each specifying when and how much should be paid. These presets streamline invoice creation by allowing quick application of common payment structures.

**Business Goals:**

*   Reduce repetitive configuration of payment terms across invoices.
*   Ensure consistency in payment schedule structures across the organization.
*   Enable quick selection of pre-configured payment schedules when creating invoices.
*   Track usage of payment presets for insights into common payment patterns.

**Scope:**

*   Payment Schedule Template listing page with search and pagination.
*   Creating new payment schedule templates via listing page and Invoice Builder.
*   Payment entry configuration with date types and payment types.
*   Edit, Duplicate, and Delete actions on payment schedule templates.
*   Apply Preset functionality within Invoice Template Builder.
*   Save as Preset functionality within Invoice Template Builder.
*   Times Used tracking for each preset.

**Out of Scope:**

*   Invoice Template listing and management (covered in FRD #1).
*   Invoice Template Builder interface (covered in FRD #2).
*   Payment processing and collection (covered in separate module).
*   Stripe integration for payment collection.

## **2\. User Roles & Permissions**

**Permission**

**Agency Owner**

**Admin**

**Project Manager**

View Payment Schedule Listing

✅

✅

✅

Create Payment Schedule

✅

✅

❌

Edit Payment Schedule

✅

✅

❌

Duplicate Payment Schedule

✅

✅

❌

Delete Payment Schedule

✅

✅

❌

Apply Preset in Invoice Builder

✅

✅

❌

Save as Preset from Invoice Builder

✅

✅

❌

**Permission Notes:**

*   Only Agency Owner, Admin, and Project Manager roles have access to the Templates section.
*   \* Editor, Supervisor Editor, Team Member, Contractor, and Client roles have no access.
*   \* Only Agency Owner and Admin can create, edit, duplicate, or delete payment schedule presets.
*   \* Project Manager has view-only access to the Payment Schedules listing. The "+ Create Payment Schedule" button and the three-dot actions menu are hidden for Project Manager.
*   \* Project Manager cannot apply or save presets from the Invoice Builder (since editing the Invoice Builder is also restricted to Agency Owner / Admin per FRD #2).
*   \* Template ownership is recorded internally but does not affect edit or delete permissions. Both Agency Owner and Admin can edit/delete any preset regardless of who created it.

## **3\. User Flow**

### 3.1 Access Payment Schedule Listing

*   The user navigates to Templates → Invoices in the left sidebar.
*   The system displays the Invoices page with two tabs: "Invoices" and "Payment Schedules."
*   The user clicks the "Payment Schedules" tab.
*   The system displays the Payment Schedule Template listing with all available presets.

### 3.2 Create Payment Schedule from Listing Page

*   The user clicks the "+ Create Payment Schedule" button in the top right corner.
*   The system opens the Add Payment modal.
*   The user configures the first payment entry with date type and payment type.
*   The user clicks "Save" to add the payment entry.
*   The user can add additional payment entries by clicking "+ Add Payment."
*   Once all payment entries are configured, the user clicks "Save as Preset."
*   The system opens the Save Payment Preset modal.
*   The user enters a preset name and clicks "Save."
*   The system creates the payment schedule template and displays it in the listing.

### 3.3 Create Payment Schedule from Invoice Builder (Save as Preset)

*   The user is configuring payment terms within the Invoice Template Builder (FRD #2).
*   The user adds one or more payment entries using the "Add Payment" button.
*   The user clicks the "Save as Preset" button in the Payment Terms block header.
*   The system opens the Save Payment Preset modal.
*   The user enters a preset name and clicks "Save."
*   The system creates a new payment schedule template.
*   A success message confirms the preset was saved.
*   The new preset is immediately available in the "Apply Preset" dropdown.

### 3.4 Apply Preset in Invoice Builder

*   The user is configuring an invoice template in the Template Builder.
*   The user clicks the "Apply Preset" button in the Payment Terms block header.
*   The system displays a dropdown with all available payment schedule presets.
*   The user selects a preset from the dropdown.
*   The system replaces the current payment terms configuration with the selected preset.
*   The user can modify the applied payment terms as needed.

### 3.5 Edit Payment Schedule

*   The user clicks the three-dot menu (⋮) on a payment schedule row.
*   The user selects "Edit" from the menu.
*   The system opens the payment schedule configuration modal with existing entries.
*   The user modifies payment entries as needed.
*   The user clicks "Save" to save changes.
*   The system updates the payment schedule template.

### 3.6 Duplicate Payment Schedule

*   The user clicks the three-dot menu (⋮) on a payment schedule row.
*   The user selects "Duplicate" from the menu.
*   The system creates a copy of the payment schedule with "(Copy)" suffix appended to the name.
*   The new preset appears in the listing with Times Used set to 0.
*   A success message confirms the duplication.

### 3.7 Delete Payment Schedule

*   The user clicks the three-dot menu (⋮) on a payment schedule row.
*   The user selects "Delete" from the menu.
*   The system displays a confirmation modal.
*   The user clicks "Delete" to confirm.
*   The system removes the payment schedule template from the listing.
*   A success message confirms the deletion.

### 3.8 Access Listing via Manage Presets

*   The user is in the Invoice Template Builder.
*   The user clicks the "Apply Preset" dropdown.
*   The user clicks "Manage Presets" at the bottom of the dropdown.
*   The system navigates to the Payment Schedules listing page.

## **4\. Functional Logic**

### 4.1 Listing Page Layout

#### **4.1.1 Page Structure**

*   The Payment Schedule listing is accessed via the "Payment Schedules" tab on the Invoices page.
*   The page header displays "Invoices" as the main title.
*   Two tabs are displayed below the header: "Invoices" (left) and "Payment Schedules" (right).
*   The "Payment Schedules" tab is highlighted in yellow/gold when active.
*   The "+ Create Payment Schedule" button is displayed in the top right corner of the page.
*   A search input field is displayed to the right of the tabs.

#### **4.1.2 Table Structure**

*   The listing displays payment schedule templates in a table format.
*   The table contains three columns: Preset Name, Times Used, and Actions.
*   The Preset Name column displays the name of the payment schedule template.
*   The Times Used column displays the count of invoices created using this preset.
*   The Actions column displays a three-dot menu icon (⋮) for each row.
*   Rows are displayed with alternating background colors for readability.

#### **4.1.3 Column Sorting**

*   The Preset Name column header includes a sort indicator.
*   Clicking on the Preset Name header toggles sorting between ascending and descending alphabetical order.
*   The Times Used column header includes a sort indicator.
*   Clicking on the Times Used header toggles sorting between ascending and descending numerical order.
*   The default sort order is by Preset Name ascending.

#### **4.1.4 Pagination**

*   Pagination controls are displayed at the bottom right of the table.
*   A "Rows per page" dropdown allows selection of 10, 25, or 50 rows per page.
*   The default rows per page is 10.
*   Page navigation displays the current range (e.g., "1-10 of 10").
*   Left and right arrow buttons allow navigation between pages.
*   The left arrow is disabled on the first page.
*   The right arrow is disabled on the last page.

### 4.2 Search Functionality

#### **4.2.1 Search Input**

*   A search input field is displayed to the right of the tab buttons.
*   The search field includes a magnifying glass icon.
*   Placeholder text displays "Search" or similar prompt.

#### **4.2.2 Search Behavior**

*   Search is triggered as the user types (real-time filtering).
*   The system searches against the Preset Name field only.
*   Search is case-insensitive.
*   Partial matches are supported (e.g., "50" matches "50/50 Split").
*   If no results match the search term, the table displays an empty state message.

#### **4.2.3 Search Results Display**

*   Matching results are displayed in the table immediately.
*   The pagination updates to reflect the filtered result count.
*   Clearing the search field restores the full listing.

### 4.3 Empty State

#### **4.3.1 No Payment Schedules Exist**

*   When no payment schedule templates exist in the system, the table area displays an empty state.
*   The empty state message displays: "No payment schedules yet."
*   A secondary message displays: "Create your first payment schedule to get started."
*   A "+ Create Payment Schedule" button is displayed below the message.

#### **4.3.2 No Search Results**

*   When a search returns no results, the table area displays an empty state.
*   The empty state message displays: "No results found."
*   A secondary message displays: "Try adjusting your search term."

### 4.4 Three-Dot Menu Actions

#### **4.4.1 Menu Display**

*   Each row displays a three-dot menu icon (⋮) in the Actions column.
*   Clicking the icon opens a dropdown menu with available actions.
*   The menu displays below and to the left of the icon.
*   Clicking outside the menu closes it.

#### **4.4.2 Available Actions**

*   The menu displays three actions: Edit, Duplicate, and Delete.
*   All three actions are available to Agency Owner and Admin for any payment schedule regardless of who created it.
*   Delete is available regardless of Times Used count (no usage-based protection — see Section 4.10.3 rationale).

### 4.5 Create Payment Schedule

#### **4.5.1 Create Button**

*   The "+ Create Payment Schedule" button is displayed in the top right corner of the page.
*   Clicking the button opens the payment schedule configuration interface.
*   The button is visible only to Agency Owner and Admin.

#### **4.5.2 Configuration Interface**

*   When creating a new payment schedule, the system displays the Add Payment modal.
*   The user configures one or more payment entries.
*   After configuring all entries, the user clicks "Save as Preset" to name and save the preset.
*   Alternatively, the user may see a combined interface that shows all entries and a name field.

#### **4.5.3 Preset Name Entry**

*   The Save Payment Preset modal displays when the user is ready to save.
*   The modal title displays: "Save Payment Preset."
*   A description displays: "Simplify your workflow by saving this payment combination for quick access later."
*   A "Preset Name" input field is displayed.
*   The field has a placeholder or is empty for new presets.
*   "Cancel" and "Save" buttons are displayed at the bottom right.

#### **4.5.4 Save Behavior**

*   Clicking "Save" validates the configuration.
*   If validation passes, the system creates the payment schedule template.
*   The template is immediately available in the listing and in Apply Preset dropdowns.
*   There is no Draft/Published status; templates are active immediately upon save.
*   A success message displays: "Payment schedule '\[Name\]' created successfully."

### 4.6 Add Payment Modal

#### **4.6.1 Modal Structure**

*   The modal title displays: "Add Payment."
*   The modal contains two main sections: Date Type and Payment Type.
*   "Cancel" and "Save" buttons are displayed at the bottom right.
*   Clicking outside the modal or pressing Escape closes it without saving.

#### **4.6.2 Date Type Section**

*   A "Date Type" label is displayed above a dropdown selector.
*   The dropdown contains four options: Smart Date, Invoice Date, Custom Date, and Event Date.
*   The default selection is "Smart Date."

#### **4.6.3 Smart Date Configuration**

*   When "Smart Date" is selected, additional configuration fields are displayed.
*   A number input field allows entry of a numeric value (e.g., 4).
*   A unit dropdown allows selection of: Days, Weeks, or Months.
*   A condition dropdown allows selection of: "before project date," "after project date," or "after invoice sent."
*   All three fields (number, unit, condition) are required when Smart Date is selected.

#### **4.6.4 Invoice Date Configuration**

*   When "Invoice Date" is selected, no additional fields are displayed.
*   The payment is due on the date the invoice is sent to the client.

#### **4.6.5 Custom Date Configuration**

*   When "Custom Date" is selected, a date picker field is displayed.
*   The user selects a specific date for the payment due date.
*   The date picker allows selection of any future date.
*   Custom Date in a payment schedule preset is stored as a \*\*fixed date\*\*, not as a rule. The same fixed date is used every time the preset is applied.
*   Past dates are allowed in the preset. When applied to an invoice template, the past date is carried through; the user can edit the date inline at invoice creation time before sending.

#### **4.6.6 Event Date Configuration**

*   When "Event Date" is selected, no additional fields are displayed.
*   The payment is due on the project's primary event date.

#### **4.6.7 Payment Type Section**

*   A "Payment Type" label is displayed above a toggle button group.
*   Three options are displayed: Custom, Percentage, and Equal Payment.
*   Only one option can be selected at a time.
*   The selected option is visually highlighted.

#### **4.6.8 Custom Amount Configuration**

*   When "Custom" is selected, a "Custom Amount" input field is displayed.
*   The field accepts numeric currency values.
*   The field placeholder displays "0" or is empty.

#### **4.6.9 Percentage Configuration**

*   When "Percentage" is selected, a "Percentage Amount" input field is displayed.
*   The field accepts numeric values representing a percentage.
*   The field placeholder displays "%0" or similar.
*   Helper text displays: "The percentage amount takes proportional part of your full payment."

#### **4.6.10 Equal Payment Configuration**

*   When "Equal Payment" is selected, no additional amount field is displayed.
*   The system automatically calculates equal portions among all Equal Payment entries.
*   The amount is determined when the preset is applied to an invoice with a known total.

### 4.7 Payment Entry Management

#### **4.7.1 Multiple Payment Entries**

*   A payment schedule template can contain one or more payment entries.
*   There is no maximum limit on the number of payment entries.
*   Each entry represents one payment in the overall payment schedule.

#### **4.7.2 Add Payment Link**

*   After adding the first payment entry, a "+ Add Payment" link is displayed.
*   Clicking the link opens the Add Payment modal for a new entry.
*   The new entry is added to the existing list of payment entries.

#### **4.7.3 Edit Payment Entry**

*   Existing payment entries can be edited by clicking on them or via an edit icon.
*   The Add Payment modal opens with the entry's current values pre-populated.
*   The user modifies values and clicks "Save" to update the entry.

#### **4.7.4 Delete Payment Entry**

*   Each payment entry displays a delete icon (trash) when editing.
*   Clicking the delete icon removes the entry from the schedule.
*   No confirmation is required for deleting individual entries.
*   The last entry can also be deleted, leaving the preset with zero entries.
*   A preset with zero entries cannot be saved — validation at save time requires at least one entry (Section 4.14.1). If the user attempts to save a preset with zero entries, the error "Please add at least one payment entry." is shown.

#### **4.7.5 Reorder Payment Entries**

*   Payment entries can be reordered via drag-and-drop if supported.
*   The order of entries determines the display order when the preset is applied.

### 4.8 Edit Payment Schedule

#### **4.8.1 Edit Trigger**

*   The user clicks "Edit" from the three-dot menu on a payment schedule row.
*   The system opens the payment schedule configuration interface.
*   All existing payment entries are displayed.

#### **4.8.2 Edit Capability**

*   The user can modify any aspect of the payment schedule.
*   Payment entries can be added, modified, or deleted.
*   The preset name can be changed.

#### **4.8.3 Save Edited Schedule**

*   Clicking "Save" validates the configuration.
*   If validation passes, the system updates the payment schedule template.
*   The updated template affects future uses; existing invoices are not modified.
*   A success message displays: "Payment schedule updated successfully."

### 4.9 Duplicate Payment Schedule

#### **4.9.1 Duplicate Behavior**

*   When the user clicks "Duplicate," the system creates a full copy of the payment schedule, including all payment entries and their configuration.
*   \* The duplicated preset name follows this naming convention:
*   \* First duplicate of "50/50 Split" → "Copy of 50/50 Split"
*   \* Second duplicate of "50/50 Split" → "Copy of 50/50 Split (1)"
*   \* Third duplicate → "Copy of 50/50 Split (2)", and so on
*   \* If "Copy of 50/50 Split (1)" is itself duplicated, the system creates "Copy of 50/50 Split (2)" by incrementing the highest existing number for that base name.
*   \* The new preset's Times Used count is set to 0.
*   \* The new preset's owner is the user who performed the duplication.
*   \* After the user clicks Duplicate, the action menu closes immediately and the Duplicate option is disabled until the API response is received, to prevent duplicate API calls from rapid double-clicks.
*   \* The duplicated preset appears in the listing immediately after creation; the user remains on the listing page.

#### **4.9.2 Duplicate Confirmation**

*   The duplication occurs immediately without a confirmation modal.
*   A success message displays: "Payment schedule duplicated successfully."
*   The new preset appears in the listing.

### 4.10 Delete Payment Schedule

#### **4.10.1 Delete Confirmation Modal**

*   When the user clicks "Delete," a confirmation modal is displayed.
*   The modal message displays: "Are you sure you want to delete '\[Preset Name\]'? This action cannot be undone."
*   "Cancel" and "Delete" buttons are displayed.

#### **4.10.2 Delete Behavior**

*   Clicking "Delete" permanently removes the payment schedule template.
*   The preset is removed from the listing and from Apply Preset dropdowns.
*   Existing invoices that used this preset are not affected.
*   A success message displays: "Payment schedule '\[Name\]' deleted successfully."

#### **4.10.3 No Usage Protection**

*   Payment schedules can be deleted regardless of the Times Used count.
*   Unlike Invoice Templates, there is no protection based on usage.
*   This is because the preset data is copied to the invoice at application time.

### 4.11 Apply Preset in Invoice Builder

#### **4.11.1 Apply Preset Button**

*   The "Apply Preset" button is displayed in the Payment Terms block header within the Invoice Template Builder.
*   Clicking the button opens a dropdown menu.

#### **4.11.2 Preset Dropdown**

*   The dropdown displays all available payment schedule templates.
*   Templates are listed by preset name.
*   All templates are shown regardless of owner (no filtering by ownership).
*   A "Manage Presets" link is displayed at the bottom of the dropdown.
*   \*\*Empty state:\*\* If no payment schedule presets exist in the system, the dropdown does not open. Instead, a toast notification is displayed: "No presets available."

#### **4.11.3 Select Preset**

*   Clicking on a preset name applies it to the current payment terms configuration.
*   The existing payment terms are replaced with the preset's configuration.
*   There is no confirmation prompt before replacement.
*   A success message displays: "Payment preset '\[Name\]' applied."

#### **4.11.4 Manage Presets Link**

*   Clicking "Manage Presets" opens the Payment Schedules listing page in a \*\*new browser tab\*\*.
*   \* The user's Invoice Builder session remains open and unchanged in the original tab.
*   \* All edits in the Invoice Builder are auto-saved (per FRD #2 Section 4.13.1), so no warning or save action is required before opening the new tab.
*   \* After managing presets in the new tab, the user can close it and return to the Invoice Builder. The Apply Preset dropdown reflects any changes (new presets, edits, deletes) on next open.

### 4.12 Save as Preset in Invoice Builder

#### **4.12.1 Save as Preset Button**

*   The "Save as Preset" button is displayed in the Payment Terms block header within the Invoice Template Builder.
*   The button is enabled when at least one payment entry exists.

#### **4.12.2 Save as Preset Modal**

*   Clicking the button opens the Save Payment Preset modal.
*   The modal displays the preset name input field.
*   The user enters a name and clicks "Save."

#### **4.12.3 Save Behavior**

*   The system creates a new payment schedule template with the current payment terms configuration.
*   The new preset is immediately available in the listing and Apply Preset dropdowns.
*   The current invoice template's payment terms remain unchanged.
*   A success message displays: "Payment preset '\[Name\]' saved successfully."

### 4.13 Times Used Tracking

#### **4.13.1 Tracking Definition**

*   \* The "Times Used" count represents the number of invoices that have been sent to clients using this preset.
*   \* The count increments specifically when an invoice is \*\*sent\*\* to the client.
*   \* The count does \*\*not\*\* increment in any of the following cases:
*   \* When the preset is applied to an invoice template (Apply Preset action).
*   \* When an invoice is created from a template but not yet sent.
*   \* When a draft invoice exists but is not sent.
*   \* When the preset itself is edited.

**4.13.2 Count Display**

*   The Times Used count is displayed in the listing table.
*   The count is updated in real-time as invoices are created.

#### **4.13.3 Count Behavior on Edit**

*   Editing a payment schedule does not reset the Times Used count.
*   The count continues to accumulate.

#### **4.13.4 Count Behavior on Duplicate**

*   When a preset is duplicated, the new preset's Times Used is set to 0.
*   The original preset's Times Used remains unchanged.

### 4.14 Validation Rules

#### **4.14.1 Minimum Payment Entry**

*   A payment schedule must have at least one payment entry.
*   The system prevents saving a payment schedule with no entries.
*   Error message: "Please add at least one payment entry."

#### **4.14.2 Preset Name Required**

*   The preset name is required and cannot be empty.
*   Error message: "Preset name is required."

#### **4.14.3 Preset Name Uniqueness**

*   Preset names do not need to be unique.
*   Duplicate names are allowed to support different users creating similarly named presets.

#### **4.14.4 Payment Entry Completeness**

*   Each payment entry must have a valid date type configuration.
*   For Smart Date, number, unit, and condition are required.
*   For Custom Date, a valid date is required.
*   Each payment entry must have a valid payment type configuration.
*   For Custom Amount, a non-negative amount is required.
*   For Percentage, a value between 0 and 100 is required.

**\*\*4.14.5 Custom Date Past Date Allowance\*\***

\* Custom Date payment entries with dates in the past are allowed at both preset creation time and at invoice creation time.

\* The system does not block save or apply due to a past Custom Date.

\* The user can correct the date inline at the invoice creation step before sending.

\* Publish validation in the Invoice Template Builder (FRD #2 Section 4.13.3) does not flag past Custom Dates either; they are surfaced to the user only by being visible in the payment entry row.

### 4.15 Key Business Rules

#### **4.15.1 Immediate Availability Rule**

*   Payment schedule templates are available immediately upon save.
*   There is no Draft/Published status for payment schedules.
*   All saved presets appear in the Apply Preset dropdown.

#### **4.15.2 Copy on Apply Rule**

*   When a preset is applied to an invoice template, the payment entries are copied.
*   The applied configuration is independent of the original preset.
*   Subsequent edits to the preset do not affect previously applied configurations.

#### **4.15.3 Ownership-Based Edit Rule**

*   \* Only Agency Owner and Admin can edit payment schedules.
*   \* Project Manager and all other roles cannot edit, regardless of ownership.
*   \* Ownership is recorded internally but does not affect edit permission.

#### **4.15.4 No Delete Protection Rule**

*   Payment schedules can be deleted regardless of usage.
*   This differs from Invoice Templates, which cannot be deleted if Times Used > 0.
*   Deletion is safe because preset data is copied at application time.

## **5\. Field Details & Validations**

### 5.1 Preset Name Field

**Field**

**Type**

**Required**

**Validation Rules**

**Max Length**

**Error Message**

Preset Name

Text

✅

Cannot be empty

100

"Preset name is required."

### 5.2 Date Type Fields

**Field**

**Type**

**Required**

**Validation Rules**

**Error Message**

Date Type

Dropdown

✅

Must select one option

"Please select a date type."

Smart Date Number

Integer

If Smart

Positive integer

"Please enter a valid number."

Smart Date Unit

Dropdown

If Smart

Days/Weeks/Months

"Please select a unit."

Smart Date Condition

Dropdown

If Smart

before project date/after project date/after invoice sent

"Please select a condition."

Custom Date

Date Picker

If Custom

Valid date((past dates permitted)

"Please select a valid date."

### 5.3 Payment Type Fields

**Field**

**Type**

**Required**

**Validation Rules**

**Error Message**

Payment Type

Toggle

✅

Must select one option

"Please select a payment type."

Custom Amount

Currency

If Custom

Non-negative number

"Please enter a valid amount."

Percentage Amount

Number

If Percentage

0-100

"Percentage must be between 0 and 100."

## **6\. Success Message Handling**

**Action**

**Success Message**

**Display Method**

**Duration**

**Post-Action Behavior**

Create Payment Schedule

"Payment schedule '\[Name\]' created successfully."

Toast notification (green, top-right)

3 seconds

Preset appears in listing

Edit Payment Schedule

"Payment schedule updated successfully."

Toast notification (green, top-right)

3 seconds

Listing refreshes

Duplicate Payment Schedule

"Payment schedule duplicated successfully."

Toast notification (green, top-right)

3 seconds

New preset appears in listing

Delete Payment Schedule

"Payment schedule '\[Name\]' deleted successfully."

Toast notification (green, top-right)

3 seconds

Preset removed from listing

Apply Preset

"Payment preset '\[Name\]' applied."

Toast notification (green, top-right)

3 seconds

Payment terms replaced

Save as Preset

"Payment preset '\[Name\]' saved successfully."

Toast notification (green, top-right)

3 seconds

Preset available in dropdown

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Display Method**

**User Action Required**

Empty Preset Name

"Preset name is required."

Inline error below field

Enter a valid preset name

No Payment Entries

"Please add at least one payment entry."

Toast notification (red)

Add at least one payment entry

Missing Smart Date Number

"Please enter a valid number."

Inline error on field

Enter a positive number

Missing Smart Date Unit

"Please select a unit."

Inline error on dropdown

Select Days, Weeks, or Months

Missing Smart Date Condition

"Please select a condition."

Inline error on dropdown

Select a condition

Missing Custom Date

"Please select a valid date."

Inline error on date picker

Select a date

Invalid Percentage

"Percentage must be between 0 and 100."

Inline error on field

Enter valid percentage

Negative Custom Amount

"Please enter a valid amount."

Inline error on field

Enter non-negative amount

Edit Without Permission

Action not displayed

N/A (action hidden in three-dot menu)

Contact Admin or Manager

Delete Without Permission

Action not displayed

N/A (action hidden in three-dot menu)

Contact Admin or Manager

Network Error on Save

"Failed to save. Please try again."

Toast notification (red)

Retry save action

## **8\. Edge Cases**

**Edge Case**

**Description**

**Expected System Behavior**

All Equal Payments

User creates a preset with only Equal Payment entries.

The system allows this. Amounts are calculated when applied to an invoice.

Percentage Total > 100%

User creates multiple percentage entries totaling more than 100%.

The system allows this in the preset. Validation occurs when applied to an invoice template.

Delete Used Preset

User deletes a preset that has been used in invoices.

The system allows deletion. Existing invoices are not affected.

Very Long Preset Name

User enters a preset name exceeding 100 characters.

The system truncates or prevents entry beyond 100 characters.

Duplicate Name

User creates a preset with the same name as an existing one.

The system allows duplicate names.

Apply to Existing Terms

User applies a preset when payment terms already exist.

The preset replaces all existing terms without warning.

Delete Last Entry

User deletes the only payment entry, leaving the preset with zero entries.

The system allows the deletion. If the user then attempts to save the preset, validation fails with "Please add at least one payment entry." The preset is not saved until at least one entry is re-added.

Browser Refresh During Create

User refreshes while creating a preset.

Unsaved changes are lost. User must start over.

Concurrent Edit

Two users edit the same preset simultaneously.

Last save wins. No conflict detection.

Zero Custom Amount

User enters $0 as the custom amount.

The system allows $0 payments (e.g., for promotional invoices).

Apply Preset with No Presets

User clicks Apply Preset when no presets exist in the system.

The dropdown does not open. A toast notification displays: "No presets available."

Equal Payment on $0 Invoice

A preset containing only Equal Payment entries is applied to a $0 promotional invoice.

Each Equal Payment entry resolves to $0. This is expected behavior for promotional invoices.

Custom Date in Past

A preset contains a Custom Date that has already passed at the time the preset is applied.

The system applies the preset as-is, including the past date. The user may edit the date inline during invoice creation. No warning or validation block is displayed.

Pagination Stale Data

User A is viewing page 2 while User B deletes a preset from page 1.

Pagination data is fetched per request. Users may observe shifted results if the dataset changes between navigations. No real-time synchronization is implemented in Phase 1.

Manage Presets Tab Lifecycle

User opens "Manage Presets" in a new tab and later closes the tab.

The original Invoice Builder session remains unaffected. Any preset changes become visible in the Apply Preset dropdown the next time it is opened.

## **9\. Acceptance Criteria**

*   ✅ Payment Schedules tab is displayed on the Invoices page alongside Invoices tab.
*   ✅ Clicking Payment Schedules tab displays the payment schedule listing.
*   ✅ Listing displays columns: Preset Name, Times Used, and Actions.
*   ✅ "+ Create Payment Schedule" button is displayed in the top right corner.
*   ✅ Search filters the listing by preset name in real-time.
*   ✅ Pagination displays 10, 25, or 50 rows per page with navigation controls.
*   ✅ Empty state is displayed when no presets exist with call-to-action to create.
*   ✅ Three-dot menu displays Edit, Duplicate, and Delete actions.
*   ✅ Add Payment modal allows configuration of date type and payment type.
*   ✅ Smart Date displays number, unit, and condition fields when selected.
*   ✅ Percentage displays percentage input with helper text when selected.
*   ✅ Equal Payment hides amount field when selected.
*   ✅ Save Payment Preset modal captures preset name.
*   ✅ Presets are available immediately upon save (no Draft status).
*   ✅ Apply Preset dropdown in Invoice Builder shows all available presets.
*   ✅ "Manage Presets" link in dropdown navigates to Payment Schedules listing.
*   ✅ Save as Preset in Invoice Builder creates a new preset from current configuration.
*   ✅ Times Used count increments when an invoice is created using the preset.
*   ✅ Deleting a preset is allowed regardless of Times Used count.
*   ✅ At least one payment entry is required to save a preset.
*   \* ✅ Only Agency Owner and Admin can create, edit, duplicate, or delete payment schedule presets.
*   \* ✅ Project Manager has view-only access to the Payment Schedules listing; the "+ Create Payment Schedule" button and three-dot menu are hidden.
*   \* ✅ Smart Date condition labels are "before event date," "after event date," "after invoice sent" (not "project date").
*   \* ✅ Custom Date allows past dates at both preset creation and invoice creation.
*   \* ✅ Times Used increments only when an invoice is \*\*sent\*\* to the client, not on creation or apply.
*   \* ✅ Times Used never decrements, even after deactivation, void, or deletion.
*   \* ✅ Editing a preset does not affect Times Used count.
*   \* ✅ The last payment entry in a preset can be deleted (leaving zero entries), but saving requires at least one entry.
*   \* ✅ Duplicate preset naming follows "Copy of \[Name\]" / "Copy of \[Name\] (1)" / "Copy of \[Name\] (2)" convention.
*   \* ✅ Apply Preset with no presets shows "No presets available." toast instead of opening an empty dropdown.
*   \* ✅ "Manage Presets" link opens the Payment Schedules listing in a new browser tab; the Invoice Builder session remains open.
*   \* ✅ All Builder edits are auto-saved (per FRD #2), so no unsaved-changes warning appears when clicking Manage Presets.
*   \* ✅ Equal Payment entries on a $0 invoice resolve to $0 each.
*   \* ✅ Sort behavior follows three-click pattern (asc → desc → asc) matching FRD #1.

## **10\. Dependencies**

**Dependency Type**

**Dependency Name**

**Description**

**Impact if Unavailable**

Internal Module

Invoice Template Builder (FRD #2)

Provides Apply Preset and Save as Preset functionality.

Cannot apply or save presets from builder.

Internal Module

Invoice Template Listing (FRD #1)

Parent page containing Payment Schedules tab.

Cannot access payment schedules listing.

Internal Module

Invoice Creation (FRD #5)

Triggers Times Used increment.

Times Used not tracked.

Internal Module

User & Permissions Module

Provides role and ownership information.

Cannot enforce edit/delete permissions.

Database

Payment\_Schedule\_Templates Table

Stores preset data.

Cannot save or load presets.

Database

Payment\_Schedule\_Entries Table

Stores individual payment entries.

Cannot save payment entry configurations.

Database

Invoices Table

Tracks invoice creation for Times Used.

Times used not tracked.

## **11\. References**

**Figma Designs:**

*   1-payment\_schedule\_template\_listing.png - Payment Schedule listing page
*   4-payment\_terms.png - Add Payment modal (Custom Amount)
*   4-payment\_terms\_percentage\_view.png - Add Payment modal (Percentage)
*   4-payment\_terms\_equal\_view.png - Add Payment modal (Equal Payment)
*   4-payment\_terms\_save\_preset.png - Save Payment Preset modal
*   4-payment\_terms\_apply\_preset.png - Apply Preset dropdown in Invoice Builder

**Related FRDs:**

*   FRD #1: Invoice Template Listing
*   FRD #2: Invoice Template Creation & Template Builder
*   FRD #3: Edit Invoice Template with Conditions
*   FRD #5: Use Invoice in Project & Auto-Generation from Proposal

**Source Documents:**

*   Module Logic Explanation - Meeting Transcript (December 2025)
*   Client Meeting MOM - Invoice Module Discussion
*   Clarifying Questions & Answers Document

☑️ 5. Use Invoice in Project

# **FRD #5: Use Invoice in Project & Auto-Generation from Proposal**

**Version:** 1.0  
**Date:** December 10, 2025

## **1\. Module Overview**

**Purpose:  
**This document defines how invoices are created, managed, and shared within projects. Users can create invoices by selecting from Published invoice templates, or invoices can be auto-generated when a client signs a contract (accepts a proposal). The module also covers invoice editing, sharing via email or link, status management, and client access through the client portal.

**Business Goals:**

*   Streamline invoice creation within project workflows.
*   Automate invoice generation from accepted proposals to reduce manual effort.
*   Enable flexible payment collection through Stripe integration and manual recording.
*   Provide clients with easy access to invoices and payment schedules via client portal.
*   Track invoice and payment statuses across the organization.

**Scope:**

*   Invoice creation methods within projects (template selection, auto-generation).
*   Invoice editor interface and editable fields.
*   Share Invoice functionality (email with link, copy link).
*   Invoice status lifecycle and transitions.
*   Payment tracking based on payment schedule transactions.
*   Client portal invoice access.
*   Finance module integration for centralized invoice management.
*   Multiple invoices per project.
*   Project total price calculation from invoices.
*   Overdue reminders per transaction.
*   Client data snapshot behavior.

## **2\. User Roles & Permissions**

**Permission**

**Admin**

**Manager**

**Team Member**

**Client**

Create Invoice in Project

✅

✅

✅

❌

Edit Invoice (Before Sending)

✅

✅

✅

❌

Edit Invoice (After Sending)

✅

✅

❌

❌

Share Invoice

✅

✅

✅

❌

Copy Invoice Link

✅

✅

✅

❌

View Invoice in Project

✅

✅

✅

❌

Cancel Invoice

✅

✅

❌

❌

Deactivate Invoice

✅

✅

❌

❌

Reactivate Invoice

✅

✅

❌

❌

Record Manual Payment

✅

✅

❌

❌

View Invoice (Client Portal)

❌

❌

❌

✅

Make Payment (Client Portal)

❌

❌

❌

✅

**Permission Notes:**

*   Team Members can create and share invoices but cannot cancel, deactivate, or record manual payments.
*   Clients can only view invoices shared with them and make payments through the client portal.
*   After an invoice is sent, only Admin and Manager can make edits.

## **3\. User Flow**

### 3.1 Create Invoice from Project Files/Documents Tab

*   The user navigates to Projects and selects a project.
*   The user clicks the "Files/Documents" tab.
*   The user clicks the "+" button next to "Documents."
*   The system opens the Add New Document modal.
*   The user selects the "Invoice" tab.
*   The system displays a list of Published invoice templates with "Review & Send" buttons.
*   The user can search for a specific template using the search field.
*   The user clicks "Review & Send" on the desired template.
*   The system creates a new invoice from the template and opens the Invoice Editor.
*   Project and client data auto-populate into the invoice.
*   The user reviews, makes any necessary edits, and proceeds to share.

### 3.2 Create Invoice from Project Management Panel

*   The user navigates to Projects and selects a project.
*   The user locates the Project Management panel on the right side.
*   The user clicks "CREATE FILE."
*   The system opens the Add New Document modal with tabs: Local File, Invoice, Contract, Proposal, Questionnaire.
*   The user selects the "Invoice" tab.
*   The system displays a list of Published invoice templates.
*   The user clicks "Review & Send" on the desired template.
*   The system creates a new invoice and opens the Invoice Editor.

### 3.3 Create Invoice from Finance Tab

*   The user navigates to Projects and selects a project.
*   The user clicks the "Finances" tab.
*   The user clicks "Create Invoice" or a similar button.
*   The system opens the template selection modal.
*   The user selects a template and proceeds to the Invoice Editor.

### 3.4 Auto-Generate Invoice from Proposal

*   A client views a proposal sent to them.
*   The client reviews the proposal details and accepts by signing the contract.
*   Upon contract signature, the system automatically generates an invoice.
*   The system uses the Pixally-wide default invoice template.
*   The system maps all data from the proposal to the invoice: line items (packages/services), pricing, client information, and payment terms.
*   The invoice is created with "Unpaid" status and associated with the project.
*   The invoice appears in the project's Files/Documents tab.
*   A notification is sent to the project team about the auto-generated invoice.

### 3.5 Review and Edit Invoice

*   The user opens an invoice from the Files/Documents tab or Finance tab.
*   The system opens the Invoice Editor with the invoice content displayed.
*   The user can modify: Title, Logo, Contact Information (FROM section), Line Items, Payment Terms, Tax, Discount, and Styling.
*   The user cannot modify: Invoice Number (auto-generated) and Issued On date (system-generated).
*   The user clicks "Preview" to review the final invoice appearance.
*   The user clicks "Share Invoice" when ready to send.

### 3.6 Share Invoice via Email

*   The user clicks "Share Invoice" button in the Invoice Editor header.
*   The system opens the Share Invoice modal.
*   The "Email To" field is pre-populated with the client's email address.
*   The user can add additional recipients by clicking the "+" button.
*   The user enters a Subject line.
*   The user types a message in the message body.
*   A "Pay Invoice" button is automatically embedded in the email.
*   The user can select an email template from the "Template" dropdown.
*   The user can format text using the formatting toolbar (text style, links, attachments, etc.).
*   The user clicks "Preview" to review the email before sending.
*   The user clicks "Send" to send the invoice.
*   The system sends an email with a link to the online invoice.
*   The invoice status changes based on the payment schedule transaction statuses.

### 3.7 Copy Invoice Link

*   The user clicks "Share Invoice" button in the Invoice Editor header.
*   The system opens the Share Invoice modal.
*   The user clicks "Copy Link" at the bottom left of the modal.
*   The system copies the invoice URL to the clipboard.
*   A success message displays: "Link copied to clipboard."
*   The user can share this link through any channel (chat, SMS, etc.).

### 3.8 Client Views Invoice in Portal

*   The client receives an email with the invoice link.
*   The client clicks the link or the "Pay Invoice" button.
*   The system opens the invoice in the client portal.
*   The client views the invoice details: line items, amounts, payment schedule.
*   The client can also access the invoice from: Client Portal → Project Details → Files/Documents tab.
*   The payment schedule is visible in: Client Portal → Project Details → Finances tab.

### 3.9 Client Makes Payment

*   The client views the invoice in the client portal.
*   The client clicks "Pay" or a similar button for a payment entry.
*   The system opens the payment interface (Stripe integration).
*   The client enters payment details and completes the payment.
*   The system updates the transaction status to "Paid" or "Processing" (for ACH/3D Secure).
*   The invoice status updates based on all transaction statuses.

### 3.10 Record Manual Payment

*   The Admin or Manager opens an invoice.
*   The Admin or Manager navigates to the payment schedule section.
*   The Admin or Manager clicks "Record Payment" or similar action on a payment entry.
*   The system opens a modal to record payment details.
*   The Admin or Manager enters payment amount, date, and method.
*   The system updates the transaction status to "Paid."
*   The invoice status updates based on all transaction statuses.

##

## **4\. Functional Logic**

### 4.1 Invoice Creation Methods

#### **4.1.1 Template Selection Method**

*   Users create invoices by selecting from Published invoice templates.
*   Only Published templates are displayed in the selection interface.
*   Draft templates are not available for invoice creation.
*   The selection interface displays template name and type ("Invoice Template").
*   Each template row includes a "Review & Send" button.
*   A search field allows filtering templates by name.

#### **4.1.2 Add New Document Modal**

*   The modal title displays: "Add New Document."
*   Five tabs are displayed: Local File, Invoice, Contract, Proposal, Questionnaire.
*   The "Invoice" tab displays the list of Published invoice templates.
*   When "Local File" is selected, an upload interface is displayed for uploading external invoice files.
*   The "Upload File" button is displayed at the bottom right.

#### **4.1.3 Auto-Generation Method**

*   Invoices are auto-generated when a client signs the contract within a proposal.
*   Contract signing constitutes proposal acceptance.
*   The system uses the Pixally-wide default invoice template configured in system settings.
*   Auto-generation occurs immediately upon contract signature.
*   No user intervention is required for auto-generation.

### 4.2 Data Mapping for Invoice Creation

#### **4.2.1 Project Data Auto-Population**

*   When an invoice is created within a project, the system automatically populates project-related data.
*   The project name is associated with the invoice record.
*   The project's primary event date is used for Smart Date calculations in payment terms.
*   The project's brand settings are applied if the template uses brand colors/logo.

#### **4.2.2 Client Data Auto-Population**

*   The BILL TO section is populated with client information from the project.
*   Client name is populated from the client record.
*   Client email is populated from the client record.
*   Client billing address is populated from the client's address details.
*   If billing address is missing, the system displays a prompt to add the address.

#### **4.2.3 FROM Section Auto-Population**

*   The FROM section is populated with agency/company information.
*   Company name is populated from the brand settings.
*   Company email is populated from the brand settings.
*   Company address can be added via "Add Address" link if not configured.

#### **4.2.4 Proposal Data Mapping (Auto-Generation)**

*   When auto-generating from a proposal, all proposal data is mapped to the invoice.
*   Line items (packages, services) are copied with their descriptions, quantities, and prices.
*   Payment terms from the proposal are copied to the invoice.
*   Client information is inherited from the proposal.
*   The total amount matches the proposal total.

### 4.3 Invoice Editor Interface

#### **4.3.1 Editor Layout**

*   The Invoice Editor follows the same layout as the Template Builder (FRD #2).
*   A left sidebar displays the Invoice Structure with mandatory blocks: Logo, Title, Contact Information, Items, Payment Terms.
*   The main canvas displays the invoice content in WYSIWYG format.
*   Additional sidebar tabs are available: Colors, Fonts, Settings (TBD).

#### **4.3.2 Header Elements**

*   The header displays a Back arrow (←) for exiting the editor.
*   The invoice name is displayed (e.g., "Blank Invoice") and can be edited inline.
*   A status badge displays the current status (e.g., "Draft" in yellow/orange).
*   A three-dot menu (⋮) provides additional options.
*   Icon buttons are displayed for additional actions (document, desktop view).
*   A "Preview" button is displayed.
*   A "Share Invoice" button (yellow/gold) is displayed on the far right.

#### **4.3.3 Editable Fields**

*   The user can edit all content fields including:
    *   Invoice title text
    *   Logo (upload different image)
    *   FROM section details (can add address)
    *   BILL TO section (if needed)
    *   Line items (add, edit, delete, reorder)
    *   Payment terms (add, edit, delete)
    *   Tax configuration
    *   Discount configuration
    *   Colors and fonts

#### **4.3.4 Non-Editable Fields**

*   Invoice Number is auto-generated by the system and cannot be modified.
*   Issued On date is set to the current date when the invoice is created and cannot be modified.
*   These fields are displayed but the input is disabled or read-only.

#### **4.3.5 Invoice Number Generation**

*   Invoice numbers are auto-generated in sequential format.
*   The format follows: #INV\[NNNNN\] (e.g., #INV00001, #INV00002).
*   The sequence is maintained across all invoices in the system.
*   Invoice numbers are unique and never reused.

### 4.4 Share Invoice Modal

#### **4.4.1 Modal Structure**

*   The modal title displays: "Share Invoice."
*   An X button in the top right closes the modal.
*   The modal contains email configuration fields and action buttons.

#### **4.4.2 Email To Field**

*   The "Email To" label is displayed.
*   The client's email is pre-populated as a chip/tag (e.g., "Emma Johnson ×").
*   The × on the chip removes that recipient.
*   A "+" button allows adding additional recipients.
*   Multiple recipients can be added.

#### **4.4.3 Subject Field**

*   The "Subject" label is displayed.
*   A text input field with placeholder "Enter the subject" is displayed.
*   The subject is required before sending.

#### **4.4.4 Message Body**

*   A "Type your message" placeholder is displayed in the message area.
*   A "Pay Invoice" button is displayed within the message area, indicating the button that will appear in the email.
*   The message body supports rich text formatting.

#### **4.4.5 Formatting Toolbar**

*   A "Template" dropdown allows selection of pre-defined email templates.
*   Formatting icons are displayed: Text formatting (A), Link (chain icon), Attachment (clip), Contact (person icon), and others.
*   These tools allow customizing the email content.

#### **4.4.6 Action Buttons**

*   "Copy Link" is displayed at the bottom left.
*   "Preview" button is displayed at the bottom right.
*   "Send" button (yellow/gold) is displayed next to Preview.

### 4.5 Invoice Delivery

#### **4.5.1 Email Delivery**

*   Clicking "Send" sends an email to all recipients in the "Email To" field.
*   The email contains the subject, message body, and a "Pay Invoice" button.
*   The "Pay Invoice" button links to the online invoice in the client portal.
*   The email does not include a PDF attachment; only the link is provided.

#### **4.5.2 Copy Link**

*   Clicking "Copy Link" generates and copies the invoice URL to the clipboard.
*   The URL provides direct access to the online invoice.
*   The link can be shared through any communication channel.
*   The link remains valid until the invoice is voided or deactivated.

### 4.6 Invoice Status Lifecycle

#### **4.6.1 Status Overview**

*   Invoices have nine possible statuses: Unpaid, Processing, Paid, Overdue, Failed, Cancelled, Refunded, Voided, and Deactivated.
*   Invoice status is derived from the statuses of individual transactions in the payment schedule.
*   Each payment entry in the schedule is tracked as a separate transaction.

#### **4.6.2 Unpaid Status**

*   An invoice is Unpaid when one or more transactions have not been paid and are not yet overdue.
*   This is the initial status for new invoices after creation.
*   The status badge displays "Unpaid" in gray.

#### **4.6.3 Processing Status**

*   An invoice is Processing when one or more transactions are being processed.
*   This typically occurs with ACH payments or 3D Secure credit card payments.
*   Processing payments typically take 3-4 working days to complete.
*   The status badge displays "Processing" in blue or similar.

#### **4.6.4 Paid Status**

*   An invoice is Paid when all transactions in the payment schedule are paid.
*   A Paid invoice cannot be changed to Cancelled, Unpaid, or Overdue.
*   The status badge displays "Paid" in green.

#### **4.6.5 Overdue Status**

*   An invoice is Overdue when one or more transactions have passed their due date without payment.
*   The system automatically updates the status when a due date passes.
*   An Overdue invoice can be marked as Paid when payment is received.
*   The status badge displays "Overdue" in red or orange.

#### **4.6.6 Failed Status**

*   An invoice is Failed when a payment attempt was unsuccessful.
*   This occurs when online payment through Stripe fails.
*   The client can retry the payment.
*   The status badge displays "Failed" in red.

#### **4.6.7 Cancelled Status**

*   An invoice is Cancelled when a user manually cancels it.
*   Only Admin and Manager can cancel invoices.
*   A Cancelled invoice cannot be changed to other statuses (terminal state).
*   Cancellation is a user-initiated action.
*   The status badge displays "Cancelled" in gray or red.

#### **4.6.8 Refunded Status**

*   An invoice is Refunded when payment has been returned to the client.
*   Refunds are processed through Stripe or recorded manually.
*   A Refunded invoice cannot be changed to any other status (terminal state).
*   An Unpaid invoice cannot be Refunded (no payment to refund).
*   The status badge displays "Refunded" in purple or similar.

#### **4.6.9 Voided Status**

*   An invoice is Voided when the associated project is cancelled or deleted.
*   Voiding is an automatic system action, not user-initiated.
*   A Voided invoice cannot be changed to any other status (terminal state).
*   The status badge displays "Voided" in gray.

#### **4.6.10 Deactivated Status**

*   An invoice is Deactivated when a user deactivates it manually.
*   Only Admin and Manager can deactivate invoices.
*   Deactivated invoices can be reactivated.
*   The status badge displays "Deactivated" in red/orange with a "Reactivate" button.

### 4.7 Status Transition Rules

#### **4.7.1 Allowed Transitions**

**From Status**

**To Status**

**Trigger**

Unpaid

Processing

Client initiates ACH/3D Secure payment

Unpaid

Paid

All transactions paid

Unpaid

Overdue

Due date passes

Unpaid

Failed

Payment attempt fails

Unpaid

Cancelled

User cancels manually

Unpaid

Voided

Project cancelled/deleted

Unpaid

Deactivated

User deactivates manually

Processing

Paid

Payment processing completes successfully

Processing

Failed

Payment processing fails

Overdue

Paid

Payment received after due date

Overdue

Cancelled

User cancels manually

Overdue

Voided

Project cancelled/deleted

Overdue

Deactivated

User deactivates manually

Failed

Processing

Client retries payment

Failed

Paid

Retry payment succeeds

Failed

Cancelled

User cancels manually

Deactivated

Unpaid/Overdue

User reactivates (returns to previous state)

#### **4.7.2 Terminal States**

*   **Paid:** Cannot transition to Cancelled, Unpaid, or Overdue.
*   **Cancelled:** Cannot transition to any other status.
*   **Refunded:** Cannot transition to any other status.
*   **Voided:** Cannot transition to any other status.

#### **4.7.3 Transaction-Based Status Calculation**

*   The invoice status is calculated based on the collective status of all transactions.
*   If ANY transaction is Failed, the invoice status is Failed.
*   If ANY transaction is Processing, the invoice status is Processing (unless Failed exists).
*   If ANY transaction is Overdue, the invoice status is Overdue (unless Failed/Processing exists).
*   If ALL transactions are Paid, the invoice status is Paid.
*   If ALL transactions are Unpaid and not overdue, the invoice status is Unpaid.
*   Voided, Cancelled, Deactivated, and Refunded are invoice-level statuses that override transaction calculations.

### 4.8 Payment Methods

#### **4.8.1 Online Payment (Stripe)**

*   Clients can pay invoices online through Stripe integration.
*   Supported payment methods include credit/debit cards and ACH bank transfers.
*   3D Secure authentication may be required for certain card payments.
*   Online payments update transaction status automatically.

#### **4.8.2 Manual Payment Recording**

*   Admin and Manager can record payments received outside the system.
*   Manual payment recording is used for cash, check, or wire transfer payments.
*   The user enters payment amount, date, and method.
*   Manual recording updates the transaction status to Paid.

#### **4.8.3 Partial Payments**

*   Partial payments are not supported.
*   Each transaction in the payment schedule must be paid in full.
*   If a client pays less than the transaction amount, it is not recorded as a partial payment.

### 4.9 Client Portal Access

#### **4.9.1 Invoice Access**

*   Clients access invoices through the client portal.
*   Invoices are visible in: Client Portal → Project Details → Files/Documents tab.
*   The client can view invoice details, line items, and payment status.

#### **4.9.2 Payment Schedule Access**

*   Clients view the payment schedule in: Client Portal → Project Details → Finances tab.
*   The schedule displays each payment entry with due date, amount, and status.
*   Clients can initiate payment for unpaid entries.

#### **4.9.3 Payment History**

*   Clients can view their payment history in the portal.
*   Each payment shows date, amount, method, and status.

### 4.10 Finance Module Integration

#### **4.10.1 Billing Page**

*   The Finance module includes a Billing page accessible via: Finances → Billing.
*   The Billing page has two tabs: Invoices and Transactions.
*   The Invoices tab displays all invoices across all projects.

#### **4.10.2 Invoice Listing in Finance Module**

*   The listing displays columns: Next Payment Date, Invoice ID, Client, Amount, Status (or Payments count), Project, Actions.
*   Invoices can be expanded to show individual payment schedule entries.
*   Each entry shows: Date, Amount, Status.
*   Filters include: All Brands dropdown, Search, and filter icon.
*   Tabs include: All, Deactivated.

#### **4.10.3 Expandable Invoice Rows**

*   Clicking the expand arrow (˅) on an invoice row reveals payment schedule details.
*   Each payment entry is displayed as a sub-row.
*   Sub-rows show: Date, Amount, Status (Paid/Unpaid).
*   The collapse arrow (˄) hides the details.

#### **4.10.4 Deactivated Tab**

*   The Deactivated tab shows invoices with Deactivated status.
*   A "Reactivate" button is displayed for each deactivated invoice.
*   Clicking Reactivate restores the invoice to its previous active status.

### 4.11 Reactivate Invoice

#### **4.11.1 Reactivate Action**

*   The Reactivate button is displayed for Deactivated invoices only.
*   Clicking Reactivate opens a confirmation prompt.
*   Upon confirmation, the invoice returns to its previous status (Unpaid, Overdue, etc.).
*   A success message displays: "Invoice reactivated successfully."

### 4.12 Key Business Rules

#### **4.12.1 Default Template Rule**

*   Auto-generated invoices use the Pixally-wide default invoice template.
*   The default template is configured at the system level, not per-agency or per-brand.
*   All auto-generated invoices have a consistent format.

#### **4.12.2 Contract Signature Trigger Rule**

*   Invoice auto-generation is triggered by contract signature within a proposal.
*   Contract signature equals proposal acceptance.
*   Auto-generation is immediate and automatic.

#### **4.12.3 Non-Editable Fields Rule**

*   Invoice Number and Issued On date are system-generated and cannot be modified.
*   This ensures invoice integrity and audit compliance.

#### **4.12.4 Transaction-Based Status Rule**

*   Invoice status is derived from the statuses of all payment schedule transactions.
*   Individual transactions are tracked separately.
*   The invoice status reflects the "worst" or aggregate state of its transactions.

#### **4.12.5 Terminal Status Rule**

*   Paid, Cancelled, Refunded, and Voided are terminal statuses.
*   These statuses cannot transition to other statuses (except Deactivated can be reactivated).
*   Terminal statuses represent final states of an invoice.

#### **4.12.6 No Partial Payment Rule**

*   Each transaction must be paid in full.
*   The system does not support partial payment recording.

### 4.13 Multiple Invoices per Project

#### **4.13.1 Multiple Invoice Support**

*   Users can create multiple invoices within a single project.
*   There is no limit to the number of invoices that can be created per project.
*   Each invoice is tracked independently with its own status, payment schedule, and transactions.
*   All invoices for a project are displayed in the project's Files/Documents tab.

#### **4.13.2 Invoice-Project Association**

*   Invoices are associated at the project level only, not at the individual event level.
*   Even if a project has multiple events (e.g., Rehearsal Dinner, Wedding, Engagement Photoshoot), the invoice is linked to the overall project.
*   The invoice may include line items for multiple events, but the association remains project-level.

#### **4.13.3 Invoice Naming Convention**

*   Invoice names are auto-generated based on the project name.
*   The naming format is: "Invoice-\[Project Name\]" (e.g., "Invoice-Rehearsal Dinner", "Invoice-Wedding").
*   If multiple invoices exist for the same project, subsequent invoices may include a sequence number or timestamp.
*   Users can edit the invoice name in the Invoice Editor if desired.

### 4.14 Project Price Calculation

#### **4.14.1 Total Project Price Derivation**

*   The total project price is derived from the sum of all invoice amounts associated with the project.
*   Only invoices with active statuses are included in the calculation.
*   Invoices with Deactivated, Voided, or Cancelled statuses are excluded from the project total.
*   The formula is: Total Project Price = Sum of (Invoice Total Amount) where Status NOT IN (Deactivated, Voided, Cancelled).

#### **4.14.2 Dynamic Recalculation**

*   The project total recalculates automatically when:
    *   A new invoice is created and sent.
    *   An existing invoice is modified (amount changes).
    *   An invoice status changes to Deactivated, Voided, or Cancelled.
    *   A Deactivated invoice is reactivated.
*   The updated total is reflected in the project's Finance tab and any related reports.

### 4.15 Overdue Reminders

#### **4.15.1 Automatic Reminder Emails**

*   The system sends automatic reminder emails for overdue transactions.
*   Reminders are sent per transaction, not per invoice.
*   If an invoice has multiple transactions and only one is overdue, the reminder is sent for that specific transaction only.

#### **4.15.2 Reminder Trigger**

*   A reminder is triggered when a transaction's due date passes without payment.
*   The system checks transaction due dates daily and sends reminders accordingly.
*   Reminders are sent to the client's email address on file.

#### **4.15.3 Reminder Content**

*   The reminder email includes the transaction amount, original due date, and a link to pay.
*   The "Pay Invoice" button in the email directs the client to the payment interface.

### 4.16 Transaction Due Dates

#### **4.16.1 Due Date Per Transaction**

*   Each transaction in the payment schedule has its own due date.
*   The due date is determined based on the payment terms configuration (Smart Date, Invoice Date, Custom Date, or Event Date).
*   There is no single "invoice due date"; each transaction is tracked independently.

#### **4.16.2 Smart Date Calculation**

*   For Smart Date configurations, the due date is calculated based on the project's event date or invoice sent date.
*   Example: "4 Days before project date" calculates the due date as Event Date minus 4 days.
*   The calculation occurs when the invoice is created or when the event date is set/updated.

### 4.17 Client Data Snapshot

#### **4.17.1 Data Retention for Sent Invoices**

*   Once an invoice is sent, it retains the client information that existed at the time of sending.
*   If the client's email, address, or other details change after the invoice is sent, the sent invoice is not updated.
*   This ensures invoice integrity and provides an accurate historical record.

#### **4.17.2 New Invoice Data Fetch**

*   When a new invoice is created, the system fetches the most current client information.
*   Any updates to client details (email, billing address, name) are reflected in newly created invoices.
*   Users should verify client information before sending if significant time has passed since data entry.

## **5\. Field Details & Validations**

### 5.1 Invoice Header Fields

**Field**

**Type**

**Required**

**Editable**

**Validation Rules**

**Error Message**

Invoice Number

Text

✅

❌

Auto-generated, unique

N/A

Invoice Name

Text

✅

✅

Cannot be empty

"Invoice name is required."

Issued On

Date

✅

❌

System-generated

N/A

Due Date

Date

✅

✅

Must be valid date

"Please select a valid due date."

### 5.2 Contact Information Fields

**Field**

**Type**

**Required**

**Editable**

**Validation Rules**

**Error Message**

FROM - Name

Text

✅

✅

Cannot be empty

"Company name is required."

FROM - Email

Email

✅

✅

Valid email format

"Please enter a valid email."

FROM - Address

Text

❌

✅

Optional

N/A

BILL TO - Name

Text

✅

✅

Cannot be empty

"Client name is required."

BILL TO - Email

Email

✅

✅

Valid email format

"Please enter a valid email."

BILL TO - Address

Text

✅

✅

Required for invoicing

"Client billing address is required."

### 5.3 Share Invoice Fields

**Field**

**Type**

**Required**

**Validation Rules**

**Error Message**

Email To

Email (multiple)

✅

At least one recipient

"Please add at least one recipient."

Subject

Text

✅

Cannot be empty

"Subject is required."

Message

Rich Text

❌

Optional

N/A

## **6\. Success Message Handling**

**Action**

**Success Message**

**Display Method**

**Duration**

**Post-Action Behavior**

Create Invoice

"Invoice created successfully."

Toast notification (green)

3 seconds

Opens Invoice Editor

Save Invoice

"Invoice saved successfully."

Toast notification (green)

3 seconds

Stays in editor

Send Invoice

"Invoice sent successfully."

Toast notification (green)

3 seconds

Modal closes

Copy Link

"Link copied to clipboard."

Toast notification (green)

2 seconds

Link in clipboard

Cancel Invoice

"Invoice cancelled successfully."

Toast notification (green)

3 seconds

Status updates

Deactivate Invoice

"Invoice deactivated successfully."

Toast notification (green)

3 seconds

Status updates

Reactivate Invoice

"Invoice reactivated successfully."

Toast notification (green)

3 seconds

Status updates

Record Payment

"Payment recorded successfully."

Toast notification (green)

3 seconds

Transaction status updates

Auto-Generate Invoice

"Invoice generated from proposal."

Toast notification (green)

3 seconds

Invoice appears in documents

Overdue Reminder Sent

"Overdue reminder sent to \[client name\]."

System log / Notification

N/A

Email delivered to client

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Display Method**

**User Action Required**

Missing Client Email

"Client email is required to send invoice."

Toast notification (red)

Add client email

Missing Billing Address

"Client billing address is required."

Inline error

Add billing address

Missing Subject

"Subject is required."

Inline error

Enter subject

No Recipients

"Please add at least one recipient."

Toast notification (red)

Add email recipient

Payment Failed

"Payment failed. Please try again."

Toast notification (red)

Client retries payment

Invalid Email Format

"Please enter a valid email address."

Inline error

Correct email format

Network Error

"Failed to send. Please try again."

Toast notification (red)

Retry action

Cannot Cancel Paid Invoice

"Paid invoices cannot be cancelled."

Toast notification (red)

No action available

Cannot Refund Unpaid Invoice

"Cannot refund an unpaid invoice."

Toast notification (red)

No action available

## **8\. Edge Cases**

**Edge Case**

**Description**

**Expected System Behavior**

Proposal Without Payment Terms

Proposal accepted but has no payment terms configured.

Auto-generated invoice uses default payment terms from template.

Client Without Billing Address

Invoice created for client without billing address.

System prompts user to add billing address before sending.

Project Deleted with Active Invoice

Project is deleted while invoice has unpaid status.

Invoice status changes to Voided automatically. Project total recalculates.

Send to Multiple Recipients

User adds multiple email recipients.

All recipients receive the email with invoice link.

Link Shared Externally

Invoice link is shared to non-client recipient.

Link opens invoice view; payment requires client authentication.

Payment During Processing

Client attempts new payment while another is processing.

System prevents duplicate payment; shows "Payment in progress."

ACH Payment Timeout

ACH payment takes longer than expected.

Status remains Processing; auto-updates when bank confirms.

Refund After Partial Schedule Paid

User initiates refund when only some payments are complete.

Refund applies to paid transactions only.

Deactivate Then Reactivate

User deactivates and later reactivates an invoice.

Invoice returns to previous status; payment schedule preserved. Project total recalculates.

All Invoices Deactivated/Voided

All invoices in a project are deactivated or voided.

Project total becomes $0.

Client Data Changed After Invoice Sent

Client email or address updated after invoice was sent.

Sent invoice retains original data. New invoices use updated data.

Multiple Overdue Transactions

Invoice has multiple transactions that become overdue.

Separate reminder email sent for each overdue transaction.

Event Date Changed After Invoice Created

Project event date updated after invoice with Smart Date terms created.

Transaction due dates may need manual recalculation or auto-update based on system configuration.

Invoice Name Collision

Multiple invoices auto-named from same project.

System appends sequence number or allows duplicate names.

## **9\. Acceptance Criteria**

**Invoice Creation:**

*   ✅ Users can create invoices from Project → Files/Documents → "+" → Invoice tab.
*   ✅ Users can create invoices from Project Management panel → CREATE FILE → Invoice tab.
*   ✅ Only Published templates are displayed in the template selection.
*   ✅ "Review & Send" button opens the Invoice Editor with selected template.
*   ✅ Project and client data auto-populate into the invoice.

**Auto-Generation:**

*   ✅ Invoice is auto-generated when client signs contract (accepts proposal).
*   ✅ Auto-generated invoice uses Pixally-wide default template.
*   ✅ All proposal data (line items, pricing, payment terms, client info) maps to invoice.
*   ✅ Auto-generated invoice appears in project's Files/Documents tab.

**Invoice Editor:**

*   ✅ Editor displays same interface as Template Builder.
*   ✅ User can edit all fields except Invoice Number and Issued On date.
*   ✅ Invoice Number is auto-generated in format #INV\[NNNNN\].
*   ✅ Preview button shows final invoice appearance.
*   ✅ Share Invoice button opens sharing modal.

**Share Invoice:**

*   ✅ Share modal pre-populates client email.
*   ✅ User can add multiple recipients.
*   ✅ Subject and message fields are available.
*   ✅ "Pay Invoice" button is embedded in email.
*   ✅ Copy Link copies invoice URL to clipboard.
*   ✅ Send delivers email with link to online invoice.

**Invoice Statuses:**

*   ✅ Nine statuses are supported: Unpaid, Processing, Paid, Overdue, Failed, Cancelled, Refunded, Voided, Deactivated.
*   ✅ Invoice status is calculated from transaction statuses.
*   ✅ Paid invoices cannot be changed to Cancelled, Unpaid, or Overdue.
*   ✅ Cancelled, Refunded, and Voided are terminal statuses.
*   ✅ Deactivated invoices can be reactivated.
*   ✅ Project cancellation/deletion automatically voids associated invoices.

**Payments:**

*   ✅ Clients can pay online via Stripe.
*   ✅ Admin/Manager can record manual payments.
*   ✅ Partial payments are not supported.
*   ✅ Processing status applies to ACH and 3D Secure payments.

**Client Portal:**

*   ✅ Clients view invoices in Client Portal → Project Details → Files/Documents.
*   ✅ Clients view payment schedule in Client Portal → Project Details → Finances.

**Finance Module:**

*   ✅ Billing page displays all invoices across projects.
*   ✅ Invoice rows are expandable to show payment schedule entries.
*   ✅ Deactivated tab shows deactivated invoices with Reactivate option.

**Multiple Invoices & Project Price:**

*   ✅ Multiple invoices can be created per project with no limit.
*   ✅ Invoices are associated at project level, not event level.
*   ✅ Invoice names are auto-generated from project name.
*   ✅ Total project price is calculated from sum of non-Deactivated/Voided/Cancelled invoices.
*   ✅ Project price recalculates when invoices are added, modified, or status changes.

**Overdue Reminders & Due Dates:**

*   ✅ Automatic reminder emails are sent for overdue transactions.
*   ✅ Reminders are per-transaction, not per-invoice.
*   ✅ Each transaction has its own due date based on payment schedule configuration.

**Client Data:**

*   ✅ Sent invoices retain client data as of send date (snapshot).
*   ✅ New invoices fetch current client information.

## **10\. Dependencies**

**Dependency Type**

**Dependency Name**

**Description**

**Impact if Unavailable**

Internal Module

Invoice Templates (FRDs #1-3)

Provides templates for invoice creation.

Cannot create invoices from templates.

Internal Module

Payment Schedule Templates (FRD #4)

Provides payment presets.

Cannot apply payment presets.

Internal Module

Proposal Module

Triggers auto-generation on contract signature.

No auto-generation from proposals.

Internal Module

Project Module

Provides project context and event dates.

Cannot associate invoices with projects.

Internal Module

Client Module

Provides client information for auto-population.

Must manually enter client details.

Internal Module

Brand Module

Provides branding for FROM section.

Must manually enter company details.

External

Stripe

Processes online payments.

Online payments unavailable; manual only.

External

Email Service

Sends invoice emails.

Cannot send invoices via email; copy link only.

Database

Invoices Table

Stores invoice data.

Cannot create or save invoices.

Database

Transactions Table

Stores payment schedule transactions.

Cannot track payment status.

Database

Projects Table

Links invoices to projects.

Cannot associate invoices with projects.

## **11\. References**

**Figma Designs:**

Copy 5. Use in project

# **FRD #5: Use Invoice in Project & Auto-Generation from Proposal**

**Version:** 1.1 **Date:** April 24, 2026 **Previous Version:** 1.0 (December 10, 2025)

**Change Log (v1.0 → v1.1):**

*   Added **Invoice Activity Page** functionality (Section 4.18), including Sender & Recipients, Payment Schedule view mode, and File Activity log.
*   **Status Lifecycle revised** from 9 statuses to 8: removed Processing, Failed, Cancelled; added Partially Paid, Partially Refunded; Voided is now user-initiated (Sections 4.6, 4.7).
*   **Permissions table updated** to remove "Cancel Invoice"; added "Void Invoice" and Activity Page permissions (Section 2).
*   **Edit-after-send rule** clarified: only Agency Owner and Admin can edit, only when status ∈ {Unpaid, Partially Paid, Overdue}, with auto-save and explicit "Update & Notify Client" action.
*   Sections 4.14, 6, 7, 8, 9 updated to reflect the new status set.

## **1\. Module Overview**

**Purpose:** This document defines how invoices are created, managed, and shared within projects. Users can create invoices by selecting from Published invoice templates, or invoices can be auto-generated when a client signs a contract (accepts a proposal). The module also covers invoice editing, sharing via email or link, status management, the Invoice Activity Page that appears once an invoice has been sent, and client access through the client portal.

**Business Goals:**

*   Streamline invoice creation within project workflows.  
    
*   Automate invoice generation from accepted proposals to reduce manual effort.  
    
*   Enable flexible payment collection through Stripe integration and manual recording.  
    
*   Provide clients with easy access to invoices and payment schedules via client portal.  
    
*   Track invoice and payment statuses across the organization.  
    
*   Provide agency users with an auditable activity record of every significant invoice event.  
    

**Scope:**

*   Invoice creation methods within projects (template selection, auto-generation).  
    
*   Invoice editor interface and editable fields.  
    
*   Share Invoice functionality (email with link, copy link).  
    
*   Invoice Activity Page (post-send view) including Sender & Recipients, Payment Schedule view mode, and File Activity log.  
    
*   Edit-after-send flow with "Update & Notify Client" action.  
    
*   Invoice status lifecycle and transitions.  
    
*   Payment tracking based on payment schedule transactions.  
    
*   Client portal invoice access.  
    
*   Finance module integration for centralized invoice management.  
    
*   Multiple invoices per project.  
    
*   Project total price calculation from invoices.  
    
*   Overdue reminders per transaction.  
    
*   Client data snapshot behavior.

## **2\. User Roles & Permissions**

**Permission**

**Agency Owner**

**Admin**

**Project Manager**

**Team Member**

**Client**

Create Invoice in Project

✅

✅

✅

✅

❌

Edit Invoice (Before Sending)

✅

✅

✅

✅

❌

Edit Invoice (After Sending — Unpaid / Partially Paid / Overdue)

✅

✅

❌

❌

❌

Edit Invoice (Paid / Refunded / Partially Refunded / Voided / Deactivated)

❌

❌

❌

❌

❌

Trigger "Update & Notify Client"

✅

✅

❌

❌

❌

Share Invoice

✅

✅

✅

❌

❌

Copy Invoice Link

✅

✅

✅

❌

❌

View Invoice in Project

✅

✅

✅

✅

❌

View Invoice Activity Page

✅

✅

✅

✅ (if attached to project)

❌

View File Activity Log

✅

✅

✅

✅ (if attached to project)

❌

Void Invoice

✅

✅

❌

❌

❌

Deactivate Invoice

✅

✅

❌

❌

❌

Reactivate Invoice

✅

✅

❌

❌

❌

Record Manual Payment ("Mark as Paid")

✅

✅

❌

❌

❌

View Invoice (Client Portal)

❌

❌

❌

❌

✅

Make Payment (Client Portal)

❌

❌

❌

❌

✅

**Permission Notes:**

*   Team Members can create and view invoices but cannot share, edit after send, void, deactivate, or record manual payments.  
    
*   Clients can only view invoices shared with them and make payments through the client portal. Clients never see the File Activity log.  
    
*   After an invoice is sent, only Agency Owner and Admin can make edits, and only while the invoice is Unpaid, Partially Paid, or Overdue.  
    
*   Edit Invoice and Share Invoice buttons on the Activity Page are **hidden entirely** (not greyed out) for users without permission.  
    
*   When the invoice is Deactivated or Voided, the Edit Invoice and Share Invoice buttons are **disabled** for all users.

## **3\. User Flow**

### 3.1 Create Invoice from Project Files/Documents Tab

*   The user navigates to Projects and selects a project.  
    
*   The user clicks the "Files/Documents" tab.  
    
*   The user clicks the "+" button next to "Documents."  
    
*   The system opens the Add New Document modal.  
    
*   The user selects the "Invoice" tab.  
    
*   The system displays a list of Published invoice templates with "Review & Send" buttons.  
    
*   The user can search for a specific template using the search field.  
    
*   The user clicks "Review & Send" on the desired template.  
    
*   The system creates a new invoice from the template and opens the Invoice Editor.  
    
*   Project and client data auto-populate into the invoice.  
    
*   The user reviews, makes any necessary edits, and proceeds to share.

### 3.2 Create Invoice from Project Management Panel

*   The user navigates to Projects and selects a project.  
    
*   The user locates the Project Management panel on the right side.  
    
*   The user clicks "CREATE FILE."  
    
*   The system opens the Add New Document modal with tabs: Local File, Invoice, Contract, Proposal, Questionnaire.  
    
*   The user selects the "Invoice" tab.  
    
*   The system displays a list of Published invoice templates.  
    
*   The user clicks "Review & Send" on the desired template.  
    
*   The system creates a new invoice and opens the Invoice Editor.

### 3.3 Create Invoice from Finance Tab

*   The user navigates to Projects and selects a project.  
    
*   The user clicks the "Finances" tab.  
    
*   The user clicks "Create Invoice" or a similar button.  
    
*   The system opens the template selection modal.  
    
*   The user selects a template and proceeds to the Invoice Editor.

### 3.4 Auto-Generate Invoice from Proposal

*   A client views a proposal sent to them.  
    
*   The client reviews the proposal details and accepts by signing the contract.  
    
*   Upon contract signature, the system automatically generates an invoice.  
    
*   The system uses the Pixally-wide default invoice template.  
    
*   The system maps all data from the proposal to the invoice: line items (packages/services), pricing, client information, and payment terms.  
    
*   The invoice is created with "Unpaid" status and associated with the project.  
    
*   The invoice appears in the project's Files/Documents tab.  
    
*   A notification is sent to the project team about the auto-generated invoice.

### 3.5 Review and Edit Invoice (Pre-Send)

*   The user opens an invoice from the Files/Documents tab or Finance tab.  
    
*   If the invoice has never been sent, the system opens the Invoice Editor.  
    
*   The user can modify: Title, Logo, Contact Information (FROM section), Line Items, Payment Terms, Tax, Discount, and Styling.  
    
*   The user cannot modify: Invoice Number (auto-generated) and Issued On date (system-generated).  
    
*   The user clicks "Preview" to review the final invoice appearance.  
    
*   The user clicks "Share Invoice" when ready to send.

### 3.6 Share Invoice via Email

*   The user clicks "Share Invoice" button in the Invoice Editor header or on the Activity Page.  
    
*   The system opens the Share Invoice modal.  
    
*   The "Email To" field is pre-populated with the client's email address.  
    
*   The user can add additional recipients by clicking the "+" button.  
    
*   The user enters a Subject line.  
    
*   The user types a message in the message body.  
    
*   A "Pay Invoice" button is automatically embedded in the email.  
    
*   The user can select an email template from the "Template" dropdown.  
    
*   The user can format text using the formatting toolbar (text style, links, attachments, etc.).  
    
*   The user clicks "Preview" to review the email before sending.  
    
*   The user clicks "Send" to send the invoice.  
    
*   The system sends an email with a link to the online invoice.  
    
*   The invoice status changes based on the payment schedule transaction statuses.

### 3.7 Copy Invoice Link

*   The user clicks "Share Invoice" button in the Invoice Editor header.  
    
*   The system opens the Share Invoice modal.  
    
*   The user clicks "Copy Link" at the bottom left of the modal.  
    
*   The system copies the invoice URL to the clipboard.  
    
*   A success message displays: "Link copied to clipboard."  
    
*   The user can share this link through any channel (chat, SMS, etc.).
*   The generated link remains valid until the invoice is Voided or Deactivated.

### 3.8 Client Views Invoice in Portal

*   The client receives an email with the invoice link.  
    
*   The client clicks the link or the "Pay Invoice" button.  
    
*   The system opens the invoice in the client portal.  
    
*   The client views the invoice details: line items, amounts, payment schedule.  
    
*   The client can also access the invoice from: Client Portal → Project Details → Files/Documents tab.  
    
*   The payment schedule is visible in: Client Portal → Project Details → Finances tab.

### 3.9 Client Makes Payment

*   The client views the invoice in the client portal.  
    
*   The client clicks "Pay" or a similar button for a payment entry.  
    
*   The system opens the payment interface (Stripe integration).  
    
*   The client enters payment details and completes the payment.  
    
*   The system updates the transaction status to "Paid."  
    
*   The invoice status updates based on all transaction statuses.

### 3.10 Record Manual Payment

*   The Agency Owner or Admin opens an invoice.  
    
*   The user navigates to the payment schedule section.  
    
*   The user clicks "Mark as Paid" or similar action on a payment entry.  
    
*   The system opens a modal to record payment details.  
    
*   The user enters payment amount, date, and method.  
    
*   The system updates the transaction status to "Paid."  
    
*   The invoice status updates based on all transaction statuses.

### 3.11 Open Activity Page for a Sent Invoice

*   The agency user navigates to Projects → \[Project Name\] → Files/Documents tab, or to the Finances tab.  
    
*   The user clicks on an invoice that has been sent at least once.  
    
*   The system opens the Invoice Activity Page (not the Invoice Editor).  
    
*   The user views the invoice title, status badge, Sender & Recipients, Payment Schedule, and File Activity log.

### 3.12 Edit a Sent Invoice and Notify Client

*   The Agency Owner or Admin opens the Activity Page for an invoice in Unpaid, Partially Paid, or Overdue status.  
    
*   The user clicks "Edit Invoice" in the header.  
    
*   The system opens the Invoice Editor.  
    
*   The user makes changes; changes are auto-saved as draft updates.  
    
*   The auto-saved changes do not affect the client view yet.  
    
*   The user clicks "Update & Notify Client."  
    
*   The system publishes the changes to the client view, sends a notification email to all existing recipients with the updated invoice link, and logs an "Invoice updated and sent" event in File Activity.  
    
*   The user is returned to the Activity Page.

**\*\*Exit Without Updating:\*\***

\* If the user has auto-saved changes and attempts to exit the Invoice Editor (via back arrow or by navigating away) without clicking "Update & Notify Client," the system displays the \*\*"Changes applied to file" modal\*\* (see Section 4.18.9).

\* The modal presents two options:

\* **Exit without updating** — closes the editor; changes remain saved as drafts but are not published to the client.

\* **Update & Notify Client** — opens the Share Invoice modal to proceed with notifying the client.

### 3.13 Share an Already-Sent Invoice with New Recipients

*   The user (Agency Owner, Admin, or Project Manager) opens the Activity Page.  
    
*   The user clicks "Share Invoice."  
    
*   The Share Invoice modal opens with previously used recipients pre-populated.  
    
*   The user adds one or more new recipients.  
    
*   The user clicks "Send."  
    
*   The new recipient is appended to the Sender & Recipients section.  
    
*   An "Invoice sent" event is logged.

### 3.14 Void an Invoice

*   The Agency Owner or Admin opens the Activity Page or accesses the invoice from Files/Documents.  
    
*   The user selects "Void Invoice" from the available actions.  
    
*   The system displays a confirmation prompt.  
    
*   Upon confirmation, the invoice status changes to Voided (terminal).  
    
*   The Edit Invoice and Share Invoice buttons are disabled.  
    
*   A "Voided" badge is displayed at the top of the Activity Page.  
    
*   An "Invoice voided" event is logged in File Activity.

## **4\. Functional Logic**

### 4.1 Invoice Creation Methods

#### **4.1.1 Template Selection Method**

*   Users create invoices by selecting from Published invoice templates.  
    
*   Only Published templates are displayed in the selection interface.  
    
*   Draft templates are not available for invoice creation.  
    
*   The selection interface displays template name and type ("Invoice Template").  
    
*   Each template row includes a "Review & Send" button.  
    
*   A search field allows filtering templates by name.

#### **4.1.2 Add New Document Modal**

*   The modal title displays: "Add New Document."  
    
*   Five tabs are displayed: Local File, Invoice, Contract, Proposal, Questionnaire.  
    
*   The "Invoice" tab displays the list of Published invoice templates.  
    
*   When "Local File" is selected, an upload interface is displayed for uploading external invoice files.  
    
*   The "Upload File" button is displayed at the bottom right.

#### **4.1.3 Auto-Generation Method**

*   Invoices are auto-generated when a client signs the contract within a proposal.  
    
*   Contract signing constitutes proposal acceptance.  
    
*   The system uses the Pixally-wide default invoice template configured in system settings.  
    
*   Auto-generation occurs immediately upon contract signature.  
    
*   No user intervention is required for auto-generation.

### 4.2 Data Mapping for Invoice Creation

#### **4.2.1 Project Data Auto-Population**

*   When an invoice is created within a project, the system automatically populates project-related data.  
    
*   The project name is associated with the invoice record.  
    
*   The project's primary event date is used for Smart Date calculations in payment terms.  
    
*   The project's brand settings are applied if the template uses brand colors/logo.

#### **4.2.2 Client Data Auto-Population**

*   The BILL TO section is populated with client information from the project.  
    
*   Client name is populated from the client record.  
    
*   Client email is populated from the client record.  
    
*   Client billing address is populated from the client's address details.  
    
*   If billing address is missing, the system displays a prompt to add the address.

#### **4.2.3 FROM Section Auto-Population**

*   The FROM section is populated with agency/company information.  
    
*   Company name is populated from the brand settings.  
    
*   Company email is populated from the brand settings.  
    
*   Company address can be added via "Add Address" link if not configured.

#### **4.2.4 Proposal Data Mapping (Auto-Generation)**

*   When auto-generating from a proposal, all proposal data is mapped to the invoice.  
    
*   Line items (packages, services) are copied with their descriptions, quantities, and prices.  
    
*   Payment terms from the proposal are copied to the invoice.  
    
*   Client information is inherited from the proposal.  
    
*   The total amount matches the proposal total.

### 4.3 Invoice Editor Interface

#### **4.3.1 Editor Layout**

*   The Invoice Editor follows the same layout as the Template Builder (FRD #2).  
    
*   A left sidebar displays the Invoice Structure with mandatory blocks: Logo, Title, Contact Information, Items, Payment Terms.  
    
*   The main canvas displays the invoice content in WYSIWYG format.  
    
*   Additional sidebar tabs are available: Colors, Fonts, Settings (TBD).

#### **4.3.2 Header Elements**

*   The header displays a Back arrow (←) for exiting the editor.  
    
*   The invoice name is displayed (e.g., "Blank Invoice") and can be edited inline.  
    
*   A status badge displays the current status (e.g., "Draft" in yellow/orange before first send).  
    
*   A three-dot menu (⋮) provides additional options.  
    
*   Icon buttons are displayed for additional actions (document, desktop view).  
    
*   A "Preview" button is displayed.  
    
*   A "Share Invoice" button (yellow/gold) is displayed on the far right (pre-send).  
    
*   An "Update & Notify Client" button is displayed on the far right (post-send, when unsaved edits exist).

#### **4.3.3 Editable Fields**

*   The user can edit all content fields including:  
    
*   Invoice title text  
    
*   Logo (upload different image)  
    
*   FROM section details (can add address)  
    
*   BILL TO section (if needed)  
    
*   Line items (add, edit, delete, reorder)  
    
*   Payment terms (add, edit, delete) — only on unpaid transactions when editing post-send  
    
*   Tax configuration  
    
*   Discount configuration  
    
*   Colors and fonts

#### **4.3.4 Non-Editable Fields**

*   Invoice Number is auto-generated by the system and cannot be modified.  
    
*   Issued On date is set to the current date when the invoice is created and cannot be modified.  
    
*   These fields are displayed but the input is disabled or read-only.

#### **4.3.5 Invoice Number Generation**

*   Invoice numbers are auto-generated in sequential format.  
    
*   The format follows: #INV\[NNNNN\] (e.g., #INV00001, #INV00002).  
    
*   The sequence is maintained across all invoices in the system.  
    
*   Invoice numbers are unique and never reused.

### 4.4 Share Invoice Modal

#### **4.4.1 Modal Structure**

*   The modal title displays: "Share Invoice."  
    
*   An X button in the top right closes the modal.  
    
*   The modal contains email configuration fields and action buttons.

#### **4.4.2 Email To Field**

*   The "Email To" label is displayed.  
    
*   The client's email is pre-populated as a chip/tag (e.g., "Emma Johnson ×").  
    
*   The × on the chip removes that recipient.  
    
*   A "+" button allows adding additional recipients.  
    
*   Multiple recipients can be added.

#### **4.4.3 Subject Field**

*   The "Subject" label is displayed.  
    
*   A text input field with placeholder "Enter the subject" is displayed.  
    
*   The subject is required before sending.

#### **4.4.4 Message Body**

*   A "Type your message" placeholder is displayed in the message area.  
    
*   A "Pay Invoice" button is displayed within the message area, indicating the button that will appear in the email.  
    
*   The message body supports rich text formatting.

#### **4.4.5 Formatting Toolbar**

*   A "Template" dropdown allows selection of pre-defined email templates.  
    
*   Formatting icons are displayed: Text formatting (A), Link (chain icon), Attachment (clip), Contact (person icon), and others.  
    
*   These tools allow customizing the email content.

#### **4.4.6 Action Buttons**

*   "Copy Link" is displayed at the bottom left.  
    
*   "Preview" button is displayed at the bottom right.  
    
*   "Send" button (yellow/gold) is displayed next to Preview.

### 4.5 Invoice Delivery

#### **4.5.1 Email Delivery**

*   Clicking "Send" sends an email to all recipients in the "Email To" field.  
    
*   The email contains the subject, message body, and a "Pay Invoice" button.  
    
*   The "Pay Invoice" button links to the online invoice in the client portal.  
    
*   The email does not include a PDF attachment; only the link is provided.

#### **4.5.2 Copy Link**

*   Clicking "Copy Link" generates and copies the invoice URL to the clipboard.  
    
*   The URL provides direct access to the online invoice.  
    
*   The link can be shared through any communication channel.  
    
*   The link remains valid until the invoice is voided or deactivated.

### 4.6 Invoice Status Lifecycle

#### **4.6.1 Status Overview**

*   Invoices have **eight** possible statuses: Unpaid, Partially Paid, Paid, Overdue, Partially Refunded, Refunded, Voided, and Deactivated.  
    
*   Invoice status is derived from the statuses of individual transactions in the payment schedule, except for Voided and Deactivated which are invoice-level user actions.  
    
*   Each payment entry in the schedule is tracked as a separate transaction.

#### **4.6.2 Unpaid Status**

*   An invoice is Unpaid when none of its transactions have been paid and none have passed their due date.  
    
*   This is the initial status for new invoices after creation.  
    
*   ACH and 3D Secure payments that are pending bank confirmation keep the invoice in Unpaid status (or Partially Paid if other transactions have completed) — there is no separate "Processing" status.  
    
*   The status badge displays "Unpaid" in gray.

#### **4.6.3 Partially Paid Status**

*   An invoice is Partially Paid the moment any single transaction transitions to Paid while at least one other transaction remains unpaid (and not yet refunded).  
    
*   If a subsequent payment attempt fails after the invoice has reached Partially Paid, the invoice **remains Partially Paid** — it does not revert to Unpaid.  
    
*   If some transactions are paid and others are past their due date, the invoice is Partially Paid (not Overdue), but the overdue transactions are flagged in the Payment Schedule table with a "Due" pill.  
    
*   The status badge displays "Partially Paid".

  
**Important — "Due" is transaction-level only:**

*   \* "**Due"** is exclusively a **transaction-level** display label and is **never** an invoice-level status.
*   \* An invoice is never labeled "Due" — it is labeled **"Overdue"** when all unpaid transactions are past due with no payments made, or **"Partially Paid"** when some transactions are paid and others are past due.
*   \* The "Due" pill (red) in the Payment Schedule table indicates an individual transaction that is unpaid and past its due date. The invoice-level status badge is computed independently per Section 4.7.3.

#### **4.6.4 Paid Status**

*   An invoice is Paid when all transactions in the payment schedule are paid.  
    
*   A Paid invoice cannot be edited.  
    
*   A Paid invoice can only transition to Partially Refunded or Refunded.  
    
*   The status badge displays "Paid" in green.

#### **4.6.5 Overdue Status**

*   An invoice is Overdue when no transactions have been paid and at least one transaction has passed its due date.  
    
*   The system automatically updates the status when a due date passes.  
    
*   An Overdue invoice can be edited (consistent with Section 4.18.6).  
    
*   An Overdue invoice transitions to Partially Paid or Paid as payments are received.  
    
*   The status badge displays "Overdue" in red.

#### **4.6.6 Partially Refunded Status**

*   An invoice is Partially Refunded when at least one paid transaction has been refunded, but at least one paid transaction has not been refunded.  
    
*   Refunds are processed through Stripe or recorded manually.  
    
*   The status badge displays "Partially Refunded".

#### **4.6.7 Refunded Status**

*   An invoice is Refunded when all paid transactions have been refunded.  
    
*   A Refunded invoice cannot be changed to any other status (terminal state).  
    
*   An Unpaid invoice cannot be Refunded (no payment to refund).  
    
*   The status badge displays "Refunded".

#### **4.6.8 Voided Status**

*   An invoice is Voided when the Agency Owner or Admin manually voids it, OR when the associated project is cancelled or deleted.  
    
*   A confirmation prompt is shown for user-initiated voiding.  
    
*   A Voided invoice cannot be changed to any other status (terminal state).  
    
*   The status badge displays "Voided" in gray.

#### **4.6.9 Deactivated Status**

*   An invoice is Deactivated when the Agency Owner or Admin deactivates it manually.  
    
*   Deactivated invoices can be reactivated, returning the invoice to its prior status.  
    
*   The status badge displays "Deactivated" with a "Reactivate" button.

#### **4.6.10 Removed Statuses (from v1.0)**

The following statuses from FRD v1.0 are **no longer supported**:

**Removed Status**

**Replacement / Handling**

Processing

ACH and 3D Secure payments stay Unpaid (or Partially Paid) until the bank/processor confirms; transaction then moves directly to Paid.

Failed

No longer a status. Failed Stripe attempts are logged as events in File Activity ("Payment failed for \[Client Name\]") but do not change invoice status; the transaction remains unpaid and the client can retry.

Cancelled

No longer a status. Users who need to stop an invoice use Deactivate (reversible) or Void (permanent) instead.

### 4.7 Status Transition Rules

#### **4.7.1 Allowed Transitions**

**From Status**

**To Status**

**Trigger**

Unpaid

Partially Paid

First transaction is paid

Unpaid

Paid

All transactions paid (single-transaction schedule)

Unpaid

Overdue

Any transaction passes its due date with no payments made

Unpaid

Voided

User voids manually, or project is cancelled/deleted

Unpaid

Deactivated

User deactivates manually

Partially Paid

Paid

All remaining transactions paid

Partially Paid

Partially Refunded

One or more paid transactions refunded

Partially Paid

Voided

User voids manually, or project is cancelled/deleted

Partially Paid

Deactivated

User deactivates manually

Overdue

Partially Paid

First transaction paid after invoice was overdue

Overdue

Paid

All transactions paid

Overdue

Voided

User voids manually, or project is cancelled/deleted

Overdue

Deactivated

User deactivates manually

Paid

Partially Refunded

Some paid transactions refunded

Paid

Refunded

All paid transactions refunded

Partially Refunded

Refunded

All remaining paid transactions refunded

Deactivated

Prior status

User reactivates (returns to non-deactivated status held just before deactivation)

#### **4.7.2 Terminal States**

*   **Refunded:** Cannot transition to any other status.  
    
*   **Voided:** Cannot transition to any other status.  
    
*   **Paid:** Can only transition to Partially Refunded or Refunded.

#### **4.7.3 Transaction-Based Status Calculation**

*   The invoice status is calculated based on the collective status of all transactions, with Voided and Deactivated overriding any calculation.  
    
*   If ALL transactions are Paid → invoice is Paid.  
    
*   If at least one transaction is Paid and at least one is unpaid (and not yet refunded) → invoice is Partially Paid.  
    
*   If no transactions are Paid and at least one is past due date → invoice is Overdue.  
    
*   If no transactions are Paid and none are past due date → invoice is Unpaid.  
    
*   If at least one paid transaction has been refunded and at least one paid transaction remains un-refunded → invoice is Partially Refunded.  
    
*   If all paid transactions have been refunded → invoice is Refunded.  
    
*   Voided and Deactivated are invoice-level statuses that override transaction calculations.

### 4.8 Payment Methods

#### **4.8.1 Online Payment (Stripe)**

*   Clients can pay invoices online through Stripe integration.  
    
*   Supported payment methods include credit/debit cards and ACH bank transfers.  
    
*   3D Secure authentication may be required for certain card payments.  
    
*   Online payments update transaction status automatically once the bank/processor confirms.

#### **4.8.2 Manual Payment Recording ("Mark as Paid")**

*   Agency Owner and Admin can record payments received outside the system using "Mark as Paid".  
    
*   Manual payment recording is used for cash, check, or other offline payment methods.  
    
*   The user enters payment amount, date, and method via the Mark as Paid modal.  
    
*   Manual recording updates the transaction status to Paid.  
    
*   Manual payments do not have a Payment ID; this column shows - in the Payment Schedule.
*   The detailed Mark as Paid modal field specification is provided in Section 5.4. For the full transactional handling and reconciliation logic of offline payments, refer to the \*\*Financial Management FRD\*

#### **4.8.3 Partial Payments**

*   Partial payments are not supported.  
    
*   Each transaction in the payment schedule must be paid in full.  
    
*   If a client pays less than the transaction amount, it is not recorded as a partial payment.

### 4.9 Client Portal Access

#### **4.9.1 Invoice Access**

*   Clients access invoices through the client portal.  
    
*   Invoices are visible in: Client Portal → Project Details → Files/Documents tab.  
    
*   The client can view invoice details, line items, and payment status.  
    
*   Clients **never** see the File Activity log or the agency-side Sender & Recipients section.

#### **4.9.2 Payment Schedule Access**

*   Clients view the payment schedule in: Client Portal → Project Details → Finances tab.  
    
*   The schedule displays each payment entry with due date, amount, and status.  
    
*   Clients can initiate payment for unpaid entries.

#### **4.9.3 Payment History**

*   Clients can view their payment history in the portal.  
    
*   Each payment shows date, amount, method, and status.

### 4.10 Finance Module Integration

#### **4.10.1 Billing Page**

*   The Finance module includes a Billing page accessible via: Finances → Billing.  
    
*   The Billing page has two tabs: Invoices and Transactions.  
    
*   The Invoices tab displays all invoices across all projects.

#### **4.10.2 Invoice Listing in Finance Module**

*   The listing displays columns: Next Payment Date, Invoice ID, Client, Amount, Status (or Payments count), Project, Actions.  
    
*   Invoices can be expanded to show individual payment schedule entries.  
    
*   Each entry shows: Date, Amount, Status.  
    
*   Filters include: All Brands dropdown, Search, and filter icon.  
    
*   Tabs include: All, Deactivated.  
    
*   Status filters reflect the 8 supported statuses.

#### **4.10.3 Expandable Invoice Rows**

*   Clicking the expand arrow (˅) on an invoice row reveals payment schedule details.  
    
*   Each payment entry is displayed as a sub-row.  
    
*   Sub-rows show: Date, Amount, Status (Paid/Due/Refunded).  
    
*   The collapse arrow (˄) hides the details.

#### **4.10.4 Deactivated Tab**

*   The Deactivated tab shows invoices with Deactivated status.  
    
*   A "Reactivate" button is displayed for each deactivated invoice.  
    
*   Clicking Reactivate restores the invoice to its previous active status.

### 4.11 Reactivate Invoice

#### **4.11.1 Reactivate Action**

*   The Reactivate button is displayed for Deactivated invoices only.  
    
*   Clicking Reactivate opens a confirmation prompt.  
    
*   Upon confirmation, the invoice returns to its previous status (Unpaid, Partially Paid, Overdue, etc.).  
    
*   A success message displays: "Invoice reactivated successfully."  
    
*   An "Invoice reactivated" event is logged in File Activity.

### 4.12 Key Business Rules

#### **4.12.1 Default Template Rule**

*   Auto-generated invoices use the Pixally-wide default invoice template.  
    
*   The default template is configured at the system level, not per-agency or per-brand.  
    
*   All auto-generated invoices have a consistent format.

#### **4.12.2 Contract Signature Trigger Rule**

*   Invoice auto-generation is triggered by contract signature within a proposal.  
    
*   Contract signature equals proposal acceptance.  
    
*   Auto-generation is immediate and automatic.

#### **4.12.3 Non-Editable Fields Rule**

*   Invoice Number and Issued On date are system-generated and cannot be modified.  
    
*   This ensures invoice integrity and audit compliance.

#### **4.12.4 Transaction-Based Status Rule**

*   Invoice status is derived from the statuses of all payment schedule transactions.  
    
*   Individual transactions are tracked separately.  
    
*   The invoice status reflects the aggregate state of its transactions, with Voided and Deactivated overriding the calculation.

#### **4.12.5 Terminal Status Rule**

*   Refunded and Voided are terminal statuses.  
    
*   Deactivated can be reactivated, returning the invoice to its prior status.  
    
*   Paid can only transition to Partially Refunded or Refunded.

#### **4.12.6 No Partial Payment Rule**

*   Each transaction must be paid in full.  
    
*   The system does not support partial payment recording.

#### **4.12.7 Edit-After-Send Rule**

*   After first send, only Agency Owner and Admin can edit the invoice.  
    
*   Editing is allowed only when the invoice is in Unpaid, Partially Paid, or Overdue status.  
    
*   Edits auto-save as drafts and require an explicit "Update & Notify Client" action to publish to the client.

### 4.13 Multiple Invoices per Project

#### **4.13.1 Multiple Invoice Support**

*   Users can create multiple invoices within a single project.  
    
*   There is no limit to the number of invoices that can be created per project.  
    
*   Each invoice is tracked independently with its own status, payment schedule, and transactions.  
    
*   All invoices for a project are displayed in the project's Files/Documents tab.

#### **4.13.2 Invoice-Project Association**

*   Invoices are associated at the project level only, not at the individual event level.  
    
*   Even if a project has multiple events (e.g., Rehearsal Dinner, Wedding, Engagement Photoshoot), the invoice is linked to the overall project.  
    
*   The invoice may include line items for multiple events, but the association remains project-level.

#### **4.13.3 Invoice Naming Convention**

*   Invoice names are auto-generated based on the project name.  
    
*   The naming format is: "Invoice-\[Project Name\]" (e.g., "Invoice-Rehearsal Dinner", "Invoice-Wedding").  
    
*   If multiple invoices exist for the same project, subsequent invoices may include a sequence number or timestamp.  
    
*   Users can edit the invoice name in the Invoice Editor if desired.

### 4.14 Project Price Calculation

#### **4.14.1 Total Project Price Derivation**

*   The total project price is derived from the sum of all invoice amounts associated with the project.  
    
*   Only invoices with active statuses are included in the calculation.  
    
*   Invoices with **Deactivated** or **Voided** status are excluded from the project total.  
    
*   The formula is: Total Project Price = Sum of (Invoice Total Amount) where Status NOT IN (Deactivated, Voided).

#### **4.14.2 Dynamic Recalculation**

*   The project total recalculates automatically when:  
    
*   A new invoice is created and sent.  
    
*   An existing invoice is modified (amount changes).  
    
*   An invoice status changes to Deactivated or Voided.  
    
*   A Deactivated invoice is reactivated.  
    
*   The updated total is reflected in the project's Finance tab and any related reports.

### 4.15 Overdue Reminders

#### **4.15.1 Automatic Reminder Emails**

*   The system sends automatic reminder emails for overdue transactions.  
    
*   Reminders are sent per transaction, not per invoice.  
    
*   If an invoice has multiple transactions and only one is overdue, the reminder is sent for that specific transaction only.

#### **4.15.2 Reminder Trigger**

*   A reminder is triggered when a transaction's due date passes without payment.
*   The reminder schedule (frequency, intervals, timing) is configured under \*\*Agency Setting →Notification \*\*.  
    
*   The system checks transaction due dates daily and sends reminders accordingly.  
    
*   Reminders are sent to the client's email address on file.

#### **4.15.3 Reminder Content**

*   The reminder email includes the transaction amount, original due date, and a link to pay.  
    
*   The "Pay Invoice" button in the email directs the client to the payment interface.  
    
*   Overdue reminder events are **not** logged in the File Activity log.

### 4.16 Transaction Due Dates

#### **4.16.1 Due Date Per Transaction**

*   Each transaction in the payment schedule has its own due date.  
    
*   The due date is determined based on the payment terms configuration (Smart Date, Invoice Date, Custom Date, or Event Date).  
    
*   There is no single "invoice due date"; each transaction is tracked independently.

#### **4.16.2 Smart Date Calculation**

*   For Smart Date configurations, the due date is calculated based on the project's event date or invoice sent date.  
    
*   Example: "4 Days before project date" calculates the due date as Event Date minus 4 days.  
    
*   The calculation occurs when the invoice is created or when the event date is set/updated.

### 4.17 Client Data Snapshot

#### **4.17.1 Data Retention for Sent Invoices**

*   Once an invoice is sent, it retains the client information that existed at the time of sending.  
    
*   If the client's email, address, or other details change after the invoice is sent, the sent invoice is not updated.  
    
*   This ensures invoice integrity and provides an accurate historical record.

#### **4.17.2 New Invoice Data Fetch**

*   When a new invoice is created, the system fetches the most current client information.  
    
*   Any updates to client details (email, billing address, name) are reflected in newly created invoices.  
    
*   Users should verify client information before sending if significant time has passed since data entry.

### 4.18 Invoice Activity Page

#### **4.18.1 Entry Conditions**

*   The Activity Page is displayed when the invoice has been sent to at least one recipient at least once.  
    
*   Before the first send, opening an invoice shows the Invoice Editor (Section 4.3).  
    
*   The Activity Page remains the default view for the remainder of the invoice's lifecycle, including after Deactivation and Voiding.  
    
*   There is no empty state for the Activity Page; the first event displayed in File Activity after first send is "Invoice sent to \[Recipient Name\]".

#### **4.18.2 Header Section**

*   A back arrow (←) is displayed on the far left for returning to Files/Documents or Finances.  
    
*   The invoice title is displayed next to the back arrow (e.g., Invoice "Jadon & Monika Wedding").  
    
*   The Status Badge is displayed immediately to the right of the invoice title, reflecting one of the 8 statuses defined in Section 4.6.  
    
*   Action buttons are displayed on the far right: "Edit Invoice" and "Share Invoice."  
    
*   The status badge is display-only and not interactive.

#### **4.18.3 Edit Invoice Button (Activity Page)**

*   The button is **visible only** to Agency Owner and Admin. It is hidden completely for Project Manager, Team Member, and Client.  
    
*   The button is **enabled** only when the invoice status is Unpaid, Partially Paid, or Overdue.  
    
*   The button is **disabled** when the invoice status is Paid, Partially Refunded, Refunded, Voided, or Deactivated.  
    
*   Clicking the button opens the Invoice Editor with all standard editor functionality.

#### **4.18.4 Share Invoice Button (Activity Page)**

*   The button is visible to Agency Owner, Admin, and Project Manager. Hidden for Team Member and Client.  
    
*   The button is **disabled** when the invoice status is Voided or Deactivated.  
    
*   Clicking the button opens the Share Invoice modal (Section 4.4) with previously used recipients pre-populated.

#### **4.18.5 Sender & Recipients Section**

**Section Structure:**

*   The section has no visible heading label; it is rendered as a list of rows at the top of the Activity Page body.  
    
*   The first row is always the sender row.  
    
*   Subsequent rows are recipient rows, one per recipient.  
    

**Sender Row:**

*   The sender is the agency user who originally clicked "Send" on the Share Invoice modal.  
    
*   The row displays: avatar with initials + sender name.  
    
*   For the viewer who is the sender, the row displays \[Sender Name\] (You).  
    
*   For other agency users viewing the page, the row displays just \[Sender Name\] without the "(You)" suffix.  
    
*   The sender row does **not** display a timestamp or status label.  
    
*   If the invoice is later re-sent (via "Update & Notify Client" or "Share Invoice"), the sender row continues to reflect the **original** sender. The re-send is logged in File Activity, but the displayed sender is immutable.  
    

**Recipient Rows:**

*   Each recipient added in the "Email To" field of the Share Invoice modal generates a recipient row.  
    
*   The row displays: avatar with initials + recipient name (or email if no contact match) + view status.  
    
*   If the recipient email matches a known client contact, the display name and avatar initials are sourced from the client record.  
    
*   If the recipient was added ad hoc (via the "+" button) and does not match a known contact, only the email address is displayed, with initials derived from the email local-part.  
    
*   The view status displays either:  
    *   "Last viewed \[date\] at \[time\]" — shown after the recipient opens the invoice link for the first time, and updated on each subsequent open.
    *   "Not viewed" — shown when the recipient has never opened the invoice link.
*   The timestamp reflects the **most recent** view by that recipient. If the invoice is edited and re-sent, the timestamp is not reset; it is overwritten when the recipient next views the invoice.  
    
*   If the invoice is re-shared and a new recipient is added, the new recipient is appended as an additional row. Existing recipients are not removed.  
    

**Timezone and Format:**

*   All timestamps are displayed in the agency's global timezone (configured in Agency Settings; a system default is always configured).  
    
*   Date format follows the design specification (e.g., "17 Dec 2024 at 1:31 PM").

#### **4.18.6 Payment Schedule Table (View Mode)**

**Table Structure:**

*   The table is displayed below the Sender & Recipients section.  
    
*   The section heading displays "Payment Schedule".  
    
*   The table is read-only. Rows and cells are not clickable and do not trigger actions.  
    

**Columns:**

**Column**

**Content**

**Format**

Amount

Transaction amount

Currency (e.g., $500.00)

Due Date

Scheduled due date per payment terms

Date (e.g., Jun 15, 2025)

Payment Date

Actual date payment was received or recorded

Date, or - if unpaid

Payment ID

Stripe transaction ID for online payments

Text, or - for manual payments and unpaid transactions

Status

Transaction-level status

Text pill

**Row Ordering:**

*   Rows are sorted chronologically by Due Date, **earliest first** at the top.  
    
*   Paid and due/overdue rows are interleaved by date; no separate grouping.  
    
*   The ordering does not change based on status.  
    

**Status Pill Values:**

*   **Paid** (green): Transaction has been paid (online or marked as paid).  
    
*   **Due** (red): Transaction is unpaid and has passed its due date (i.e., overdue at transaction level).  
    
*   **Refunded**: Transaction payment has been refunded.  
    

**Payment ID Handling:**

*   For **online payments** via Stripe, the Payment ID is the Stripe transaction identifier (e.g., #PAY-1147).  
    
*   For **manually recorded payments**, the Payment ID column displays -.  
    
*   For **unpaid transactions**, the Payment ID column displays -.  
    

**Sort and Filter:**

*   Sorting and filtering are **not** supported on this table in the Activity Page view.

#### **4.18.7 File Activity Log**

**Section Structure:**

*   The File Activity section is displayed below the Payment Schedule table.  
    
*   The section heading displays "File Activity".  
    
*   Events are listed as a vertical feed with a generic document icon, event description, and timestamp.  
    

**Visibility:**

*   The File Activity log is visible **only** to agency-side users attached to the project (Agency Owner, Admin, Project Manager, and Team Members attached to the project).  
    
*   Clients **never** see the File Activity log in the client portal.  
    
*   The log remains visible when the invoice status is Deactivated or Voided; in these cases, the status badge at the top reflects the state, and the log continues to display all historical events.  
    

**Event Ordering:**

*   Events are displayed in **reverse chronological order** (most recent event at the top).  
    
*   No day-level grouping or date separators are used; each entry displays its own full date/time.  
    

**Pagination:**

*   The log uses **infinite scroll**. As the user scrolls to the bottom of the loaded entries, the next batch is fetched and appended automatically.  
    
*   No "Load More" button is shown.  
    

**Event Entry Format:**

Each entry contains:

*   A generic document icon (no color or type differentiation).  
    
*   The event description (see Logged Event Types below).  
    
*   The event timestamp in the format shown in the design (e.g., "Jul 7, 2025 • 3:45 PM"), rendered in the agency's global timezone.  
    
*   No color coding is applied to entries regardless of event type.  
    

**Logged Event Types:**

The following events are logged in the File Activity log:

**#**

**Event Trigger**

**Log Entry Description**

1

Invoice is sent to one or more recipients (first send or subsequent re-send via Share Invoice)

"Invoice sent to \[Recipient Name or Email\]"

2

Recipient opens the invoice link for the **first time**

"Invoice viewed by \[Recipient Name or Email\]"

3

Agency user edits the invoice and clicks "Update & Notify Client"

"Invoice updated and sent by \[User Name\]"

4

Agency user edits the invoice (auto-saved changes) without triggering "Update & Notify Client"

"Invoice edited by \[User Name\]"

5

Client completes an online payment via Stripe

"Payment received from \[Client Name\]"

6

Agency user manually marks a transaction as paid (offline payment)

"Payment marked as paid by \[User Name\]"

7

A Stripe payment attempt fails

"Payment failed for \[Client Name\]"

8

Agency Owner or Admin voids the invoice

"Invoice voided by \[User Name\]"

9

Agency Owner or Admin deactivates the invoice

"Invoice deactivated by \[User Name\]"

10

Agency Owner or Admin reactivates a deactivated invoice

"Invoice reactivated by \[User Name\]"

**Not Logged:**

*   Invoice created (the Activity Page only appears after first send; creation happens in the Editor and is not part of the activity feed).  
    
*   Agency-side views of the invoice (only client views are logged).  
    
*   Overdue reminder emails sent to the client.  
    
*   Link copied to clipboard.  
    
*   Subsequent views by the same recipient after the first view (these are reflected in the Sender & Recipients "Last viewed" timestamp instead).  
    

**Actor Display Convention:**

*   When the actor of an event is the current viewer, their name is suffixed with "(You)" — e.g., "Invoice created by Aaron Ramsdale (You)" pattern, applied to all event types where applicable.  
    
*   When the actor is another agency user, the full name is displayed without suffix.  
    
*   When the actor is the client, the client's name is used as stored in the client record.  
    

**Event Immutability and Retention:**

*   Logged events are immutable. No user can edit or delete individual entries.  
    
*   If the invoice itself is deleted from Files & Documents, all associated File Activity entries are removed immediately. There is **no retention** of activity data after invoice deletion.

#### **4.18.8 Edit and Re-Notify Flow**

**When Edits Are Allowed:**

*   Editing post-send is allowed when the invoice status is Unpaid, Partially Paid, or Overdue.  
    
*   Editing is **not allowed** when the invoice status is Paid, Partially Refunded, Refunded, Voided, or Deactivated.  
    

**Who Can Edit:**

*   Only Agency Owner and Admin can edit an already-sent invoice.  
    
*   For unauthorized users, the Edit Invoice button is hidden completely.  
    

**Editable Fields Post-Send:**

*   All fields editable in the Editor remain editable post-send, except Invoice Number and Issued On date (Section 4.3.4).  
    
*   Payment schedule edits are allowed only on transactions that are still unpaid. Paid transactions cannot be modified.  
    

**Auto-Save Behavior:**

*   All edits made in the Editor are auto-saved as draft changes.  
    
*   Auto-saved edits are **not** immediately visible to the client. The client continues to see the previously sent version until the user clicks "Update & Notify Client."  
    
*   Each auto-save batch triggers an "Invoice edited" log entry. The exact batching interval is to be defined with engineering to avoid log spam on rapid edits.  
    

**Update & Notify Client Action:**

*   The "Update & Notify Client" button is displayed in the Editor when unsaved changes exist.  
    
*   Clicking the button:  
    *   Publishes the edited version to the client view.
    *   Sends a notification email to all existing recipients with the updated invoice link.
    *   Logs an "Invoice updated and sent" event in File Activity.
*   The notification email content and template are defined in the Email Templates module.

## **5\. Field Details & Validations**

### 5.1 Invoice Header Fields

**Field**

**Type**

**Required**

**Editable**

**Validation Rules**

**Error Message**

Invoice Number

Text

✅

❌

Auto-generated, unique

N/A

Invoice Name

Text

✅

✅

Cannot be empty

"Invoice name is required."

Issued On

Date

✅

❌

System-generated

N/A

Due Date

Date

✅

✅

Must be valid date

"Please select a valid due date."

### 5.2 Contact Information Fields

**Field**

**Type**

**Required**

**Editable**

**Validation Rules**

**Error Message**

FROM - Name

Text

✅

✅

Cannot be empty

"Company name is required."

FROM - Email

Email

✅

✅

Valid email format

"Please enter a valid email."

FROM - Address

Text

❌

✅

Optional

N/A

BILL TO - Name

Text

✅

✅

Cannot be empty

"Client name is required."

BILL TO - Email

Email

✅

✅

Valid email format

"Please enter a valid email."

BILL TO - Address

Text

✅

✅

Required for invoicing

"Client billing address is required."

### 5.3 Share Invoice Fields

**Field**

**Type**

**Required**

**Validation Rules**

**Error Message**

Email To

Email (multiple)

✅

At least one recipient

"Please add at least one recipient."

Subject

Text

✅

Cannot be empty

"Subject is required."

Message

Rich Text

❌

Optional

N/A

### 5.4 Activity Page — Sender & Recipients Fields

**Field**

**Type**

**Required**

**Editable**

**Validation Rules**

Sender Name

Text (derived)

✅

❌

Sourced from the user who first clicked Send

"(You)" suffix

Computed

❌

❌

Displayed only when current viewer = sender

Recipient Name / Email

Text (derived)

✅

❌

Sourced from client record or email input from Share modal

Recipient Avatar Initials

Computed

❌

❌

Derived from recipient name or email local-part

Last Viewed Timestamp

DateTime (derived)

❌

❌

Updated on each client view; displays "Not viewed" if never opened

### 5.5 Activity Page — Payment Schedule (View Mode) Fields

**Field**

**Type**

**Required**

**Editable**

**Validation Rules**

Amount

Currency

✅

❌

Sourced from payment schedule configuration

Due Date

Date

✅

❌

Sourced from payment terms (Smart Date, Custom Date, etc.)

Payment Date

Date

❌

❌

Populated when transaction is paid; shows - otherwise

Payment ID

Text

❌

❌

Stripe transaction ID for online payments; - for manual / unpaid

Status

Enum

✅

❌

One of: Paid, Due, Refunded

### 5.6 Activity Page — File Activity Fields

**Field**

**Type**

**Required**

**Editable**

**Validation Rules**

Event Icon

Icon (static)

✅

❌

Generic document icon for all entries

Event Description

Text (templated)

✅

❌

Format defined in Section 4.18.7

Event Timestamp

DateTime

✅

❌

Rendered in agency global timezone

Actor Name

Text

✅

❌

Suffixed with "(You)" when actor = current viewer

### 5.7 Activity Page Action Buttons

**Field**

**Visibility Rule**

**Enabled Rule**

Edit Invoice button

Visible only to Agency Owner and Admin

Enabled only when status ∈ {Unpaid, Partially Paid, Overdue}

Share Invoice button

Visible to Agency Owner, Admin, Project Manager

Enabled when status ∉ {Voided, Deactivated}

Update & Notify Client button (inside Editor)

Visible only when unsaved changes exist

Enabled when all required fields are valid

## **6\. Success Message Handling**

**Action**

**Success Message**

**Display Method**

**Duration**

**Post-Action Behavior**

Create Invoice

"Invoice created successfully."

Toast notification (green)

3 seconds

Opens Invoice Editor

Save Invoice

"Invoice saved successfully."

Toast notification (green)

3 seconds

Stays in editor

Send Invoice

"Invoice sent successfully."

Toast notification (green)

3 seconds

Modal closes; Activity Page becomes available

Update & Notify Client

"Invoice updated and sent successfully."

Toast notification (green)

3 seconds

Returns to Activity Page; event logged

Copy Link

"Link copied to clipboard."

Toast notification (green)

2 seconds

Link in clipboard

Void Invoice

"Invoice voided successfully."

Toast notification (green)

3 seconds

Status updates to Voided; buttons disabled

Deactivate Invoice

"Invoice deactivated successfully."

Toast notification (green)

3 seconds

Status updates

Reactivate Invoice

"Invoice reactivated successfully."

Toast notification (green)

3 seconds

Status updates to prior active state

Mark Payment as Paid

"Payment marked as paid successfully."

Toast notification (green)

3 seconds

Transaction status updates

Auto-Generate Invoice

"Invoice generated from proposal."

Toast notification (green)

3 seconds

Invoice appears in documents

Overdue Reminder Sent

"Overdue reminder sent to \[client name\]."

System log / Notification

N/A

Email delivered to client (not added to File Activity)

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Display Method**

**User Action Required**

Missing Client Email

"Client email is required to send invoice."

Toast notification (red)

Add client email

Missing Billing Address

"Client billing address is required."

Inline error

Add billing address

Missing Subject

"Subject is required."

Inline error

Enter subject

No Recipients

"Please add at least one recipient."

Toast notification (red)

Add email recipient

Payment Failed

"Payment failed. Please try again."

Toast notification (red)

Client retries payment

Invalid Email Format

"Please enter a valid email address."

Inline error

Correct email format

Network Error

"Failed to send. Please try again."

Toast notification (red)

Retry action

Cannot Edit Paid Invoice

"Paid invoices cannot be edited."

Toast notification (red)

No action available

Cannot Edit Voided/Deactivated Invoice

"This invoice can no longer be edited."

Toast notification (red)

Return to Activity Page

Cannot Refund Unpaid Invoice

"Cannot refund an unpaid invoice."

Toast notification (red)

No action available

Unauthorized Edit Attempt

"You do not have permission to edit this invoice."

Toast notification (red)

Return to Activity Page

Update & Notify Client — Network Failure

"Failed to update invoice. Please try again."

Toast notification (red)

Retry action

Update & Notify Client — Email Service Failure

"Invoice updated but notification failed to send. Please retry sending."

Toast notification (amber)

Manually re-share

File Activity Load Failure

"Unable to load activity history. Please refresh."

Inline message in File Activity section

Refresh page

Payment Schedule Load Failure

"Unable to load payment schedule."

Inline message in Payment Schedule section

Refresh page

Already Voided

"This invoice has already been voided."

Toast notification (red)

No action available

Already Deactivated

"This invoice is already deactivated."

Toast notification (red)

No action available

## **8\. Edge Cases**

**Edge Case**

**Description**

**Expected System Behavior**

Proposal Without Payment Terms

Proposal accepted but has no payment terms configured.

Auto-generated invoice uses default payment terms from template.

Client Without Billing Address

Invoice created for client without billing address.

System prompts user to add billing address before sending.

Project Deleted with Active Invoice

Project is deleted while invoice has unpaid status.

Invoice status changes to Voided automatically. Project total recalculates.

Send to Multiple Recipients

User adds multiple email recipients.

All recipients receive the email with invoice link. Each appears as a separate row in Sender & Recipients.

Link Shared Externally

Invoice link is shared to non-client recipient.

Link opens invoice view; payment requires client authentication.

Payment During Processing

Client attempts new payment while another is processing.

System prevents duplicate payment; shows "Payment in progress."

ACH Payment Pending Confirmation

ACH payment takes 3–4 days for bank confirmation.

Invoice remains Unpaid (or Partially Paid if other transactions complete); transaction moves directly to Paid on confirmation; no separate Processing status is shown.

Stripe Payment Fails Repeatedly

Client's card is declined multiple times.

Each failure logs a "Payment failed for \[Client\]" event in File Activity; invoice status stays Unpaid (or remains in current non-paid state).

Refund After Partial Schedule Paid

User initiates refund when only some payments are complete.

Refund applies to paid transactions only; invoice transitions to Partially Refunded.

Deactivate Then Reactivate

User deactivates and later reactivates an invoice.

Invoice returns to previous status; payment schedule preserved; project total recalculates.

Auto-Generate Default Template Missing

Default template not configured when proposal accepted.

System uses first available Published template or shows error.

All Invoices Deactivated/Voided

All invoices in a project are deactivated or voided.

Project total becomes $0.

Client Data Changed After Invoice Sent

Client email or address updated after invoice was sent.

Sent invoice retains original data. New invoices use updated data.

Multiple Overdue Transactions

Invoice has multiple transactions that become overdue.

Separate reminder email sent for each overdue transaction.

Event Date Changed After Invoice Created

Project event date updated after invoice with Smart Date terms created.

Transaction due dates may need manual recalculation or auto-update based on system configuration.

Invoice Name Collision

Multiple invoices auto-named from same project.

System appends sequence number or allows duplicate names.

Invoice Opened Before First Send

User clicks an invoice that has never been sent.

Opens Invoice Editor, not Activity Page.

Sender Leaves the Agency

Original sender's account is deactivated or removed.

Sender row continues to display the original sender's name; "(You)" suffix no longer applies to anyone.

Recipient Email Changes After Send

Client's email updated after invoice was already sent.

Sender & Recipients section retains the original email it was sent to. New sends use the updated email.

Recipient Opens Link on Multiple Devices

Client opens invoice on phone then laptop.

"Last viewed" updates to most recent view; "Invoice viewed" event is logged only on the first-ever view.

Invoice Re-Sent After Edit

User clicks "Update & Notify Client".

Existing recipient rows retain previous "Last viewed" timestamps; new views after re-send overwrite the timestamp. A new "Invoice updated and sent" event is logged.

New Recipient Added on Re-Share

User adds a new recipient via "+" in the Share modal.

New recipient row appended; "Not viewed" shown until first open; "Invoice sent to \[new recipient\]" logged.

Payment Completes While User Is Editing

Client pays a transaction while Admin is mid-edit.

Payment is recorded; transaction becomes Paid; auto-save continues on other fields; paid transaction cannot be edited further.

All Refunded While Partially Paid

Refund triggered on the only paid transaction of a Partially Paid invoice.

Invoice transitions to Refunded if no other paid transactions exist; otherwise Partially Refunded.

Invoice Deactivated While Client Viewing

Admin deactivates an invoice the client has open.

Client's next action (e.g., Pay) returns an error; link becomes inactive.

Voided Invoice's Activity Page

User opens Activity Page of a voided invoice.

Page renders with "Voided" badge; File Activity remains fully visible; Edit and Share buttons disabled.

Deactivated Invoice's Activity Page

User opens Activity Page of a deactivated invoice.

Page renders with "Deactivated" badge; File Activity remains fully visible; Edit and Share buttons disabled; Reactivate option available.

Invoice Deleted from Files & Documents

User deletes the invoice file.

Activity Page, File Activity log, and all associated data are removed immediately with no retention.

Agency Timezone Changes

Admin changes the global agency timezone setting.

All displayed timestamps render in the new timezone on next page load; stored timestamps remain unchanged (UTC).

Large Activity History

Long-running project generates 500+ events.

Infinite scroll loads in batches without performance degradation.

Concurrent Edits by Two Admins

Two admins open Editor simultaneously.

Last-write-wins per field on auto-save; "Update & Notify Client" sends the most recent state. Detailed conflict handling TBD with engineering.

Recipient Becomes Saved Contact Later

Ad-hoc email recipient is later added as a client contact.

Recipient row continues to show the email (historical snapshot); name is not retroactively applied.

## **9\. Acceptance Criteria**

**Invoice Creation:**

*   ✅ Users can create invoices from Project → Files/Documents → "+" → Invoice tab.  
    
*   ✅ Users can create invoices from Project Management panel → CREATE FILE → Invoice tab.  
    
*   ✅ Only Published templates are displayed in the template selection.  
    
*   ✅ "Review & Send" button opens the Invoice Editor with selected template.  
    
*   ✅ Project and client data auto-populate into the invoice.  
    

**Auto-Generation:**

*   ✅ Invoice is auto-generated when client signs contract (accepts proposal).  
    
*   ✅ Auto-generated invoice uses Pixally-wide default template.  
    
*   ✅ All proposal data (line items, pricing, payment terms, client info) maps to invoice.  
    
*   ✅ Auto-generated invoice appears in project's Files/Documents tab.  
    

**Invoice Editor:**

*   ✅ Editor displays same interface as Template Builder.  
    
*   ✅ User can edit all fields except Invoice Number and Issued On date.  
    
*   ✅ Invoice Number is auto-generated in format #INV\[NNNNN\].  
    
*   ✅ Preview button shows final invoice appearance.  
    
*   ✅ Share Invoice button opens sharing modal.  
    

**Share Invoice:**

*   ✅ Share modal pre-populates client email.  
    
*   ✅ User can add multiple recipients.  
    
*   ✅ Subject and message fields are available.  
    
*   ✅ "Pay Invoice" button is embedded in email.  
    
*   ✅ Copy Link copies invoice URL to clipboard.  
    
*   ✅ Send delivers email with link to online invoice.  
    

**Invoice Statuses:**

*   ✅ Eight statuses are supported: Unpaid, Partially Paid, Paid, Overdue, Partially Refunded, Refunded, Voided, Deactivated.  
    
*   ✅ Processing, Failed, and Cancelled statuses from v1.0 are removed.  
    
*   ✅ Invoice status is calculated from transaction statuses (with Voided/Deactivated overriding).  
    
*   ✅ Partially Paid applies the moment any transaction becomes Paid.  
    
*   ✅ Failed Stripe attempts are logged as events but do not change status.  
    
*   ✅ Paid invoices can only transition to Partially Refunded or Refunded.  
    
*   ✅ Refunded and Voided are terminal statuses.  
    
*   ✅ Voiding is user-initiated (Agency Owner / Admin) and also auto-triggered on project cancellation/deletion.  
    
*   ✅ Deactivated invoices can be reactivated.  
    

**Activity Page Entry:**

*   ✅ Activity Page is displayed when an invoice has been sent at least once.  
    
*   ✅ Before first send, opening the invoice shows the Editor.  
    

**Sender & Recipients Section:**

*   ✅ Sender row displays "(You)" suffix only for the original sender viewing the page.  
    
*   ✅ Sender row does not show timestamp or "Viewed" label.  
    
*   ✅ Each recipient is shown with avatar + name/email + "Last viewed" or "Not viewed".  
    
*   ✅ "Last viewed" reflects the most recent view by that recipient.  
    
*   ✅ Multiple recipients are shown as separate rows.  
    
*   ✅ Timestamps use the agency's global timezone.  
    

**Payment Schedule Table (View Mode):**

*   ✅ Displays Amount, Due Date, Payment Date, Payment ID, Status.  
    
*   ✅ Sorted chronologically by Due Date, earliest first.  
    
*   ✅ Payment Date and Payment ID show - for unpaid rows.  
    
*   ✅ Payment ID shows - for manually recorded payments.  
    
*   ✅ Table is view-only; no clicking, sorting, or filtering.  
    

**File Activity Log:**

*   ✅ Visible only to agency-side users attached to the project.  
    
*   ✅ Events displayed in reverse chronological order.  
    
*   ✅ Infinite scroll pagination.  
    
*   ✅ Each entry uses a generic document icon with no color coding.  
    
*   ✅ The 10 defined event types are logged as specified in Section 4.18.7.  
    
*   ✅ Client view events are logged only on first view per recipient.  
    
*   ✅ Agency-side views, overdue reminders, and link copies are not logged.  
    
*   ✅ Timestamps use the agency's global timezone.  
    
*   ✅ "(You)" suffix appears only when current viewer = actor.  
    

**Edit Invoice (Activity Page):**

*   ✅ Visible only to Agency Owner and Admin.  
    
*   ✅ Hidden completely for Project Manager and Team Member.  
    
*   ✅ Enabled only when status ∈ {Unpaid, Partially Paid, Overdue}.  
    
*   ✅ Disabled for Paid, Partially Refunded, Refunded, Voided, Deactivated.  
    

**Update & Notify Client Flow:**

*   ✅ Edits auto-save as drafts without affecting client view.  
    
*   ✅ "Update & Notify Client" publishes changes and sends notification email.  
    
*   ✅ Triggers "Invoice updated and sent" log entry.  
    

**Deactivated / Voided State:**

*   ✅ Activity Page renders with the appropriate status badge.  
    
*   ✅ Edit and Share buttons are disabled.  
    
*   ✅ File Activity remains fully visible.  
    

**Retention:**

*   ✅ Deleting an invoice from Files & Documents immediately removes all associated Activity Page data (no retention).

**Payments:**

*   ✅ Clients can pay online via Stripe.  
    
*   ✅ Agency Owner / Admin can record manual payments via "Mark as Paid".  
    
*   ✅ Partial payments are not supported.  
    
*   ✅ ACH and 3D Secure payments stay Unpaid (or Partially Paid) until bank confirms.  
    

**Client Portal:**

*   ✅ Clients view invoices in Client Portal → Project Details → Files/Documents.  
    
*   ✅ Clients view payment schedule in Client Portal → Project Details → Finances.  
    
*   ✅ Clients do not see the File Activity log.  
    

**Finance Module:**

*   ✅ Billing page displays all invoices across projects.  
    
*   ✅ Invoice rows are expandable to show payment schedule entries.  
    
*   ✅ Deactivated tab shows deactivated invoices with Reactivate option.  
    
*   ✅ Status filters reflect the 8 supported statuses.  
    

**Multiple Invoices & Project Price:**

*   ✅ Multiple invoices can be created per project with no limit.  
    
*   ✅ Invoices are associated at project level, not event level.  
    
*   ✅ Invoice names are auto-generated from project name.  
    
*   ✅ Total project price is calculated from sum of non-Deactivated/Voided invoices.  
    
*   ✅ Project price recalculates when invoices are added, modified, or status changes.

**Overdue Reminders & Due Dates:**

*   ✅ Automatic reminder emails are sent for overdue transactions.  
    
*   ✅ Reminders are per-transaction, not per-invoice.  
    
*   ✅ Each transaction has its own due date based on payment schedule configuration.  
    
*   ✅ Overdue reminders are not logged in File Activity.  
    

**Client Data:**

*   ✅ Sent invoices retain client data as of send date (snapshot).  
    
*   ✅ New invoices fetch current client information.

## **10\. Dependencies**

**Dependency Type**

**Dependency Name**

**Description**

**Impact if Unavailable**

Internal Module

Invoice Templates (FRDs #1-3)

Provides templates for invoice creation.

Cannot create invoices from templates.

Internal Module

Payment Schedule Templates (FRD #4)

Provides payment presets.

Cannot apply payment presets.

Internal Module

Proposal Module

Triggers auto-generation on contract signature.

No auto-generation from proposals.

Internal Module

Project Module

Provides project context and event dates.

Cannot associate invoices with projects.

Internal Module

Client Module

Provides client information for auto-population and recipient name resolution.

Must manually enter client details; recipients display as raw email.

Internal Module

Brand Module

Provides branding for FROM section and avatar/display names.

Must manually enter company details; generic placeholder avatars.

Internal Module

Agency Settings

Provides global timezone for timestamp rendering.

Timestamps fall back to system default.

Internal Module

Email Templates

Provides notification email template for "Update & Notify Client".

Notification emails cannot be sent.

External

Stripe

Processes online payments and provides Payment IDs.

Online payments unavailable; manual only; no Payment IDs.

External

Email Service

Sends invoice emails.

Cannot send invoices via email; copy link only.

External

Event Tracking Service

Tracks first-view events on invoice links.

Client view events cannot be logged; "Not viewed" shown indefinitely.

Database

Invoices Table

Stores invoice data.

Cannot create or save invoices.

Database

Transactions Table

Stores payment schedule transactions.

Cannot track payment status.

Database

Projects Table

Links invoices to projects.

Cannot associate invoices with projects.

Database

Invoice Activity Log Table

Stores File Activity entries.

File Activity log cannot be persisted or displayed.

Database

Invoice Recipients Table

Stores recipient records with last-viewed timestamps.

Sender & Recipients section cannot render.

## **11\. References**

**Figma Designs:**

*   Invoice Activity Page — "Jadon & Monika Wedding" reference screen (Apr 24, 2026).

**Open Items for Design / Engineering Confirmation:**

*   Exact label and visual treatment of "Update & Notify Client" button inside the Editor.  
    
*   Transaction-level status pill for "upcoming but not yet due" entries (not visible in current design).  
    
*   Auto-save batching interval for "Invoice edited" events (to avoid log spam on rapid edits).  
    
*   Infinite scroll batch size for File Activity.  
    
*   Concurrent edit conflict handling between two agency users.  
    
*   Delivery-failure (bounce) event format in File Activity.  
    

☑️ 6. Edit Sent Invoice

# **Functional Requirements Document (FRD)**

## **Invoices Module**

## **1\. Module Overview**

The Invoices module is a comprehensive billing and payment management system within the CRM that enables users to create, manage, and track invoices for projects and services. The module intelligently handles payment schedules based on project event dates, automatically adjusts payment terms, and enforces business rules to maintain data integrity and ensure proper payment tracking. The system supports flexible payment scheduling options and provides real-time payment status visibility.

**Key Capabilities:**

*   Create and manage invoices with automatic/manual payment schedules
*   Track payment status and pending balances
*   Restrict editing of fully paid invoices
*   Allow editing of invoices with pending balance
*   Auto-recalculate payment schedules when invoice amounts change
*   Prevent past-date selection after primary event has passed
*   Support both smart dates (relative) and event dates (absolute) for payment scheduling
*   Enforce future-date-only scheduling after event completion

## **2\. User Roles & Permissions**

**Role**

**Create Invoice**

**Edit Invoice**

**Edit Payment Schedule**

**View Invoice**

**Delete Invoice**

**Change Payment Status**

**Admin**

✓

✓ (if not fully paid)

✓ (future dates only after event)

✓

✓

✓

**Project Manager**

✓

✓ (if not fully paid)

✓ (future dates only after event)

✓

✗

✗

**Finance Manager**

✓

✓ (if not fully paid)

✓ (future dates only after event)

✓

✓

✓

**Client/Stakeholder**

✗

✗

✗

✓ (view only)

✗

✗

## **3\. User Flow**

### 3.1 Invoice Creation Flow

Start → Select Project/Event → Choose Invoice Type →

Enter Invoice Details (Items, Amounts) → Select Payment Schedule Option →

(Smart Dates / Event Date / Manual Date Selection) →

Review & Confirm → Invoice Created Successfully

#### **3.1.1 Standard Invoice Creation (Event Date Not Passed)**

1.  User navigates to Invoices section
2.  Clicks "Create Invoice" button
3.  Selects associated project and primary event date is auto-populated
4.  Adds invoice line items (deliverables/charges with amounts)
5.  Chooses payment schedule option:
    *   **Smart Dates (Auto-Preset):** System displays preset options (e.g., Net-30, Net-60, etc.) calculated from primary event date
    *   **Event Date:** System uses primary event date as the base for payment calculation
    *   **Manual Date Selection:** User manually selects specific payment dates from calendar
6.  Confirms and creates invoice
7.  System generates initial payment schedule with due dates

#### **3.1.2 Invoice Creation After Primary Event Has Passed**

1.  User navigates to Invoices section for a project where primary event has passed
2.  Clicks "Create Invoice" button
3.  Selects associated project
4.  Adds invoice line items
5.  **Smart Dates option is DISABLED** (greyed out with hover message: "Event has passed — you must select a current or future date")
6.  **Event Date option is DISABLED** (greyed out with same hover message)
7.  User is required to manually select payment dates from calendar
8.  Calendar blocks all past dates; only today and future dates are selectable
9.  Confirms and creates invoice with manually selected schedule

### 3.2 Invoice Editing Flow

#### **3.2.1 Fully Paid Invoice**

1.  User views invoice with status "Fully Paid"
2.  **No Edit button is displayed** for the invoice
3.  Invoice details are in read-only mode
4.  User can only view invoice and payment history

#### **3.2.2 Invoice with Pending Balance**

1.  User views invoice with pending balance remaining
2.  **Edit button is visible**
3.  User clicks Edit button
4.  Can modify:
    *   Invoice line items (deliverables/charges)
    *   Item quantities and amounts
    *   Invoice total amount
5.  System automatically recalculates payment schedule based on new amount
6.  If new deliverable is added **after primary event date has passed:**
    *   New payment schedule must be created for the new amount
    *   User must select a future date (today onwards) for this new schedule
    *   Past dates cannot be selected
7.  User confirms changes
8.  Invoice is updated with new payment schedule

### 3.3 Payment Schedule Management Flow

#### **3.3.1 Edit Existing Payment Schedule (Event Not Passed)**

1.  User views invoice with pending payment schedule
2.  Clicks edit on payment schedule installment/dates
3.  Can modify due dates using Smart Dates, Event Date, or Manual date selection
4.  All date options are available and enabled
5.  User confirms changes

#### **3.3.2 Edit Existing Payment Schedule (Event Has Passed)**

1.  User views invoice with pending payment schedule
2.  Event date has already passed
3.  Clicks edit on payment schedule installment/dates
4.  **Smart Dates dropdown is DISABLED** (greyed out, hover shows: "Event has passed — you must select a current or future date")
5.  **Event Date dropdown is DISABLED** (greyed out, same hover message)
6.  Only manual date selection is available
7.  Calendar date picker blocks all past dates
8.  User can only select today's date or any future date
9.  User confirms changes with new future date

### 3.4 Payment Tracking Flow

1.  User views invoice dashboard
2.  Invoices display payment status: Not Started, In Progress, Fully Paid
3.  Pending balance is clearly visible
4.  Payment schedule shows upcoming due dates
5.  User can track payment history and adjustments

## **4\. Functional Logic**

### 4.1 Invoice Status & Editability Logic

**Fully Paid Invoice State:**

*   When all payment schedule installments are marked as paid (or total payments = invoice amount)
*   Invoice enters "Fully Paid" status
*   **Edit button is completely hidden** (not disabled, not visible at all)
*   Invoice becomes read-only
*   Payment schedule becomes read-only
*   No modifications allowed to any invoice field

**Pending Balance State:**

*   When invoice has not received full payment (remaining balance > 0)
*   Invoice status shows "In Progress" or pending amount
*   **Edit button is visible and enabled**
*   User can modify:
    *   Line items (add, remove, update)
    *   Item amounts and quantities
    *   Entire invoice amount
    *   Payment schedule dates (subject to event date restrictions)
*   Changes trigger automatic payment schedule recalculation

### 4.2 Automatic Payment Schedule Recalculation Logic

**When Invoice Amount Changes (During Edit):**

1.  User modifies invoice line items or amounts
2.  System calculates new invoice total
3.  System automatically recalculates entire payment schedule:
    *   **If original schedule was Smart Dates:** Recalculates using same preset intervals from primary event date
    *   **If original schedule was Event Date:** Recalculates using same event date calculation
    *   **If original schedule was Manual Dates:** Proportionally adjusts installment amounts across existing due dates (dates remain same, amounts redistribute)
4.  New schedule is presented for confirmation
5.  User can accept or manually adjust before saving

**Example Recalculation Scenario:**

*   Original invoice: $10,000, Net-30 from event (event date: Jan 1)
*   Original schedule: 3 installments of $3,333.33 due on Jan 31, Feb 28, Mar 31
*   User edits invoice to $15,000
*   System recalculates: 3 installments of $5,000 due on Jan 31, Feb 28, Mar 31 (same dates, new amounts)

### 4.3 Event Date Logic & Restrictions

**Primary Event Date Definition:**

*   Every project has a primary event date (project completion, milestone date, delivery date)
*   This date is used as the base reference for all payment schedule calculations

**Smart Dates Auto-Preset Behavior:**

*   Smart Dates represent relative payment terms (e.g., Net-30, Net-60, Net-90)
*   Smart Dates are calculated as: **Number of days before or after the Primary Event Date**
*   Example: Net-30 after event = Primary Event Date + 30 days
*   When Smart Dates option is selected during invoice creation/editing, system automatically applies the preset intervals from the primary event date

**Event Date Selection Behavior:**

*   When "Event Date" option is selected, system uses the Primary Event Date as the payment due date reference
*   Payment schedules created with Event Date option are calculated relative to the Primary Event Date
*   All installments are distributed around the Primary Event Date according to the selected payment terms

**Event Date Passed - Restrictions Applied:**

*   **When Primary Event Date < Today's Date:**
    *   Smart Dates dropdown becomes DISABLED and greyed out
    *   Event Date dropdown becomes DISABLED and greyed out
    *   Hover message displayed: **"Event has passed — you must select a current or future date."**
    *   User is forced to use Manual Date Selection only
    *   Calendar date picker automatically blocks all past dates
    *   Only today's date and future dates are selectable

**Example Scenario - Event Date Impact:**

*   Primary Event Date: January 15, 2024
*   Today's Date: January 20, 2024 (event has passed)
*   User creates new invoice:
    *   Smart Dates disabled ✗
    *   Event Date disabled ✗
    *   Must select manually from calendar starting Jan 20 onwards
    *   Cannot select any date before Jan 20

### 4.4 New Deliverables After Event Date Has Passed

**Scenario: Adding New Charge/Deliverable to Existing Invoice After Event**

1.  User opens existing invoice for a project where primary event has passed
2.  Clicks Edit Invoice
3.  Adds new line item (new deliverable or charge)
4.  Invoice amount increases
5.  System detects that:
    *   Primary event date has passed
    *   New amount needs new payment schedule
6.  **New payment schedule must be created** for the additional amount:
    *   Separate schedule line item for the new charge
    *   Future date selection only (today onwards)
    *   Past dates completely blocked in calendar
7.  User selects future date for the new schedule
8.  System creates new payment schedule installment(s) with future date
9.  Original payment schedule remains unchanged (unless user explicitly modifies it)
10.  Invoice now has multiple payment schedules:
     *   Original schedule with original dates/amounts
     *   New schedule with future dates for new charges

**Business Rule:**

*   A new deliverable/charge added after the event date cannot use Smart Dates or Event Date options
*   User must manually assign future dates only
*   This ensures clarity and prevents accidental past-date scheduling

### 4.5 Payment Schedule Editing - Date Restrictions After Event

**For Existing Payment Schedule Installments:**

**Scenario A: Primary Event NOT Passed**

*   User can edit existing installment dates
*   All three options available:
    *   Smart Dates (enabled)
    *   Event Date (enabled)
    *   Manual Date Selection (enabled)
*   Date picker allows any valid date

**Scenario B: Primary Event HAS Passed**

*   User can still edit existing installment dates
*   BUT with restrictions:
    *   **Smart Dates:** DISABLED, greyed out
    *   **Event Date:** DISABLED, greyed out
    *   Hover message: "Event has passed — you must select a current or future date."
    *   **Manual Date Selection:** ENABLED (only option)
*   Calendar date picker:
    *   Blocks all dates before today
    *   Allows today and all future dates
    *   User must select from available range

**Business Rule:**

*   Once the primary event has passed, no payment schedules can be set for past dates
*   This maintains accuracy of payment tracking and prevents data inconsistency
*   Users retain flexibility to adjust schedule to future dates

### 4.6 Invoice Amount Modification Impact

**When User Modifies Invoice Amount:**

1.  Calculation of difference (original vs. new amount)
2.  If amount decreases:
    *   Proportional reduction across all installments
    *   Payment schedule restructured with new amounts
    *   Due dates may be recalculated based on original schedule type
3.  If amount increases:
    *   Proportional increase across all installments
    *   OR new schedule created for additional amount (if after event date)
4.  System updates total invoice amount
5.  Pending balance is recalculated
6.  Payment status may change based on existing payments

### 4.7 Business Rules Summary

**Rule**

**Behavior**

**Fully Paid Invoice**

Edit button hidden; read-only mode; no modifications allowed

**Pending Balance Invoice**

Edit button visible; can modify items, amounts, and schedule

**Auto-Recalculation**

Triggered on invoice amount change; redistributes across same dates or creates new schedule

**Event Passed - Creation**

Smart Dates and Event Date options disabled; manual selection only; past dates blocked

**Event Passed - Editing**

Smart Dates and Event Date disabled; manual selection only; past dates blocked

**New Charge After Event**

New payment schedule required; future dates only

**Date Selection**

Past dates never allowed; today and future dates always available when manual selection required

## **5\. Field Details & Validations**

### 5.1 Invoice Header Fields

**Field**

**Type**

**Required**

**Validation**

**Notes**

**Invoice Number**

Text (Auto-generated)

Yes

Unique, sequential

System auto-generates; read-only

**Project**

Dropdown

Yes

Must be valid project

Links to primary event date

**Invoice Date**

Date

Yes

Today or earlier

Cannot be future date

**Invoice Status**

Dropdown (Read-only)

Yes

Not Started, In Progress, Fully Paid

Auto-calculated based on payments

**Event Date**

Date (Read-only)

Yes

Inherited from project

Used for payment schedule calculation

**Invoice Type**

Dropdown

Yes

Service, Product, Mixed

Categorizes invoice purpose

**Description**

Text Area

No

Max 500 characters

Additional invoice details

**Currency**

Dropdown

Yes

Valid currency code

Default from project settings

### 5.2 Invoice Line Items

**Field**

**Type**

**Required**

**Validation**

**Notes**

**Deliverable/Charge Name**

Text

Yes

Max 255 characters

Description of item

**Quantity**

Number

Yes

\> 0, decimal allowed

Can be fractional

**Unit Price**

Currency

Yes

\> 0, 2 decimal places

Price per unit

**Amount**

Currency (Auto-calculated)

Yes

Quantity × Unit Price

Read-only, auto-calculated

**Tax (if applicable)**

Percentage

No

0-100%

Applied to amount

**Notes**

Text Area

No

Max 300 characters

Line-item specific notes

### 5.3 Payment Schedule Fields

**Field**

**Type**

**Required**

**Validation**

**Notes**

**Schedule Type**

Dropdown

Yes

Smart Dates, Event Date, Manual

Determines date selection method

**Smart Date Preset**

Dropdown (Conditional)

Conditional

Net-30, Net-60, Net-90, etc.

Only if Smart Dates selected; **DISABLED after event passes**

**Event Date Option**

Checkbox (Conditional)

Conditional

Relative to Primary Event Date

**DISABLED after event passes**

**Due Date**

Date

Yes

Today or future (if event passed)

Calendar picker; **past dates blocked after event**

**Amount**

Currency

Yes

\> 0, 2 decimal places

Installment amount

**Status**

Dropdown (Read-only)

Yes

Not Due, Due, Overdue, Paid

Auto-updated based on actual payments

**Notes**

Text Area

No

Max 300 characters

Payment schedule notes

### 5.4 Conditional Field Display Logic

**Smart Dates Dropdown:**

*   **Visible & Enabled:** If primary event date > today OR during initial creation
*   **Visible & DISABLED (Greyed Out):** If primary event date < today
*   **Hover State:** When disabled, shows tooltip: "Event has passed — you must select a current or future date."

**Event Date Option:**

*   **Visible & Enabled:** If primary event date > today OR during initial creation
*   **Visible & DISABLED (Greyed Out):** If primary event date < today
*   **Hover State:** When disabled, shows tooltip: "Event has passed — you must select a current or future date."

**Manual Date Selection Calendar:**

*   **Always Visible:** When selected as schedule type
*   **Past Dates:** Always blocked/unclickable (greyed out in calendar picker)
*   **Today & Future Dates:** Always selectable
*   **Highlight:** Today's date may be highlighted for easy reference

## **6\. Error Message Handling**

### 6.1 Validation Error Messages

**Scenario**

**Error Message**

**Placement**

**Severity**

**Missing Required Field**

"\[Field Name\] is required."

Below field

Error (Red)

**Invoice Amount = 0**

"Invoice amount must be greater than 0."

Below total field

Error (Red)

**Invoice Date in Future**

"Invoice date cannot be in the future."

Below date field

Error (Red)

**Payment Amount > Remaining**

"Payment amount cannot exceed remaining balance of \[Amount\]."

Below payment field

Error (Red)

**Payment Date in Past**

"Payment date cannot be earlier than today."

Below date field

Error (Red)

**Duplicate Invoice Number**

"This invoice number already exists. Please try again."

Top of form

Error (Red)

**Invalid Currency Format**

"Please enter a valid currency amount (e.g., 1,000.00)."

Below field

Error (Red)

### 6.2 Operational Warning Messages

**Scenario**

**Warning Message**

**Placement**

**Severity**

**Editing Fully Paid Invoice**

"This invoice is fully paid and cannot be edited."

Invoice header banner

Warning (Orange)

**Event Date Passed - Schedule Creation**

"Event has passed — you must select a current or future date."

Hover on disabled dropdowns

Info (Blue)

**Adding New Charge After Event**

"New deliverables added after the event date require a separate future-dated payment schedule."

Above new schedule section

Warning (Orange)

**Decreasing Invoice Amount**

"Decreasing the invoice amount may affect payment calculations. Review the payment schedule below."

Below amount field

Info (Blue)

**Schedule Date Conflicts**

"The selected date conflicts with an existing payment due date. Consider adjusting."

Below date field

Warning (Orange)

**Large Pending Balance**

"This invoice has a pending balance of \[Amount\]. Consider creating a payment reminder."

Invoice summary section

Info (Blue)

### 6.3 Success Messages

**Scenario**

**Success Message**

**Placement**

**Duration**

**Invoice Created**

"Invoice \[Invoice #\] created successfully."

Top of page toast

3 seconds

**Invoice Updated**

"Invoice \[Invoice #\] updated successfully. Payment schedule recalculated."

Top of page toast

3 seconds

**Payment Recorded**

"Payment of \[Amount\] recorded successfully."

Top of page toast

3 seconds

**Schedule Updated**

"Payment schedule updated successfully."

Top of page toast

3 seconds

**Multiple Schedules Created**

"Invoice created with \[Number\] payment schedules."

Top of page toast

3 seconds

### 6.4 Disabled State Messaging (Hover Tooltips)

**When Smart Dates Dropdown is Disabled (Event Passed):**

Message: "Event has passed — you must select a current or future date."

Display: Tooltip on hover

Icon: Info icon (i) next to field label

Background: Greyed out dropdown

Text Color: Muted/disabled color

**When Event Date Option is Disabled (Event Passed):**

Message: "Event has passed — you must select a current or future date."

Display: Tooltip on hover

Icon: Info icon (i) next to field label

Background: Greyed out checkbox/option

Text Color: Muted/disabled color

## **7\. Edge Cases**

### 7.1 Date-Related Edge Cases

**Edge Case 1: Event Date is Today**

*   **Scenario:** Primary event date = today's date
*   **Behavior:** Smart Dates and Event Date options remain enabled (today is not "passed")
*   **User Can:** Select payment dates from today onwards using all three options
*   **Resolution:** Tomorrow onwards starts the "event passed" restriction period

**Edge Case 2: Multiple Invoices for Same Event on Different Dates**

*   **Scenario:** User creates Invoice A on Jan 10 (event on Jan 20), then creates Invoice B on Jan 25 (same event date Jan 20 - now passed)
*   **Behavior:** Invoice A allows all schedule options; Invoice B restrictions apply
*   **Resolution:** Each invoice independently evaluates primary event date status

**Edge Case 3: Editing Payment Schedule After One Installment is Paid**

*   **Scenario:** 3-installment payment schedule; first installment paid; user edits second installment date
*   **Behavior:**
    *   First installment (paid) becomes read-only; cannot edit
    *   Second and third installments (pending) can be edited
    *   Recalculation redistributes remaining balance across unpaid installments
*   **Resolution:** Only pending/unpaid schedule items are editable

**Edge Case 4: Timezone Issues with Event Date**

*   **Scenario:** User in timezone A; project event date created in timezone B
*   **Behavior:** Event date is stored in UTC; compared to current date in user's timezone
*   **Resolution:** System converts to user's local timezone for "today" comparison

### 7.2 Amount & Calculation Edge Cases

**Edge Case 5: Invoice Amount = Payment Amount (Exact Match)**

*   **Scenario:** Invoice for $1,000 with single payment of $1,000
*   **Behavior:** Upon payment, invoice status changes to "Fully Paid"; edit button disappears
*   **Resolution:** Clear status transition; no remaining balance

**Edge Case 6: Decimal Precision in Recalculation**

*   **Scenario:** Invoice of $100 split into 3 equal installments
*   **Behavior:** Results in $33.33, $33.33, $33.34 (to avoid rounding errors)
*   **Resolution:** System applies rounding rules: last installment absorbs remainder

**Edge Case 7: Currency Conversion Changes During Invoice Lifecycle**

*   **Scenario:** Invoice created in USD; currency conversion rates change before payment
*   **Behavior:** Original invoice amount remains unchanged; conversion rates at payment time apply
*   **Resolution:** Currency locked at invoice creation; payment conversion is separate calculation

**Edge Case 8: Zero-Amount Line Item**

*   **Scenario:** User enters line item with $0 amount
*   **Behavior:** System prevents save; shows error "Amount must be greater than 0"
*   **Resolution:** User must enter valid amount or delete line item

### 7.3 Schedule Flexibility Edge Cases

**Edge Case 9: Manual Schedule with All Dates in Future**

*   **Scenario:** Event passed; user manually selects all schedule dates far in future (e.g., 1 year out)
*   **Behavior:** System allows selection; generates schedule with future dates
*   **Resolution:** No validation error; system respects user's date selection (business judgment)

**Edge Case 10: Changing Schedule Type Mid-Edit**

*   **Scenario:** Invoice created with Smart Dates; user edits and switches to Manual Date Selection
*   **Behavior:** Original Smart Dates are replaced; new dates must be manually selected
*   **Resolution:** User must confirm the schedule type change before saving

**Edge Case 11: Adding New Charge on Last Day Before Event**

*   **Scenario:** Event date is tomorrow; user adds new charge today
*   **Behavior:** Can use all three schedule options (Smart Dates, Event Date, Manual)
*   **Resolution:** Restriction only applies after event has passed

**Edge Case 12: Adding New Charge One Second After Event**

*   **Scenario:** Event completed at 11:59:59 PM; user adds charge at 12:00:00 AM next day
*   **Behavior:** Immediate switch to manual-date-only mode
*   **Resolution:** System evaluates event status in real-time; no grace period

### 7.4 User Action Edge Cases

**Edge Case 13: Rapid Sequential Edits**

*   **Scenario:** User makes multiple edits to invoice amount within seconds
*   **Behavior:** Each edit triggers recalculation; system queues updates; final state reflects last saved version
*   **Resolution:** Last-write-wins; previous unsaved edits discarded

**Edge Case 14: Attempting to Edit Fully Paid Invoice**

*   **Scenario:** User somehow accesses invoice URL or makes API call for fully paid invoice
*   **Behavior:** System prevents edit; read-only mode enforced; no edit button visible
*   **Resolution:** Backend validates permission; frontend doesn't display edit option

**Edge Case 15: Concurrent Payments During Edit**

*   **Scenario:** User A editing invoice schedule; User B recording payment simultaneously
*   **Behavior:** System locks invoice during edit; prevents concurrent modifications
*   **Resolution:** Last successful action wins; user receives notification to refresh and retry

**Edge Case 16: Deleting Invoice with Partial Payment**

*   **Scenario:** User attempts to delete invoice with pending balance but some payments recorded
*   **Behavior:** System prevents deletion; shows message "Cannot delete invoice with payment history"
*   **Resolution:** Invoice must be archived or marked void; not deleted

### 7.5 Display & UI Edge Cases

**Edge Case 17: Very Long Invoice Description**

*   **Scenario:** User enters 500 character description
*   **Behavior:** Text displays with word wrapping; no overflow issues
*   **Resolution:** Character counter prevents exceeding limit

**Edge Case 18: Many Line Items in Single Invoice**

*   **Scenario:** Invoice with 50+ line items
*   **Behavior:** Interface remains responsive; line items display with pagination or scrolling
*   **Resolution:** UI handles large data sets gracefully

**Edge Case 19: Payment Schedule with 12+ Installments**

*   **Scenario:** Invoice split into monthly payments for 12+ months
*   **Behavior:** All installments visible; can be edited individually
*   **Resolution:** Scrollable list or expandable sections maintain usability

**Edge Case 20: Disabled Dropdown Interaction**

*   **Scenario:** User hovers over disabled Smart Dates dropdown
*   **Behavior:** Tooltip appears with message; dropdown does not open; selection unchanged
*   **Resolution:** Visual and textual feedback provided; no dropdown expansion

## **8\. Acceptance Criteria**

### 8.1 Invoice Creation & Basic Functionality

*   \[ \] User can create new invoice with project, items, and amounts
*   \[ \] Invoice date defaults to today and cannot be set to future dates
*   \[ \] Invoice number auto-generates and is unique
*   \[ \] Calculation of total invoice amount from line items is correct
*   \[ \] Invoice status is set to "Not Started" upon creation

### 8.2 Payment Schedule Creation (Event Not Passed)

*   \[ \] User can select Smart Dates option with preset intervals
*   \[ \] User can select Event Date option based on primary event date
*   \[ \] User can manually select specific dates from calendar
*   \[ \] Smart Dates calculates as number of days before/after primary event date
*   \[ \] Event Date uses primary event date as reference point
*   \[ \] All three options are enabled and functional

### 8.3 Payment Schedule Creation (Event Passed)

*   \[ \] Smart Dates dropdown is greyed out and disabled
*   \[ \] Event Date checkbox is greyed out and disabled
*   \[ \] Hover over disabled options shows message: "Event has passed — you must select a current or future date."
*   \[ \] Manual date selection is the only available option
*   \[ \] Calendar date picker blocks all past dates (greyed out, unclickable)
*   \[ \] User can only select today's date and future dates

### 8.4 Invoice Editing (Fully Paid)

*   \[ \] Edit button is completely hidden for fully paid invoices
*   \[ \] Invoice displays "Fully Paid" status
*   \[ \] User cannot access edit form for fully paid invoices
*   \[ \] All invoice fields are in read-only mode
*   \[ \] Read-only mode is visually distinct (greyed out or locked appearance)

### 8.5 Invoice Editing (Pending Balance)

*   \[ \] Edit button is visible and enabled for invoices with pending balance
*   \[ \] User can modify line items (add, remove, update)
*   \[ \] User can modify item amounts and quantities
*   \[ \] User can modify invoice total amount
*   \[ \] Changes trigger automatic payment schedule recalculation
*   \[ \] Recalculated schedule maintains original payment dates when using Smart Dates or Manual
*   \[ \] Recalculated amounts are proportionally redistributed across installments

### 8.6 New Deliverable After Event

*   \[ \] User can add new line item to existing invoice
*   \[ \] If event has passed, new charge requires new payment schedule
*   \[ \] New payment schedule uses future dates only
*   \[ \] System prevents use of Smart Dates or Event Date for new charge
*   \[ \] User must manually select date from calendar (blocked past dates)
*   \[ \] New schedule is displayed separately from original schedule
*   \[ \] Invoice reflects total of original plus new charges

### 8.7 Payment Schedule Editing (Pending Schedules)

*   \[ \] User can edit due dates of pending payment schedule installments
*   \[ \] If event not passed: all three options (Smart Dates, Event Date, Manual) are enabled
*   \[ \] If event passed: only Manual date selection is available
*   \[ \] Smart Dates dropdown shows disable message and hover tooltip when past event
*   \[ \] Event Date dropdown shows disable message and hover tooltip when past event
*   \[ \] Calendar blocks past dates when event has passed
*   \[ \] User can select only today and future dates

### 8.8 Error Handling & Validation

*   \[ \] Required fields show validation errors if empty
*   \[ \] Currency amounts must be > 0 or show error
*   \[ \] Invoice date cannot be in future (validation error shown)
*   \[ \] Duplicate invoice numbers are prevented (validation error shown)
*   \[ \] Payment amount cannot exceed remaining balance (validation error shown)
*   \[ \] All error messages are clear and actionable

### 8.9 Disabled State UX

*   \[ \] Disabled dropdowns appear greyed out visually
*   \[ \] Disabled checkboxes appear greyed out visually
*   \[ \] Hover over disabled elements shows tooltip with explanation
*   \[ \] Users cannot interact with or select disabled options
*   \[ \] No click or keyboard access to disabled options

### 8.10 Success Messages

*   \[ \] Invoice creation shows success message with invoice number
*   \[ \] Invoice update shows success message including "payment schedule recalculated"
*   \[ \] Payment recording shows success message with amount
*   \[ \] Messages display for 3 seconds then auto-dismiss
*   \[ \] Messages are non-intrusive (toast notification style)

### 8.11 Date Logic Consistency

*   \[ \] Primary event date is correctly inherited from project
*   \[ \] System compares event date to current date accurately
*   \[ \] Timezone differences don't affect event-passed determination
*   \[ \] All date comparisons are consistent across module
*   \[ \] Date calculations are accurate for payment schedules

### 8.12 Data Integrity

*   \[ \] Payment schedules remain consistent after invoice edit
*   \[ \] Paid installments are never modified
*   \[ \] Original amounts are preserved in payment history
*   \[ \] Invoice audit trail shows all modifications
*   \[ \] Calculations always balance (no rounding discrepancies > $0.01)

## **9\. Dependencies**

### 9.1 System Dependencies

*   **Project Module:** Primary event date must be defined in project
*   **Payment Module:** Actual payment recording against invoices
*   **User Authentication:** Role-based access control for edit/delete permissions
*   **Notification Module:** Payment reminders and status notifications
*   **Reporting Module:** Invoice analytics and financial reports
*   **Currency Module:** Multi-currency support and conversion rates

### 9.2 Data Dependencies

*   **Project Master Data:** Event date, project status, project details
*   **User Master Data:** User roles, permissions, user profiles
*   **Currency Configuration:** Valid currencies, exchange rates (for reporting)
*   **Payment Configuration:** Payment methods, terms definitions

### 9.3 Integration Points

*   **API Integration:** External accounting systems (via payment module)
*   **Email Notifications:** Invoice creation/update confirmations
*   **Calendar Integration:** Event dates synchronized from project calendar
*   **Dashboard:** Invoice summary widgets showing pending amounts
*   **Export Functionality:** Invoice export to PDF, Excel formats

### 9.4 External Dependencies

*   **Calendar Component:** Date picker library supporting date range blocking
*   **Currency Conversion API:** Real-time currency exchange rates
*   **PDF Generation Library:** Invoice PDF export functionality

## **10\. References**

### 10.1 Related Modules

*   **Project Management Module:** \[Link to Project FRD\]
*   **Payment Processing Module:** \[Link to Payment FRD\]
*   **Financial Reporting Module:** \[Link to Reporting FRD\]
*   **User Management Module:** \[Link to User FRD\]

### 10.2 Business Rules Documents

*   **Payment Terms Policy:** \[Internal documentation\]
*   **Event Date Definition Standards:** \[Internal documentation\]
*   **Invoice Numbering Convention:** \[Internal documentation\]
*   **Currency & Localization Policy:** \[Internal documentation\]

### 10.3 UI/UX Standards

*   **Design System:** \[Link to design tokens/guidelines\]
*   **Form Validation Patterns:** \[Link to validation standards\]
*   **Error Message Standards:** \[Link to error message guidelines\]
*   **Accessibility Guidelines:** \[WCAG 2.1 AA compliance\]

### 10.4 Compliance & Regulations

*   **Financial Compliance:** Local accounting standards (GAAP/IFRS)
*   **Data Privacy:** GDPR/CCPA compliance for invoice data
*   **Audit Requirements:** Invoice history and modification tracking

### 10.5 System Architecture

*   **Database Schema:** Invoice, InvoiceLineItem, PaymentSchedule tables
*   **API Endpoints:** /api/invoices, /api/payments, /api/schedules
*   **Frontend Framework:** \[Framework details\]
*   **Backend Services:** \[Service architecture\]

## **Document Control**

**Version**

**Date**

**Author**

**Changes**

1.0

\[Current Date\]

\[Author Name\]

Initial FRD creation with updated invoice editing and payment schedule logic

1.1

TBD

TBD

Event date restriction refinements

**Status:** Ready for Review  
**Last Updated:** \[Current Date\]  
**Next Review Date:** \[Date + 30 days\]

☑️ 7. Invoice Module Integrations

# **FRD #7: Invoice Module Integrations**

**Version:** 1.0  
**Date:** December 10, 2025

## **1\. Module Overview**

**Purpose:  
**This document provides detailed documentation of how the Invoice Module integrates with other modules in the Pixally CRM system. It covers data flows, triggers, dependencies, and synchronization rules between the Invoice Module and Proposal, Project, Client, Stripe, Email, Finance, Client Portal, Automations, Reports, QuickBooks, and Calendar modules.

**Business Goals:**

*   Ensure seamless data flow between invoices and other system modules.
*   Automate invoice generation from accepted proposals.
*   Synchronize financial data across Finance, Reports, and QuickBooks.
*   Provide clients with consistent invoice access across email and portal.
*   Enable workflow automations triggered by invoice events.

**Scope:**

*   Proposal Module Integration (auto-generation, data mapping)
*   Project Module Integration (association, project total calculation)
*   Client Module Integration (data population)
*   Stripe Integration (payments, tax, refunds, webhooks)
*   Email Integration (notifications, reminders)
*   Finance Module Integration (Billing, Transactions)
*   Client Portal Integration (access, payments)
*   Automations Integration (triggers, workflows)
*   Reports Integration (financial reports)
*   QuickBooks Integration (sync)
*   Calendar Integration (due dates)

## **2\. Integration Summary Matrix**

**Integration**

**Direction**

**Trigger**

**Data Flow**

Proposal → Invoice

Inbound

Contract signed

Auto-generate invoice

Project ↔ Invoice

Bidirectional

Invoice create/update

Project total, event dates

Client → Invoice

Inbound

Invoice create

Client info population

Stripe ↔ Invoice

Bidirectional

Payment events

Payment processing, status updates

Email ← Invoice

Outbound

Various triggers

Notifications, reminders

Finance ← Invoice

Outbound

Invoice/transaction events

Billing, P&L data

Client Portal ↔ Invoice

Bidirectional

Invoice share, payment

View, pay, history

Automations ← Invoice

Outbound

Invoice events

Workflow triggers

Reports ← Invoice

Outbound

Data aggregation

Financial reports

QuickBooks ← Invoice

Outbound

Transaction events

Accounting sync

Calendar ← Invoice

Outbound

Payment schedule

Due date display

## **3\. Proposal Module Integration**

### 3.1 Overview

The Proposal Module triggers automatic invoice generation when a client signs the contract (accepts the proposal). The invoice inherits all financial data from the proposal including line items, payment terms, discounts, and tax settings.

### 3.2 Auto-Generation Trigger

#### **3.2.1 Trigger Event**

*   Invoice auto-generation is triggered when the client signs the contract within a proposal.
*   Contract signature constitutes proposal acceptance.
*   The trigger is immediate upon signature completion.
*   No user intervention is required.

#### **3.2.2 Trigger Conditions**

**Condition**

**Requirement**

Proposal Status

Must be "Sent"

Contract

Must be signed by client

Payment Terms

Must be configured in proposal

Client Info

Must be complete

### 3.3 Data Mapping: Proposal to Invoice

#### **3.3.1 Line Items Mapping**

**Proposal Source**

**Invoice Destination**

**Mapping Rule**

Selected Packages

Invoice Line Items

Each package becomes a line item group

Package Line Items

Invoice Line Items

Individual services within packages

Selected À La Carte Items

Invoice Line Items

Each selected add-on becomes a line item

Item Name

Line Item Name

Direct copy

Item Description

Line Item Description

Direct copy

Item Quantity

Line Item Quantity

Direct copy (including client-selected quantities)

Item Price

Line Item Price

Direct copy

Item Tax Toggle

Line Item Tax Toggle

Inherits taxable setting

#### **3.3.2 Line Item Structure Example**

**Proposal Selection:**

*   Package: "Photo/Video Bronze" ($3,500)
    *   Wedding: 10 hours of photoshooting, Basic Retouch, 1 Photographer
    *   Rehearsal Dinner: 10 hours of photoshooting
*   À La Carte: "Extra Hour" x 2 ($100/hour)
*   À La Carte: "Drone Footage" ($500)

**Invoice Line Items Generated:**

**Line Item**

**Description**

**Qty**

**Price**

**Tax**

Photo/Video Bronze

Wedding package

1

$3,500

✅

→ 10 hours of photoshooting

Wedding

\-

\-

\-

→ Basic Retouch

Wedding

\-

\-

\-

→ 1 Photographer

Wedding

\-

\-

\-

→ 10 hours of photoshooting

Rehearsal Dinner

\-

\-

\-

Extra Hour

Additional coverage

2

$200

✅

Drone Footage

Aerial videography

1

$500

✅

#### **3.3.3 Payment Terms Mapping**

**Proposal Source**

**Invoice Destination**

**Mapping Rule**

Payment Schedule

Payment Terms

Direct copy of all entries

Payment Entry Amount

Transaction Amount

Copy amount or percentage

Payment Entry Due Date

Transaction Due Date

Copy date type and configuration

Smart Date Settings

Smart Date Calculation

Inherits calculation rules

Payment Type (Custom/Percentage/Equal)

Payment Type

Direct copy

#### **3.3.4 Financial Data Mapping**

**Proposal Source**

**Invoice Destination**

**Mapping Rule**

Subtotal

Invoice Subtotal

Calculated from line items

Discount Type

Discount Type

Bundle or Regular

Discount Amount

Discount Amount

Flat amount or percentage

Discount Scope

Discount Application

Packages only OR Packages + À La Carte

Tax Setting

Tax Configuration

Auto (Stripe) or Manual rate

Total

Invoice Total

Calculated: (Subtotal - Discount) + Tax

#### **3.3.5 Client Information Mapping**

**Proposal Source**

**Invoice Destination**

Client Name

BILL TO - Name

Client Email

BILL TO - Email

Client Phone

BILL TO - Phone

Client Company

BILL TO - Company

Client Billing Address

BILL TO - Address

### 3.4 Proposal Reference on Invoice

#### **3.4.1 Source Metadata**

*   Auto-generated invoices include a "Source" field in metadata.
*   Format: "Source: Proposal - \[Proposal Name\]"
*   This field is stored in the invoice record for tracking.

#### **3.4.2 Clickable Link**

*   The invoice displays a clickable link to the source proposal.
*   Link location: Invoice details/metadata section.
*   Clicking the link opens the signed proposal in view mode.
*   Link is visible to agency users only, not clients.

#### **3.4.3 Auto-Generated Badge**

*   Auto-generated invoices display a badge/tag: "Auto-generated from Proposal"
*   Badge is visible in the invoice listing and invoice editor header.
*   Badge differentiates auto-generated invoices from manually created ones.

### 3.5 Default Template Usage

#### **3.5.1 Template Selection**

*   Auto-generated invoices use the Pixally-wide default invoice template.
*   The default template is configured at the system level.
*   All auto-generated invoices have consistent formatting.

#### **3.5.2 Template Override**

*   Users can edit the auto-generated invoice after creation.
*   Styling, line items, and payment terms can be modified.
*   Original proposal data is preserved in audit trail.

## **4\. Project Module Integration**

### 4.1 Overview

Invoices are associated with projects at the project level. The Project Module provides context for invoice creation (event dates, brand) and receives financial aggregation (project total).

### 4.2 Invoice-Project Association

#### **4.2.1 Association Level**

*   Invoices are associated at the project level, not event level.
*   A project can have multiple invoices.
*   Each invoice tracks its project association.

#### **4.2.2 Invoice Naming**

*   Invoice names are auto-generated from the project name.
*   Format: "Invoice-\[Project Name\]" (e.g., "Invoice-Rehearsal Dinner")
*   Users can rename invoices in the editor.

#### **4.2.3 Line Item Event References**

*   Invoice line items may reference specific events (e.g., "Wedding," "Rehearsal Dinner").
*   These references are inherited from package event types.
*   The invoice itself remains project-level despite event-specific line items.

### 4.3 Project Total Calculation

#### **4.3.1 Calculation Formula**

Project Total = SUM(Invoice Total)

WHERE Invoice Status NOT IN (Deactivated, Voided, Cancelled)

#### **4.3.2 Included Invoices**

**Invoice Status**

**Included in Total?**

Unpaid

✅

Processing

✅

Paid

✅

Overdue

✅

Failed

✅

Refunded

✅

Deactivated

❌

Voided

❌

Cancelled

❌

#### **4.3.3 Display Location**

*   Project total is displayed in: Project → Finances Tab.
*   The total updates in real-time when invoice amounts or statuses change.

#### **4.3.4 Recalculation Triggers**

*   New invoice created and sent.
*   Existing invoice amount modified.
*   Invoice status changes to Deactivated, Voided, or Cancelled.
*   Deactivated invoice is reactivated.

### 4.4 Event Date for Smart Date Calculation

#### **4.4.1 Primary Event Date**

*   Smart Date calculations use the project's primary event date.
*   If a project has multiple events, the primary event date is used.
*   Primary event is designated in project setup.

#### **4.4.2 Smart Date Examples**

**Configuration**

**Primary Event Date**

**Calculated Due Date**

7 days before project date

Dec 20, 2025

Dec 13, 2025

4 days after project date

Dec 20, 2025

Dec 24, 2025

On invoice sent date

\-

Date of sending

### 4.5 Invoice Access in Project

#### **4.5.1 Files/Documents Tab**

*   All project invoices appear in: Project → Files/Documents tab.
*   Invoices are listed alongside other documents (proposals, contracts, questionnaires).
*   Table columns: Name, Type, Created, Sent To, Actions.

#### **4.5.2 Finances Tab**

*   Payment schedule summary displayed in: Project → Finances tab.
*   Shows all transactions across all project invoices.
*   Displays payment status, due dates, and amounts.

## **5\. Client Module Integration**

### 5.1 Overview

The Client Module provides client information that populates into invoices. Data flows from the client record to the invoice BILL TO section.

### 5.2 Client Data Population

#### **5.2.1 Fields Populated**

**Client Field**

**Invoice Field**

**Required**

Client Name

BILL TO - Name

✅

Client Email

BILL TO - Email

✅

Client Phone

BILL TO - Phone

❌

Client Company

BILL TO - Company

❌

Billing Address

BILL TO - Address

✅

#### **5.2.2 Primary Client Selection**

*   If a project has multiple clients, the primary client's information is used.
*   Primary client is designated in project setup.
*   Secondary clients do not populate into invoice BILL TO section.

### 5.3 Data Snapshot Behavior

#### **5.3.1 Sent Invoice Data**

*   Once an invoice is sent, client information is snapshotted.
*   Changes to the client record after sending do NOT update the sent invoice.
*   This preserves invoice integrity for records.

#### **5.3.2 New Invoice Data**

*   When a new invoice is created, current client information is fetched.
*   Any updates to client details are reflected in new invoices.
*   Users should verify client information before sending.

## **6\. Stripe Integration**

### 6.1 Overview

Stripe provides payment processing, tax calculation, refund processing, and real-time status updates via webhooks. The integration supports credit/debit cards, ACH bank transfers, and manual payment recording.

### 6.2 Payment Processing

#### **6.2.1 Supported Payment Methods**

**Payment Method**

**Description**

**Processing Time**

Credit/Debit Card

Visa, Mastercard, Amex, etc.

Instant

ACH Bank Transfer

US bank account direct debit

3-4 business days

Mark as Paid

Manual recording for offline payments

Instant

#### **6.2.2 Payment Flow**

1.  Client clicks "Pay" on a transaction in the client portal.
2.  System opens Stripe payment interface.
3.  Client enters payment details.
4.  Stripe processes the payment.
5.  Stripe sends webhook to Pixally.
6.  Pixally updates transaction status.
7.  Invoice status recalculates based on all transactions.

#### **6.2.3 3D Secure Handling**

*   For cards requiring 3D Secure authentication, status is "Processing" during verification.
*   Upon successful authentication, status updates to "Paid."
*   Upon failed authentication, status updates to "Failed."

### 6.3 Stripe Tax Integration

#### **6.3.1 Auto Tax Calculation**

*   Stripe Tax automatically calculates tax based on client location.
*   Tax rates are determined by the client's billing address.
*   Supports international tax compliance.

#### **6.3.2 Tax Configuration Options**

**Option**

**Description**

Auto (Stripe Tax)

Tax calculated based on client location

Manual

Agency enters tax rate percentage manually

#### **6.3.3 Tax Application**

*   Tax respects line-item taxable settings.
*   Items with Tax toggle OFF are not taxed.
*   Tax is calculated after discount application.
*   Formula: Tax = (Subtotal - Discount) × Tax Rate

### 6.4 Refund Processing

#### **6.4.1 Refund Initiation**

*   Refunds are initiated through the Pixally UI only.
*   Direct Stripe dashboard refunds will NOT sync to Pixally.
*   Agency users must use Pixally to maintain data integrity.

#### **6.4.2 Refund Flow**

1.  Admin/Manager selects a paid transaction.
2.  Admin/Manager clicks "Refund" action.
3.  System opens refund confirmation modal.
4.  Admin/Manager confirms the refund amount (full or partial).
5.  Pixally sends refund request to Stripe.
6.  Stripe processes the refund.
7.  Stripe sends webhook confirmation.
8.  Pixally updates transaction status to "Refunded."
9.  Invoice status updates accordingly.

#### **6.4.3 Refund Restrictions**

*   Only paid transactions can be refunded.
*   Unpaid transactions cannot be refunded.
*   Processing transactions must complete before refund.

### 6.5 Webhook Integration

#### **6.5.1 Webhook Events Handled**

**Stripe Event**

**Pixally Action**

payment\_intent.succeeded

Update transaction to "Paid"

payment\_intent.payment\_failed

Update transaction to "Failed"

payment\_intent.processing

Update transaction to "Processing"

charge.refunded

Update transaction to "Refunded"

charge.refund.updated

Update refund status

#### **6.5.2 Status Synchronization**

*   Webhook events trigger immediate status updates in Pixally.
*   Invoice status recalculates after each transaction status change.
*   No manual sync required.

### 6.6 Failed Payment Handling

#### **6.6.1 Retry Policy**

*   Manual retry only (no automatic retry).
*   Client can retry immediately after failure.
*   Unlimited manual retry attempts allowed.

#### **6.6.2 Failure Notification**

*   Client receives email notification of failed payment.
*   Email includes "Retry Payment" link.
*   Agency owner is also notified.

#### **6.6.3 Retry Flow**

1.  Client receives failed payment notification.
2.  Client clicks "Retry Payment" link or accesses invoice in portal.
3.  Client attempts payment again.
4.  Process repeats until successful or client contacts agency.

## **7\. Email Integration**

### 7.1 Overview

The Email Integration sends notifications for invoice events, payment reminders, and status updates. Templates are customizable per agency.

### 7.2 Email Triggers

**Trigger Event**

**Recipient**

**Email Type**

Invoice Sent (Share Invoice)

Client

Invoice notification with pay link

Invoice Updated (Update & Share)

Client

Update notification with pay link

Payment Reminder - Upcoming

Client

Reminder (7 days before due)

Payment Reminder - Due Date

Client

Reminder (on due date)

Overdue Reminder (+2 days)

Client

Overdue notice

Overdue Reminder (+5 days)

Client

Overdue notice

Payment Received

Client

Payment confirmation

Payment Failed

Client + Agency Owner

Failure notification

Refund Processed

Client

Refund confirmation

### 7.3 Email Templates

#### **7.3.1 Customization**

*   Email templates are customizable per agency.
*   Templates are managed in: Templates → Email Templates.
*   Each trigger event has a corresponding template.

#### **7.3.2 Template Variables**

**Variable**

**Description**

{{client\_name}}

Client's full name

{{invoice\_number}}

Invoice number (#INV00001)

{{amount\_due}}

Transaction amount

{{due\_date}}

Payment due date

{{payment\_link}}

Link to pay invoice

{{project\_name}}

Associated project name

{{company\_name}}

Agency/brand name

### 7.4 Payment Reminders

#### **7.4.1 Reminder Schedule (System-Wide Fixed)**

**Reminder Type**

**Timing**

**Default Channel**

Upcoming

7 days prior to due date

Email

Due Date

On payment due date

SMS

Overdue (+2 days)

2 days past due date

Email

Overdue (+5 days)

5 days past due date

Email

#### **7.4.2 Channel Options**

*   Each reminder can be configured to: None, SMS, or Email.
*   Configuration is set in agency's global settings.
*   Settings apply to all invoices for the agency.

#### **7.4.3 Reminder Content**

*   Reminders include transaction amount, due date, and payment link.
*   "Pay Invoice" button links directly to payment interface.
*   Reminders reference the specific transaction, not the entire invoice.

### 7.5 SMS Notifications

#### **7.5.1 SMS Support**

*   SMS notifications are supported alongside email.
*   SMS can be enabled for any reminder type.
*   SMS content is a condensed version of email content.

#### **7.5.2 SMS Content**

*   Includes: Amount, due date, short payment link.
*   Character limit considerations apply.
*   Links are shortened for SMS delivery.

## **8\. Finance Module Integration**

### 8.1 Overview

The Finance Module provides centralized invoice and transaction management through the Billing page. Invoice data feeds into financial reports and Profit & Loss calculations.

### 8.2 Billing Page - Invoices Tab

#### **8.2.1 Invoice Listing**

**Column**

**Description**

Next Payment Date

Date of next unpaid transaction

Invoice ID

Unique invoice identifier (#INV00001)

Client

Client name with avatar

Amount

Total invoice amount

Status / Payments

Status badge or payment count

Project

Associated project name

Actions

Three-dot menu

#### **8.2.2 Expandable Rows**

*   Clicking the expand arrow reveals payment schedule details.
*   Each transaction displays: Date, Amount, Status.
*   Allows viewing individual payment entries without opening invoice.

#### **8.2.3 Tabs and Filters**

**Tab**

**Contents**

All

All active invoices

Deactivated

Deactivated invoices with Reactivate option

**Filter**

**Options**

Brand

All Brands, or specific brand

Search

Search by client name, invoice ID, project

### 8.3 Billing Page - Transactions Tab

#### **8.3.1 Transaction Listing**

*   Displays individual payment transactions across all invoices.
*   Each row represents one payment entry from a payment schedule.
*   Provides detailed view of all payment activity.

#### **8.3.2 Transaction Data**

**Column**

**Description**

Date

Transaction due date or payment date

Invoice ID

Parent invoice reference

Client

Client name

Amount

Transaction amount

Status

Paid, Unpaid, Processing, Failed, Refunded

Actions

View, Record Payment, Refund