Brandwise QuickBooks Listing

Functional Requirements Document (FRD)

Brandwise QuickBooks Listing

Module: QuickBooks Integration
Sub-Module: Brandwise QuickBooks Listing
Version: 1.1

1. Module Overview

Module Name: Brandwise QuickBooks Listing

Purpose: This sub-module provides agency users with a centralized view of all their brands and their respective QuickBooks integration statuses. It serves as the main dashboard for managing QuickBooks connections across multiple brands within the Pixally CRM platform.

Business Goals:

• Enable agency owners to view and manage QuickBooks connections for all their brands from a single interface.
• Provide clear visibility into which brands are connected to QuickBooks and which require setup.
• Facilitate quick access to connect, disconnect, or modify QuickBooks account mappings for each brand.
• Support flexible business setups where agencies can connect the same QuickBooks account to multiple brands or use different QuickBooks accounts for different brands.

2. User Roles & Permissions

Role

Access Level

Permissions

Agency Owner

Full Access

View all brands, connect/disconnect QuickBooks, modify account mappings, access expanded row details

Agency Admin

Full Access

View all brands, connect/disconnect QuickBooks, modify account mappings, access expanded row details

Agency Manager

View Only

View brand listing and connection statuses; cannot connect/disconnect or modify mappings

Contractor

No Access

Cannot access the Integrations module

Client

No Access

Cannot access the Integrations module

3. User Flow

3.1 The user navigates to Tools > Integrations from the left sidebar menu.

3.2 The system displays the Integrations main page showing all available integration cards including Google Calendar, QuickBooks Online, and Calendly.

3.3 The user views the QuickBooks Online card which displays the description "Sync your Pixally invoices with QuickBooks."

3.4 If QuickBooks is already connected for at least one brand, the system displays a "Manage Integration" button on the QuickBooks card.

3.5 If QuickBooks is not connected for any brand, the system displays a "Connect" button on the QuickBooks card.

3.6 The user clicks on "Manage Integration" or "Connect" button on the QuickBooks Online card.

3.7 The system navigates to the QuickBooks Online brandwise listing page with the header "← QuickBooks Online" and a back arrow.

3.8 If the agency has multiple brands, the system displays an info banner at the top stating: "Please Note: Each brand in Pixally needs its own QuickBooks connection. If you use the same QuickBooks account for multiple brands, simply connect to that same account again for each brand — this ensures everything stays organized and flexible for the future."

3.9 The system displays a table with columns: Brand Name, QuickBooks Company ID, Integration Status, and Actions.

3.10 For each brand, the system displays the brand logo/avatar, brand name, connected QuickBooks company name (if connected), integration status badge, and appropriate action button.

3.11 The user can view which brands are connected (green "Connected" badge) and which are not connected (gray "Not Connected" badge).

3.12 For connected brands, the user can click the chevron icon to expand the row and view/modify account mappings.

3.13 For not connected brands, the chevron icon is disabled and non-clickable.

3.14 The user clicks the back arrow "←" to return to the main Integrations page.

4. Functional Logic

4.1 Navigation and Access

• The QuickBooks Integration module is accessible via the path: Tools > Integrations > QuickBooks Online.
• The system displays the QuickBooks Online card on the main Integrations page alongside other integration options such as Google Calendar and Calendly.
• Users must have an active subscription plan that includes QuickBooks integration to access this feature.
• If the user's subscription plan does not include QuickBooks integration, clicking the "Connect" button will prompt the user to upgrade their subscription plan.
• Only Agency Owners and Agency Admins have permission to connect, disconnect, or modify QuickBooks integration settings.

4.2 Integration Card Display Logic

• The QuickBooks Online card displays the QuickBooks logo, the title "QuickBooks Online", and the description "Sync your Pixally invoices with QuickBooks."
• If at least one brand is connected to QuickBooks, the card displays a "Manage Integration" button.
• If no brands are connected to QuickBooks, the card displays a "Connect" button.
• The card background uses a light green color to visually distinguish QuickBooks from other integrations.

4.3 Brandwise Listing Table

• Upon clicking "Manage Integration" or "Connect", the system navigates to the brandwise listing page.
• The page header displays "← QuickBooks Online" with a back arrow that navigates to the main Integrations page.
• The table displays all brands associated with the agency, regardless of their QuickBooks connection status.
• Each row in the table contains: Brand Logo/Avatar, Brand Name, QuickBooks Company ID, Integration Status, and Actions column.
• Brands are displayed in the order they were created in Pixally (oldest first).

4.4 Info Banner Display Rules

• The info banner is displayed at the top of the brandwise listing page only when the agency has multiple brands (2 or more brands).
• The info banner is not displayed if the agency has only one brand.
• The info banner text reads: "Please Note: Each brand in Pixally needs its own QuickBooks connection. If you use the same QuickBooks account for multiple brands, simply connect to that same account again for each brand — this ensures everything stays organized and flexible for the future."
• The info banner includes an information icon (ℹ️) on the left side.

4.5 QuickBooks Company ID Column

• The QuickBooks Company ID column displays the company name fetched from QuickBooks after successful OAuth authentication.
• This value is auto-populated by the system after the user completes the QuickBooks login process.
• If the brand is not connected to QuickBooks, this column displays empty/blank.
• The company ID helps users identify which QuickBooks company is linked to each brand, especially when using multiple QuickBooks accounts.

4.6 Integration Status Display

• The Integration Status column displays a badge indicating the current connection state.
• "Connected" status: Displayed as a green badge with white text when the brand is successfully connected to QuickBooks and account mapping is complete.
• "Not Connected" status: Displayed as a gray badge with dark text when the brand has never been connected to QuickBooks or has been disconnected.
• If a brand is connected but account mapping is incomplete (user clicked "Skip for Now"), the status still shows "Connected" but with a warning tooltip: "Account mapping incomplete. Some transaction types will not sync until accounts are configured."

4.7 Actions Column

• For brands with "Connected" status, the Actions column displays a "Disconnect" button styled in yellow/gold color.
• For brands with "Not Connected" status, the Actions column displays a "Connect" button with an outlined/bordered style.
• Clicking "Connect" initiates the QuickBooks connection flow (covered in FRD 2).
• Clicking "Disconnect" opens a confirmation modal (covered in FRD 5).

4.8 Expandable Row Functionality

• Each row has a chevron icon (▼) on the left side that indicates expandability.
• The chevron icon is only clickable/enabled when the brand's QuickBooks status is "Connected".
• The chevron icon is disabled and appears grayed out when the brand's status is "Not Connected".
• Clicking the chevron on a connected brand expands the row to reveal account mapping details and modification options.
• The expanded section displays the five account mapping dropdowns: Income, Refund, COGS, OPEX, and Tax Account.
• Only one row can be expanded at a time; expanding a new row automatically collapses the previously expanded row.

4.9 Empty State Handling

• If the agency has no brands created yet, the system displays an empty state message: "No brands found. Please create a brand first to connect QuickBooks."
• The empty state includes a call-to-action button or link to navigate to the Brands module.
• If brands exist but none are connected to QuickBooks, the table displays all brands with "Not Connected" status and "Connect" buttons.

4.10 Subscription Plan Validation

• The system validates the user's subscription plan before allowing QuickBooks integration access.
• Users without a qualifying subscription plan will not see the QuickBooks integration card on the Integrations page.
• If a user's plan is downgraded and QuickBooks is no longer included, the QuickBooks card is hidden from the Integrations page.
• Previously connected QuickBooks integrations are automatically disconnected when the subscription is downgraded.

5. Field Details & Validations

Field Name

Field Type

Description

Validation Rules

Brand Logo/Avatar

Image

Displays the brand's logo or a generated avatar with initials

Read-only; fetched from Brand settings

Brand Name

Text (Display)

Name of the brand as configured in Pixally

Read-only; fetched from Brand settings

QuickBooks Company ID

Text (Display)

Company name from the connected QuickBooks account

Read-only; auto-populated after OAuth; empty if not connected

Integration Status

Badge

Visual indicator of connection status

Read-only; system-generated based on connection state

Connect Button

Button

Initiates QuickBooks connection flow

Enabled only for "Not Connected" brands; requires valid subscription

Disconnect Button

Button

Initiates disconnection confirmation

Enabled only for "Connected" brands

Expand/Collapse Chevron

Icon Button

Toggles row expansion for account mapping view

Enabled only for "Connected" brands; disabled for "Not Connected"

6. Success Message Handling

Action

Success Message

Display Location

Post-Action Behavior

Navigate to QuickBooks listing

N/A (No message)

N/A

Page loads with brandwise table

Expand row

N/A (No message)

N/A

Row expands smoothly with animation

Collapse row

N/A (No message)

N/A

Row collapses smoothly with animation

Back navigation

N/A (No message)

N/A

Returns to main Integrations page

7. Error Message Handling

Error Scenario

Error Message

Display Location

Trigger Condition

User Action Required

Subscription not eligible

"QuickBooks integration is not available on your current plan. Please upgrade to access this feature."

Toast notification

User clicks Connect without qualifying subscription

Upgrade subscription plan

Page load failure

"Unable to load QuickBooks integration data. Please try again."

Inline error with retry button

API failure or network error

Click "Retry" button or refresh page

No brands exist

"No brands found. Please create a brand first to connect QuickBooks."

Empty state in table area

User has no brands configured

Navigate to Brands module to create a brand

Session expired

"Your session has expired. Please log in again."

Modal dialog

OAuth token expired during operation

Re-authenticate into Pixally

8. Edge Cases

Edge Case

Scenario Description

Expected System Behavior

Single brand agency

Agency has only one brand

Info banner is not displayed; table shows single brand row

All brands connected

All brands in the agency are connected to QuickBooks

All rows show "Connected" status with "Disconnect" buttons

All brands disconnected

No brands are connected to QuickBooks

All rows show "Not Connected" status with "Connect" buttons; main card shows "Connect" instead of "Manage Integration"

Mixed connection states

Some brands connected, some not

Table shows mixed statuses; main card shows "Manage Integration"

Brand deleted after connection

A brand connected to QB is deleted from Pixally

Brand row is removed from the listing; QB connection is orphaned (no impact on QB side)

New brand added

User creates a new brand while on QB listing page

New brand appears in the table with "Not Connected" status after page refresh

Rapid expand/collapse

User rapidly clicks multiple row chevrons

System handles gracefully; only the last clicked row is expanded

Same QB account for multiple brands

User connects the same QuickBooks company to multiple brands

Each brand maintains its own connection; all show the same QB Company ID

Network interruption

Network fails while loading the page

Error message displayed with retry option

Concurrent session

User has multiple browser tabs open on the same page

Changes in one tab reflect in other tabs upon refresh

9. Acceptance Criteria

• AC1: The QuickBooks Online card is displayed on the Integrations page with correct branding and description.
• AC2: The card shows "Manage Integration" when at least one brand is connected, and "Connect" when no brands are connected.
• AC3: Clicking the card navigates to the brandwise listing page with all brands displayed.
• AC4: The info banner is visible only when the agency has multiple brands (2 or more).
• AC5: Each brand row displays the correct Brand Name, QuickBooks Company ID (if connected), Integration Status, and appropriate action button.
• AC6: The "Connected" status displays as a green badge, and "Not Connected" displays as a gray badge.
• AC7: The expand chevron is enabled only for connected brands and disabled for not connected brands.
• AC8: Clicking an enabled chevron expands the row to show account mapping details.
• AC9: Only one row can be expanded at a time.
• AC10: The back arrow navigates to the main Integrations page.
• AC11: Users without a qualifying subscription cannot access QuickBooks integration features.
• AC12: The empty state message is displayed when no brands exist.

10. Manual Test Cases

Link: Test Cases - Brandwise QuickBooks Listing

11. Dependencies

Dependency Type

Dependency Name

Description

Impact if Unavailable

Internal Module

Brands Module

Provides list of brands for the agency

Cannot display brand listing; empty state shown

Internal Module

Subscription/Billing Module

Validates user's subscription plan eligibility

Cannot verify QuickBooks access; may block all users

External Service

QuickBooks OAuth API

Provides company information after authentication

Company ID column cannot be populated

Internal Module

User Authentication

Validates user session and permissions

Access denied to Integrations module

Internal Database

QuickBooks Connection Store

Stores connection status and mappings per brand

Cannot determine connection status; page fails to load

12. References

• Figma Design:

Connect the QuickBooks Account with Pixally

Functional Requirements Document (FRD)

Connect the QuickBooks Account with Pixally

Module: QuickBooks Integration
Sub-Module: Connect the QuickBooks Account with Pixally
Version: 1.1

1. Module Overview

Module Name: Connect the QuickBooks Account with Pixally

Purpose: This sub-module enables agency users to establish a connection between their Pixally brand and their QuickBooks Online account. It handles the complete first-time connection flow including OAuth authentication with Intuit, fetching the chart of accounts from QuickBooks, and allowing users to map QuickBooks accounts for different transaction types (income, refunds, COGS, OPEX, and taxes).

Business Goals:

• Enable seamless one-way integration from Pixally to QuickBooks for financial data synchronization.
• Allow users to authenticate with their existing QuickBooks account or create a new one during the connection process.
• Provide flexible account mapping to support various accounting structures and preferences.
• Ensure data accuracy by mapping specific Pixally transaction types to appropriate QuickBooks accounts.

2. User Roles & Permissions

Role

Access Level

Permissions

Agency Owner

Full Access

Initiate connection, complete OAuth, configure account mappings, finish or skip setup

Agency Admin

Full Access

Initiate connection, complete OAuth, configure account mappings, finish or skip setup

Agency Manager

No Access

Cannot initiate or configure QuickBooks connections

Contractor

No Access

Cannot access the Integrations module

Client

No Access

Cannot access the Integrations module

3. User Flow

3.1 The user navigates to Tools > Integrations > QuickBooks Online from the brandwise listing page.

3.2 The user identifies a brand with "Not Connected" status and clicks the "Connect" button in the Actions column.

3.3 The system displays the "Connect Your QuickBooks Account" modal with integration overview information.

3.4 The modal displays the Pixally logo, an arrow, and the QuickBooks logo indicating the direction of data flow.

3.5 The modal displays three key benefits of the integration:

• Creates a customer and corresponding invoice in QuickBooks when a first payment is made
• Records new payments from that customer against the invoice
• Records any refunds issued to the customer against the invoice in QuickBooks

3.6 The modal displays a "Please Note" info box explaining that each brand needs its own QuickBooks connection.

3.7 The user reviews the information and clicks the "Connect QuickBooks" button to proceed.

3.8 The system redirects the user to the Intuit (QuickBooks) OAuth login page in a new browser window or the same window.

3.9 The user enters their Intuit credentials (Email/User ID or Phone) and clicks "Sign in".

3.10 If the user does not have an Intuit account, they can click "Create an account" to register a new QuickBooks account.

3.11 If the user has multiple QuickBooks companies associated with their Intuit account, Intuit displays a company selection screen.

3.12 The user selects the QuickBooks company they want to connect to the Pixally brand.

3.13 After successful authentication, Intuit redirects the user back to Pixally.

3.14 The system displays the "Define The Accounts" modal for account mapping configuration.

3.15 The system fetches and populates the chart of accounts from the connected QuickBooks company into the dropdown options.

3.16 The user selects a QuickBooks account for Income from the first dropdown (this field is mandatory).

3.17 The user selects a QuickBooks account for Refund from the second dropdown (optional).

3.18 The user selects a QuickBooks account for COGS (Cost of Goods Sold) from the third dropdown (optional).

3.19 The user selects a QuickBooks account for OPEX (Operating Expenses) from the fourth dropdown (optional).

3.20 The user selects a QuickBooks Sales Tax Payable account from the fifth dropdown (optional).

3.21 If the Tax Account dropdown is empty, the system prompts the user to create a Sales Tax Payable account in QuickBooks.

3.22 If the system detects that Automated Sales Tax is enabled in QuickBooks, the Tax Account dropdown is disabled with a message directing the user to use their existing tax agency account.

3.23 The user can choose to click "Skip for Now" to complete the connection with only the mandatory Income account configured.

3.24 If the user clicks "Skip for Now" without selecting the mandatory Income account, the system displays a validation error.

3.25 Alternatively, the user clicks "Finish Setup" to save the account mappings and complete the setup.

3.26 The "Finish Setup" button is disabled until the mandatory Income account is selected.

3.27 The system saves the configuration and displays a success message.

3.28 The system navigates the user back to the brandwise listing page where the brand now shows "Connected" status.

4. Functional Logic

4.1 Connection Initiation

• The connection flow is initiated when a user clicks the "Connect" button for a brand with "Not Connected" status.
• The system first validates that the user has permission to connect QuickBooks (Agency Owner or Agency Admin only).
• The system validates that the user's subscription plan includes QuickBooks integration before proceeding.
• If subscription validation fails, the system displays an upgrade prompt instead of the connection modal.

4.2 Connect Your QuickBooks Account Modal

• The modal serves as an informational screen before OAuth redirect, explaining what the integration does.
• The modal header displays "Connect Your QuickBooks Account" with an X close button.
• The modal body displays visual branding showing data flow direction: Pixally logo → arrow → QuickBooks logo.
• The modal displays the text "Sync your Pixally invoices with QuickBooks."
• Three green checkmark bullet points explain the integration benefits:
  • "Creates a customer and corresponding invoice in QuickBooks when a first payment is made"
  • "Records new payments from that customer against the invoice"
  • "Records any refunds issued to the customer against the invoice in QuickBooks"
• An info box with an information icon displays: "Please Note: Each brand in Pixally needs its own QuickBooks connection. If you use the same QuickBooks account for multiple brands, simply connect to that same account again for each brand — this ensures everything stays organized and flexible for the future."
• The modal footer contains two buttons: "Close" (secondary) and "Connect QuickBooks" (primary, yellow).

4.3 OAuth Authentication Flow

• Clicking "Connect QuickBooks" initiates the OAuth 2.0 flow with Intuit.
• The system redirects the user to Intuit's authentication page (https://accounts.intuit.com).
• The Intuit login page provides two authentication options: Email/User ID or Phone.
• The user can choose to be remembered on the device by checking "Remember me".
• Users without an Intuit account can click "Create an account" to register.
• After successful login, if the user has multiple QuickBooks companies, Intuit displays a company selection screen.
• The company selection is handled entirely by Intuit's OAuth flow; Pixally does not need to build a separate company selection screen.
• After the user selects a company (or if they have only one company), Intuit redirects back to Pixally with the OAuth tokens.
• The system stores the OAuth access token and refresh token securely for the specific brand.
• The system retrieves and stores the QuickBooks Company ID (company name) from the OAuth response.

4.4 Define The Accounts Modal

• After successful OAuth, the system immediately displays the "Define The Accounts" modal.
• The modal header displays "Define The Accounts" with an X close button.
• The modal displays instructional text: "Define the accounts to which payments, taxes, service charges, and refunds should be allocated."
• The system fetches the chart of accounts from the connected QuickBooks company via API.
• The modal displays five dropdown fields for account mapping.
• Each dropdown is populated with relevant accounts from QuickBooks filtered by account type.

4.5 Account Mapping Dropdowns

The Define Accounts modal displays five dropdown fields for account mapping. The Income dropdown is mandatory; all other fields are optional.

Dropdown 1: Income (Mandatory)

• Label: "Select the default QuickBooks account for income"
• Placeholder: "Select your QuickBooks account"
• Populated with: Accounts with type "Income" and "Cash on Hand" from QuickBooks chart of accounts
• Purpose: Defines where client payment income is recorded
• Validation: This field is mandatory. The user cannot proceed with "Finish Setup" without selecting an Income account.

Dropdown 2: Refund

• Label: "Select the QuickBooks account to associate with refunds"
• Placeholder: "Select your QuickBooks account"
• Populated with: Accounts with type "Income" and subtype "Discounts/Refunds Given" from QuickBooks
• Purpose: Defines where Refund Receipt transactions are posted

Dropdown 3: COGS (Cost of Goods Sold)

• Label: "Select the QuickBooks account for cost of goods sold"
• Placeholder: "Select your QuickBooks account"
• Populated with: Accounts with type "Expense" and subtypes "Cost of Goods Sold" and "Labor Cost" from QuickBooks
• Purpose: Defines where contractor payment expenses are recorded

Dropdown 4: OPEX (Operating Expenses)

• Label: "Select the QuickBooks account for operating expenses"
• Placeholder: "Select your QuickBooks account"
• Populated with: Accounts with type "Expense" from QuickBooks
• Purpose: Defines where Stripe transaction fees and other operating expenses are recorded

Dropdown 5: Tax Account (Sales Tax Payable)

• Label: "Select the QuickBooks account for sales tax payable"
• Placeholder: "Select your QuickBooks account"
• Populated with: Accounts with type "Other Current Liability" and subtype "Sales Tax Payable" from QuickBooks
• Purpose: Defines where collected sales tax is posted
• Special Behavior:
  • If no liability accounts exist, the dropdown shows empty with a prompt: "No tax accounts found. Please create a Sales Tax Payable account in QuickBooks."
  • If Automated Sales Tax is detected in QuickBooks, the dropdown is disabled with message: "Your QuickBooks uses Automated Sales Tax. Please use your existing tax agency account configured in QuickBooks."

4.6 Dropdown Filtering by Account Type

• The system filters QuickBooks chart of accounts based on the appropriate account type for each dropdown.
• Income dropdown shows only accounts with type "Income" and "Cash on Hand".
• Refund dropdown shows only accounts with type "Income" and subtype "Discounts/Refunds Given".
• COGS dropdown shows only accounts with type "Expense" and subtypes "Cost of Goods Sold" and "Labor Cost".
• OPEX dropdown shows only accounts with type "Expense".
• Tax Account dropdown shows only accounts with type "Other Current Liability" and subtype "Sales Tax Payable".
• This filtering ensures users can only select appropriate accounts for each transaction type.

4.6.1 Tax Account Special Handling

• The Tax Account dropdown shows liability accounts only, not tax rates.
• If no Sales Tax Payable accounts exist in QuickBooks, the dropdown is empty and displays a prompt to create one.
• If the system detects that Automated Sales Tax is enabled in the connected QuickBooks company, the Tax Account dropdown is disabled.
• When disabled, the system displays the message: "Your QuickBooks uses Automated Sales Tax. Please use your existing tax agency account configured in QuickBooks."
• Auto-creating a tax account is not recommended as it may create duplicates that conflict with Automated Sales Tax.

4.7 Mandatory and Optional Fields

• The Income dropdown is mandatory and must be selected before the user can click "Finish Setup".
• The remaining four dropdowns (Refund, COGS, OPEX, Tax Account) are optional.
• The user can complete the setup with only the Income account selected by clicking "Skip for Now".
• If the user clicks "Skip for Now" without selecting the Income account, the system displays a validation error: "Please select an Income account to continue."
• Transaction syncing will only work for transaction types that have accounts mapped.
• If only the Income account is mapped, only client payment transactions will sync to QuickBooks.

4.8 Skip for Now Behavior

• The "Skip for Now" button is enabled only when the mandatory Income account is selected.
• Clicking "Skip for Now" closes the modal and completes the connection process with partial mappings.
• The brand status is set to "Connected" in the brandwise listing.
• The QuickBooks Company ID is populated in the listing table.
• If optional mappings are incomplete, the system displays a warning tooltip on the status badge: "Account mapping incomplete. Some transaction types will not sync until accounts are configured."
• Only transaction types with mapped accounts will sync to QuickBooks.
• The user can later complete the account mapping by expanding the brand row in the listing.

4.9 Finish Setup Behavior

• The "Finish Setup" button is disabled until the mandatory Income account is selected.
• Clicking "Finish Setup" saves all selected account mappings to the database.
• The system validates that the OAuth connection is still valid before saving.
• The brand status is set to "Connected" in the brandwise listing.
• The QuickBooks Company ID is populated in the listing table.
• The integration is ready to sync transactions for all mapped account types.
• The system displays a success toast notification confirming the connection.
• The user is redirected to the brandwise listing page.

4.10 Chart of Accounts Not Found

• If the connected QuickBooks company has no chart of accounts configured, the dropdowns will be empty.
• The system displays a message: "No accounts found in your QuickBooks. Please configure your chart of accounts in QuickBooks and try again."
• The user can still proceed with "Skip for Now" to complete the connection.
• The user will need to configure accounts in QuickBooks, then use the Refresh option (in the expanded row) to load them.

4.11 Connection Failure Handling

• If OAuth fails (user cancels, invalid credentials, etc.), the system returns to the brandwise listing without changes.
• If the API call to fetch chart of accounts fails, the system displays an error and allows retry.
• If saving the account mappings fails, the system displays an error but maintains the OAuth connection.
• The user can retry the account mapping later through the expanded row view.

4.12 Same QuickBooks Account for Multiple Brands

• Users can connect the same QuickBooks company to multiple Pixally brands.
• Each brand-to-QuickBooks connection is independent and maintains its own OAuth tokens.
• Account mappings can be different for each brand even if connected to the same QuickBooks company.
• This supports business scenarios where one QuickBooks company handles finances for multiple brands.

5. Field Details & Validations

Field Name

Field Type

Description

Validation Rules

Email or User ID

Text Input

Intuit login credential

Handled by Intuit OAuth; not validated by Pixally

Phone

Text Input

Alternative Intuit login credential

Handled by Intuit OAuth; not validated by Pixally

Remember me

Checkbox

Intuit session persistence option

Handled by Intuit OAuth

Income Dropdown

Dropdown Select

QuickBooks account for income

Mandatory; must be selected before Finish Setup; must be valid Income or Cash on Hand account

Refund Dropdown

Dropdown Select

QuickBooks account for refunds

Optional; must be valid Income account with Discounts/Refunds Given subtype if selected

COGS Dropdown

Dropdown Select

QuickBooks account for cost of goods sold

Optional; must be valid Expense account with COGS or Labor Cost subtype if selected

OPEX Dropdown

Dropdown Select

QuickBooks account for operating expenses

Optional; must be valid Expense account if selected

Tax Account Dropdown

Dropdown Select

QuickBooks account for sales tax payable

Optional; must be valid Other Current Liability account with Sales Tax Payable subtype if selected; disabled if Automated Sales Tax is detected

6. Success Message Handling

Action

Success Message

Display Location

Post-Action Behavior

OAuth completed

N/A (No message)

N/A

Define The Accounts modal opens

Account mappings saved

"QuickBooks connected successfully for [Brand Name]."

Toast notification (top-right)

Redirect to brandwise listing

Skip for Now

"QuickBooks connected for [Brand Name]. Complete account mapping to enable sync."

Toast notification (top-right)

Redirect to brandwise listing

7. Error Message Handling

Error Scenario

Error Message

Display Location

Trigger Condition

User Action Required

OAuth cancelled

"QuickBooks connection was cancelled."

Toast notification

User closes OAuth window or clicks cancel

Retry connection

OAuth failed

"Unable to connect to QuickBooks. Please try again."

Toast notification

OAuth error from Intuit

Retry connection

Chart of accounts fetch failed

"Unable to load QuickBooks accounts. Please try again."

Inline error in modal

API error during fetch

Click retry or refresh

Income account not selected

"Please select an Income account to continue."

Inline validation error

User clicks Finish Setup or Skip for Now without Income

Select Income account

Save failed

"Failed to save account mappings. Please try again."

Toast notification

Database or API error

Click Save again

Session expired

"Your session has expired. Please log in again."

Modal dialog

OAuth token expired

Re-authenticate into Pixally

No tax accounts available

"No tax accounts found. Please create a Sales Tax Payable account in QuickBooks."

Inline message below dropdown

No liability accounts exist in QB

Create account in QuickBooks

Automated Sales Tax detected

"Your QuickBooks uses Automated Sales Tax. Please use your existing tax agency account configured in QuickBooks."

Inline message; dropdown disabled

QB has Automated Sales Tax enabled

No action; use existing QB tax setup

8. Edge Cases

Edge Case

Scenario Description

Expected System Behavior

User has no QuickBooks account

User doesn't have an Intuit/QuickBooks account

"Create an account" link is available on Intuit login page

User has one QB company

User has only one company in their Intuit account

Company selection screen is skipped; direct redirect

User has multiple QB companies

User has multiple companies in their Intuit account

Intuit shows company selection screen

Empty chart of accounts

Connected QB company has no accounts configured

Dropdowns show empty; user prompted to configure QB first

OAuth popup blocked

Browser blocks the OAuth popup window

Error message with instructions to allow popups

OAuth window closed early

User closes OAuth window before completing

Connection cancelled; user can retry

Network error during OAuth

Network fails during OAuth redirect

Error message; user can retry

Network error during account fetch

Network fails while fetching chart of accounts

Error message with retry option

Rapid Finish Setup clicks

User clicks Finish Setup multiple times quickly

System processes first click; subsequent ignored

Browser refresh during account mapping

User refreshes the page while on Define The Accounts modal

OAuth connection is saved; modal can be accessed via expanded row

Different user reconnects same brand

A different admin attempts to reconnect an already connected brand

System shows brand as "Connected"; must disconnect first to reconnect

9. Acceptance Criteria

• AC1: Clicking "Connect" on a "Not Connected" brand displays the "Connect Your QuickBooks Account" modal.
• AC2: The modal displays correct branding, integration description, and three benefit bullet points.
• AC3: The "Please Note" info box is visible with correct text about brand-specific connections.
• AC4: Clicking "Connect QuickBooks" redirects to Intuit OAuth login page.
• AC5: User can authenticate using Email/User ID or Phone on the Intuit page.
• AC6: If user has multiple QB companies, they can select which company to connect.
• AC7: After successful OAuth, the "Define The Accounts" modal is displayed.
• AC8: All five dropdowns are populated with appropriate accounts from QuickBooks: Income, Refund, COGS, OPEX, and Tax Account.
• AC9: Dropdowns are filtered by account type: Income (Income + Cash on Hand), Refund (Income + Discounts/Refunds Given), COGS (Expense + COGS/Labor Cost), OPEX (Expense), Tax Account (Other Current Liability + Sales Tax Payable).
• AC10: The Income dropdown is mandatory; all other fields are optional.
• AC11: The "Finish Setup" button is disabled until the mandatory Income account is selected.
• AC12: Clicking "Skip for Now" is enabled only when Income is selected; it completes connection with partial mappings.
• AC13: If "Skip for Now" is clicked without selecting Income, a validation error is displayed.
• AC14: The Tax Account dropdown shows only liability accounts (not tax rates).
• AC15: If no Sales Tax Payable accounts exist, the Tax Account dropdown shows a prompt to create one in QuickBooks.
• AC16: If Automated Sales Tax is detected, the Tax Account dropdown is disabled with an appropriate message.
• AC17: Clicking "Finish Setup" saves mappings and shows success message.
• AC18: After setup, the brand shows "Connected" status with the QuickBooks Company ID populated.
• AC19: If optional mappings are incomplete, the status shows "Connected" with a warning tooltip.
• AC20: User can connect the same QuickBooks account to multiple brands.
• AC21: OAuth errors display appropriate error messages and allow retry.

10. Manual Test Cases

Link: Test Cases - Connect QuickBooks Account with Pixally

11. Dependencies

Dependency Type

Dependency Name

Description

Impact if Unavailable

External Service

Intuit OAuth 2.0 API

Handles user authentication with QuickBooks

Connection flow cannot proceed; users cannot connect QB

External Service

QuickBooks Chart of Accounts API

Fetches available accounts for mapping

Account mapping dropdowns will be empty

External Service

QuickBooks Tax Rates API

Fetches available tax rates

Tax Account dropdown will be empty

Internal Module

Subscription/Billing Module

Validates user's subscription plan

Cannot verify eligibility; may block all users

Internal Module

Brands Module

Provides brand context for the connection

Cannot associate connection with a brand

Internal Database

OAuth Token Storage

Securely stores OAuth access and refresh tokens

Connection cannot be maintained; re-auth required each time

Internal Database

Account Mapping Storage

Stores user's account mapping selections

Cannot remember user's configuration

12. References

• Figma Designs:

Pixally to QuickBooks Sync

Functional Requirements Document (FRD)

Pixally to QuickBooks Sync of Income and Expense

Module: QuickBooks Integration
Sub-Module: Pixally to QuickBooks Sync of Income and Expense
Version: 1.1

1. Module Overview

Module Name: Pixally to QuickBooks Sync of Income and Expense

Purpose: This sub-module handles the automatic synchronization of financial transactions from Pixally to QuickBooks Online. It covers the real-time syncing of invoices, client payments (Sales Receipts), refunds (Refund Receipts), contractor payments (Expenses), and Stripe processing fees. The integration ensures that all financial data flows from Pixally to QuickBooks for accurate bookkeeping and tax reporting.

Business Goals:

• Automate the transfer of financial transaction data from Pixally to QuickBooks to eliminate manual data entry.
• Ensure accurate recording of income (client payments), expenses (contractor payments, Stripe fees), and refunds.
• Support partial payments, multiple payers, and complex invoicing scenarios.
• Provide visibility into sync status for each transaction.
• Enable manual retry for failed sync attempts.

2. User Roles & Permissions

Role

Access Level

Permissions

Agency Owner

Full Access

View sync status, manually trigger sync for failed transactions, view all transaction details

Agency Admin

Full Access

View sync status, manually trigger sync for failed transactions, view all transaction details

Agency Manager

View Only

View sync status indicators; cannot manually trigger syncs

Contractor

No Access

Cannot view QuickBooks sync status or trigger syncs

Client

No Access

Cannot view QuickBooks sync status or trigger syncs

3. User Flow

3.1 The user navigates to Finances > Billing from the left sidebar menu.

3.2 The user clicks on the "Transactions" tab to view all financial transactions.

3.3 The system displays the transaction list with tabs for Unpaid, Processing, Paid, Overdue, Failed, and Refunds.

3.4 The user views the "Paid" tab which shows all successfully completed payment transactions.

3.5 For each transaction, the user can see the QuickBooks sync icon in the row indicating sync status.

3.6 If the QuickBooks icon shows a green/success state, the transaction has been successfully synced to QuickBooks.

3.7 If the QuickBooks icon shows a failed/error state, the transaction failed to sync.

3.8 The user clicks on the three-dot action menu (⋮) for a specific transaction.

3.9 The system displays action options including "Sync with QuickBooks" for transactions that failed to sync.

3.10 The user clicks "Sync with QuickBooks" to manually retry the sync for the failed transaction.

3.11 The system attempts to sync the transaction to QuickBooks in the background.

3.12 Upon successful sync, the QuickBooks icon updates to show the synced state.

3.13 If the manual sync fails, the system displays an error message and the icon remains in the failed state.

3.14 When the first payment is made on an invoice, the system syncs the entire invoice to QuickBooks including all packages, line items, and discounts.

3.15 For client payments, the system creates a Sales Receipt in QuickBooks upon successful payment.

3.16 For contractor payments, the system creates an Expense entry in QuickBooks upon successful payment.

3.17 When a client makes their first payment, the system automatically creates a Customer profile in QuickBooks.

3.18 When a contractor receives their first payment, the system automatically creates a Vendor profile in QuickBooks.

3.19 When a refund is issued, the system creates a Refund Receipt in QuickBooks linked to the original transaction.

4. Functional Logic

4.1 One-Way Integration Direction

• The integration is strictly one-way: data flows only from Pixally to QuickBooks.
• No data is ever pulled from QuickBooks into Pixally.
• Changes made directly in QuickBooks do not reflect in Pixally.
• This design ensures Pixally remains the source of truth for all financial transactions.

4.2 Sync Trigger and Timing

• Transaction sync is triggered in real-time when a payment is successfully processed in Pixally.
• The sync happens automatically in the background without user intervention.
• There is no batch or scheduled sync; each transaction syncs individually upon completion.
• Sync is only attempted for brands that have QuickBooks connected and at least one account mapped.
• If a transaction fails to sync, it remains in a "failed" state until the user manually retries.

4.3 Prerequisites for Syncing

• The brand associated with the transaction must have an active QuickBooks connection.
• At least one relevant account must be mapped (e.g., Income for payments).
• The user's subscription plan must include QuickBooks integration.
• If QuickBooks is disconnected or account mapping is incomplete, transactions are not synced.
• Transactions that occur while QuickBooks is disconnected will not be synced later (data gap).

4.4 Customer Creation in QuickBooks

• When a client makes their first payment in Pixally, the system automatically creates a corresponding Customer record in QuickBooks.
• The customer is created using the Primary Client's email as the unique identifier for mapping.
• The customer name in QuickBooks matches the Primary Client's name from the Pixally project.
• The customer's billing address is synced from Pixally to QuickBooks (Bill to address).
• If shipping information is available in Pixally, the Ship to address is also synced.
• If a project has multiple clients (e.g., Bride and Groom), all transactions are linked to the Primary Client.
• The actual payer's name (if different from Primary Client) is captured in the transaction notes/memo field.
• Subsequent payments from the same project use the existing customer record in QuickBooks.
• The customer profile is stored in QuickBooks and reused for all future transactions from that client.

4.5 Vendor Creation in QuickBooks (for Contractors)

• When a contractor receives their first payment from an agency in Pixally, the system automatically creates a corresponding Vendor record in QuickBooks.
• The vendor is created using the Contractor's email as the unique identifier for mapping.
• Email is mandatory for contractor profile creation; if a contractor does not have an email in Pixally, the sync will fail with an error.
• The vendor name in QuickBooks matches the Contractor's name from Pixally.
• Subsequent payments to the same contractor use the existing vendor record in QuickBooks.
• The vendor profile is stored in QuickBooks and reused for all future expense transactions for that contractor.

4.6 Invoice Creation in QuickBooks

• The invoice is created in QuickBooks only when the first payment is made on the Pixally invoice (not when the invoice is created in Pixally).
• The entire invoice is synced to QuickBooks including all packages and line items.
• Each package and its line items appear as separate line items in the QuickBooks invoice.
• For each line item, the following fields are synced: Product/Service name, Description, Quantity, Rate, Amount, and Tax applicability.
• If a discount is applied to the invoice, it is synced as a separate negative line item on the QuickBooks invoice (e.g., "Discount - 10%" with -$100 amount).
• The discount line item reduces the invoice total but is not posted to the Refund account.
• The Pixally Invoice ID is synced to QuickBooks for reference and reconciliation.
• The invoice in QuickBooks is linked to the customer record.
• Payment terms (e.g., Net 30) are synced if available in Pixally.
• Shipping information (Ship to, Ship from, Shipping date, Tracking no., Ship via) is synced if available in Pixally.
• Invoice memo format: Brand | Project | Invoice # (e.g., "Gray Mullins | Test User | #GRA-INV-1783673886").
• The memo is written to the "Memo on statement" field in QuickBooks.

4.7 Payment Sync (Client Payments - Income)

• When a client payment is successfully processed in Pixally (status: Paid), it syncs to QuickBooks.
• The system creates a Sales Receipt in QuickBooks for the payment.
• The Sales Receipt is linked to the corresponding customer and invoice in QuickBooks.
• The gross payment amount (before Stripe fees) is recorded as income.
• The payment is posted to the QuickBooks account mapped for "Income".
• Payment details synced include: amount, payment date, payment method reference.
• Each payment term (Term 1, Term 2, etc.) is synced individually when it gets paid, not the full payment schedule.
• Payment memo format: Brand | Project | Invoice # | Payment term | Payment method (e.g., "Gray Mullins | Test User | #GRA-INV-1783673886 | Term 1 payment | Cash").
• The memo is written to the "Memo on statement" field in QuickBooks.

4.8 Transaction Fields Synced to QuickBooks

The following data fields are synced for each transaction:

For Invoice:

Field

Description

QuickBooks Mapping

Invoice ID

Pixally invoice identifier

Invoice Number

Client Name

Primary client's full name

Customer Name

Client Email

Primary client's email address

Customer Email (identifier)

Bill to Address

Client's billing address

Bill to

Ship to Address

Shipping address (if available)

Ship to

Ship from Address

Origin address (if available)

Ship from

Shipping Date

Shipping date (if available)

Shipping date

Tracking Number

Tracking number (if available)

Tracking no.

Ship via

Shipping method (if available)

Ship via

Payment Terms

Payment terms (if available)

Terms

Invoice Date

Date invoice was created

Invoice date

Due Date

Payment due date

Due date

Line Items

All packages and their line items

Product/Service lines

Line Item Description

Package name, item description

Description

Line Item Quantity

Quantity

Qty

Line Item Rate

Unit rate

Rate

Line Item Amount

Total amount

Amount

Line Item Tax

Tax applicability per item

Tax checkbox

Discount

Discount as negative line item

Separate line item

Invoice Memo

Brand | Project | Invoice #

Memo on statement

For Client Payments (Sales Receipt):

Field

Description

QuickBooks Mapping

Client Name

Primary client's full name

Customer Name

Client Email

Primary client's email address

Customer Email (identifier)

Invoice ID

Pixally invoice identifier

Invoice Reference

Amount

Transaction amount (gross)

Sales Receipt Amount

Payment Date

Date the payment was processed

Transaction Date

Payment Term

Which payment term (Term 1, Term 2, etc.)

Memo field

Payment Method

Payment method used

Payment Method

Payment Memo

Brand | Project | Invoice # | Payment term | Payment method

Memo on statement

Stripe Transaction Reference

Stripe's transaction ID (if applicable)

Reference field

For Contractor Payments (Expense):

Field

Description

QuickBooks Mapping

Contractor Name

Contractor's full name

Vendor Name

Contractor Email

Contractor's email address

Vendor Email (identifier)

Payment Amount

Amount paid to contractor

Expense Amount

Payment Date

Date the payment was processed

Transaction Date

Project Name

Associated Pixally project

Memo field

Invoice ID

Associated Pixally invoice

Reference field

Payment Method

Payment method used

Payment Method

Expense Memo

Brand | Project | Invoice # | Contractor name | Payment method

Memo on statement

Stripe Transaction Reference

Stripe's transaction ID (if applicable)

Reference field

4.9 Partial Payment Handling

• A single Pixally invoice may receive multiple partial payments.
• Only one invoice is created in QuickBooks for each Pixally invoice.
• Each partial payment is recorded as a separate Sales Receipt against that invoice.
• The QuickBooks invoice shows the total amount and tracks remaining balance.
• When all partial payments are received, the invoice shows as fully paid in QuickBooks.
• The payment count indicator (e.g., "1 of 2") in Pixally helps track partial payment progress.

4.10 Multiple Payers on Same Invoice

• If different people make payments toward the same invoice, all payments are linked to the Primary Client.
• The Primary Client is the designated main contact for the project in Pixally.
• The actual payer's name is captured in the payment notes/memo field for reference.
• This approach ensures clean invoice-payment matching in QuickBooks while preserving payer information.
• Example: If both "Bride" and "Groom" pay toward the same wedding invoice, both payments appear under the Primary Client (e.g., "Bride") in QuickBooks.

4.11 Stripe Fee Handling - Client Payments

• When a client pays, Stripe deducts a processing fee before depositing funds.
• The system syncs the gross amount (full payment) as income to the mapped "Income" account.
• The Stripe fee is synced as a separate expense entry to the mapped "OPEX" account.
• If no OPEX account is mapped, the system uses the auto-created "Pixally Transaction Fees" account.
• Example: Client pays $100, Stripe deducts $3 fee → Pixally syncs $100 income + $3 OPEX expense.
• This approach ensures accurate net income reporting in QuickBooks.

4.12 Auto-Creation of Pixally Transaction Fees Account

• The Pixally system automatically creates a dedicated account called "Pixally Transaction Fees" in QuickBooks.
• This account is created under the Expenses category with detail type "Other Miscellaneous Service Cost".
• The account is created automatically when the first Stripe fee needs to be synced, if no OPEX account is mapped.
• The account is created once per QuickBooks company, regardless of how many Pixally brands are connected.
• If the user maps an OPEX account, Stripe fees are posted to the mapped OPEX account instead of "Pixally Transaction Fees".
• If the user later changes the OPEX account mapping, future fees go to the new account while past fees remain in the original account.

4.13 Refund Sync

• When a refund is issued in Pixally, the system creates a Refund Receipt in QuickBooks.
• The Refund Receipt is the exact mirror of the original payment (Sales Receipt).
• The refund reduces the same Income account and returns the money from the same bank/deposit account.
• The refund is posted to the QuickBooks account mapped for "Refund" (Income > Discounts/Refunds Given).
• Partial refunds are supported; the system creates a Refund Receipt for just the refunded amount.
• Refund Receipt details include: amount, refund date, original invoice reference, customer reference.
• Refund memo format: Brand | Project | Invoice # | Refund notes (e.g., "Gray Mullins | Test User | #GRA-INV-1783673886 | Client requested refund").
• The memo is written to the "Memo on statement" field in QuickBooks.

4.14 Contractor Payment Sync (Expenses)

• When an agency pays a contractor through Pixally, the payment syncs to QuickBooks as an Expense transaction.
• The system does NOT create receipts or bills for contractor payments; it uses a direct Expense entry method.
• The payment is posted to the account mapped for "COGS" (Cost of Goods Sold).
• If no COGS account is mapped, contractor payment sync will fail with an error prompting the user to configure the COGS account.
• The contractor is created as a Vendor in QuickBooks using their email as the unique identifier.
• The expense transaction is linked to the Vendor record in QuickBooks.
• Contractor payment details include: contractor name, contractor email, amount, payment date, project name, invoice reference, payment method.
• Expense memo format: Brand | Project | Invoice # | Contractor name | Payment method (e.g., "Gray Mullins | Test User | #GRA-INV-1783673886 | John Doe | Bank Transfer").
• The memo is written to the "Memo on statement" field in QuickBooks.

Update and Delete Support:

• If a contractor payment is edited in Pixally, the corresponding Expense entry in QuickBooks is automatically updated.
• If a contractor payment is deleted in Pixally, the corresponding Expense entry in QuickBooks is automatically deleted.
• The system maintains a mapping between Pixally transaction IDs and QuickBooks transaction IDs to support update and delete operations.

4.15 Stripe Fee Handling - Contractor Payments

• When an agency pays a contractor, Stripe charges an additional processing fee.
• Example: Agency pays $100 to contractor + $5 Stripe fee = $105 total.
• The system syncs the contractor payment ($100) as one expense entry to the "COGS" account.
• The Stripe fee ($5) is synced as a separate expense entry to the "OPEX" account or "Pixally Transaction Fees" account.
• This ensures accurate expense tracking beyond gross payment amounts.

4.16 Tax Amount Handling

• If the user has configured a Tax Account in the QuickBooks account mapping, tax amounts are synced accordingly.
• The tax is posted to the mapped Sales Tax Payable liability account.
• Tax amounts on invoices are included in the transaction sync.
• The specific tax handling depends on the QuickBooks tax configuration.
• If Automated Sales Tax is enabled in QuickBooks, tax calculations are handled by QuickBooks automatically.

4.17 Sync Status Indicator

• A QuickBooks sync icon is displayed next to each transaction in the Billing > Transactions list.
• The icon is only visible for brands that have QuickBooks connected.
• The icon has two visual states:
  • Synced (Success): Green QuickBooks icon indicating successful sync.
  • Failed: QuickBooks icon with error indicator showing sync failed.
• Hovering over the icon may display a tooltip with sync timestamp or error details.
• Transactions for brands without QuickBooks connection do not show the icon.

4.18 Manual Sync Retry

• For transactions that failed to sync, users can manually retry the sync.
• The "Sync with QuickBooks" option appears in the transaction action menu (⋮).
• This option is only visible for failed/unsynced transactions.
• Clicking "Sync with QuickBooks" triggers an immediate sync attempt.
• The system provides feedback on whether the retry succeeded or failed.
• There is no automatic retry mechanism; users must manually initiate retries.

4.19 Sync Failure Scenarios

• Sync may fail due to: QuickBooks API unavailability, invalid OAuth token, network issues, or data validation errors.
• Failed syncs do not block the transaction from completing in Pixally.
• The transaction is marked with a failed sync status in the UI.
• Users can retry the sync at any time through the action menu.
• If OAuth token has expired, the user may need to reconnect QuickBooks.

4.20 Data Accuracy and Integrity

• The integration prioritizes data accuracy because QuickBooks data directly impacts tax filings and financial reporting.
• Detailed field mapping ensures comprehensive data transfer.
• The backend system processes syncs carefully to avoid duplicate entries.
• Sync timestamps are logged for audit purposes.
• Historical data is maintained even if account mappings change (past syncs remain in original accounts).

4.21 Known Limitations

• Historical Transaction Sync: Transactions that occur while QuickBooks is disconnected cannot be synced later. Only transactions from the connection date forward are synced. This is a known limitation for Phase 1.
• Data Gap During Disconnection: If a user disconnects and later reconnects QuickBooks, transactions during the offline period are not retroactively synced.
• One-Way Only: Users cannot push QuickBooks data to Pixally or reconcile discrepancies.

5. Field Details & Validations

Field Name

Field Type

Description

Validation Rules

Transaction Amount

Decimal

Gross payment amount

Must be positive; synced as-is to QuickBooks

Payment Date

Date

Date transaction was processed

Must be a valid date; synced in QB format

Invoice ID

String

Pixally invoice identifier

Required for payment matching

Client Email

Email

Primary client's email

Used as customer identifier in QB

Client Name

String

Primary client's full name

Used as customer display name in QB

Contractor Email

Email

Contractor's email address

Mandatory for vendor creation; sync fails if missing

Project Name

String

Pixally project name

Synced to notes/memo field

Stripe Fee

Decimal

Processing fee deducted by Stripe

Synced as separate expense entry to OPEX

Refund Amount

Decimal

Amount being refunded

Must not exceed original payment; synced to refunds account

Contractor Payment Amount

Decimal

Amount paid to contractor

Synced as expense to COGS account

6. Success Message Handling

Action

Success Message

Display Location

Post-Action Behavior

Automatic sync completed

N/A (Background process)

N/A

Sync icon updates to "Synced" state

Manual sync retry successful

"Transaction synced to QuickBooks successfully."

Toast notification (top-right)

Sync icon updates to "Synced" state

Customer created in QB

N/A (Background process)

N/A

Logged in system; no user message

Vendor created in QB

N/A (Background process)

N/A

Logged in system; no user message

Invoice created in QB

N/A (Background process)

N/A

Logged in system; no user message

7. Error Message Handling

Error Scenario

Error Message

Display Location

Trigger Condition

User Action Required

QuickBooks API unavailable

"Unable to sync with QuickBooks. Please try again later."

Toast notification

QuickBooks API returns error

Retry later using manual sync

OAuth token expired

"QuickBooks connection expired. Please reconnect QuickBooks."

Toast notification

OAuth refresh token invalid

Reconnect QuickBooks from Integrations

Account mapping missing

"Cannot sync transaction. Please configure QuickBooks account mappings."

Toast notification

No account mapped for transaction type

Complete account mapping in Integrations

COGS account not mapped

"Cannot sync contractor payment. Please configure the COGS account mapping."

Toast notification

Contractor payment without COGS mapped

Map COGS account in Integrations

Contractor email missing

"Cannot sync contractor payment. Contractor email is required."

Toast notification

Contractor has no email in Pixally

Add email to contractor profile

Network error

"Network error. Transaction will sync when connection is restored."

Toast notification

No internet connectivity

Check network; transaction will remain in failed state

Duplicate transaction detected

"This transaction has already been synced to QuickBooks."

Toast notification

Attempting to sync already-synced transaction

No action needed

Invalid data format

"Unable to sync due to data error. Please contact support."

Toast notification

Data fails QuickBooks validation

Contact support for resolution

Manual sync failed

"Failed to sync transaction. Please try again."

Toast notification

Manual retry unsuccessful

Retry again or check QB connection

QuickBooks subscription expired

"QuickBooks sync unavailable. Your QuickBooks subscription may have expired."

Toast notification

QB account inactive

Verify QuickBooks subscription status

8. Edge Cases

Edge Case

Scenario Description

Expected System Behavior

Payment before QB connected

Client pays before QuickBooks is connected to the brand

Transaction is recorded in Pixally but not synced; no QB icon shown

Payment during disconnection

Client pays while QB is temporarily disconnected

Transaction is not synced; remains in Pixally only; creates data gap

Zero-amount transaction

A transaction with $0 amount (e.g., fully discounted)

System skips sync; no entry created in QuickBooks

Very large transaction

Transaction amount exceeds typical limits

System syncs as normal; QuickBooks handles large numbers

Multiple payments same second

Two payments processed at the exact same time

Each payment syncs independently; no conflicts

Refund exceeds payment

User attempts to refund more than original payment

Prevented by Pixally; refund limited to original amount

Partial refund

User refunds only a portion of the original payment

Partial refund syncs as Refund Receipt to QB; original invoice updated accordingly

Client email changed

Primary client's email is changed after customer created in QB

New email not synced; existing QB customer retained

Project name special characters

Project name contains special characters

Characters are sanitized or escaped for QB compatibility

Stripe fee is $0

Transaction processed with no Stripe fee

No fee expense entry created; only income synced

Contractor paid without COGS mapped

Agency pays contractor but no COGS account is configured

Payment sync fails; error shown; user must map COGS account

Contractor without email

Agency pays contractor who has no email in Pixally

Payment sync fails; error shown; user must add email to contractor

Same client, different projects

Same client makes payments for different projects

Same QB customer used; each project has its own invoice

Sync fails repeatedly

Transaction fails to sync after multiple manual retries

Transaction remains in failed state; user may need to contact support

Account mapping changed mid-transaction

User changes account mapping while transactions are pending

Pending transactions use new mapping; past syncs unchanged

Invoice with discount

Invoice has a discount applied

Discount syncs as negative line item on QB invoice

Invoice with multiple packages

Invoice contains multiple packages with line items

All packages and line items sync as separate lines in QB

9. Acceptance Criteria

Invoice Sync:

• AC1: The invoice is created in QuickBooks only when the first payment is made (not when created in Pixally).
• AC2: All packages and line items are synced as separate line items in the QuickBooks invoice.
• AC3: Each line item includes: Product/Service name, Description, Quantity, Rate, Amount, and Tax applicability.
• AC4: If a discount is applied, it appears as a separate negative line item on the QuickBooks invoice.
• AC5: Client billing address is synced to the Bill to field in QuickBooks.
• AC6: Shipping information (Ship to, Ship from, Shipping date, Tracking no., Ship via) is synced if available in Pixally.
• AC7: Payment terms are synced if available in Pixally.
• AC8: Invoice memo follows format: Brand | Project | Invoice #.

Customer and Vendor Creation:

• AC9: A new Customer is created in QuickBooks on the first client payment using Primary Client's email and name.
• AC10: A new Vendor is created in QuickBooks on the first contractor payment using Contractor's email (mandatory) and name.

Payment Sync:

• AC11: Client payments sync to QuickBooks as Sales Receipts upon successful payment (status: Paid).
• AC12: Each payment term is synced individually when it gets paid.
• AC13: Payment memo follows format: Brand | Project | Invoice # | Payment term | Payment method.
• AC14: Multiple partial payments are correctly recorded as separate Sales Receipts against a single QuickBooks invoice.

Stripe Fees:

• AC15: Stripe processing fees are synced as separate expense entries to the mapped "OPEX" account or auto-created "Pixally Transaction Fees" account.
• AC16: The "Pixally Transaction Fees" account is auto-created by Pixally in QuickBooks under Expenses if it doesn't exist and no OPEX account is mapped.

Refunds:

• AC17: Refunds are synced as Refund Receipts to the mapped "Refund" account.
• AC18: Refund Receipt reduces the same Income account and returns money from the same bank/deposit account.
• AC19: Partial refunds create a Refund Receipt for just the refunded amount.
• AC20: Refund memo follows format: Brand | Project | Invoice # | Refund notes.

Contractor Payments:

• AC21: Contractor payments sync as Expense entries (not receipts or bills) to the mapped "COGS" account in QuickBooks.
• AC22: Contractor payment Expense entries support update and delete operations from Pixally.
• AC23: If a contractor payment is edited in Pixally, the corresponding Expense in QuickBooks is automatically updated.
• AC24: If a contractor payment is deleted in Pixally, the corresponding Expense in QuickBooks is automatically deleted.
• AC25: Expense memo follows format: Brand | Project | Invoice # | Contractor name | Payment method.
• AC26: Contractor payment sync fails with an error if COGS account is not mapped.
• AC27: Contractor payment sync fails with an error if contractor email is missing in Pixally.

General:

• AC28: A QuickBooks sync icon is visible next to each transaction for connected brands.
• AC29: The sync icon shows "Synced" (success) or "Failed" state accurately.
• AC30: Users can manually retry failed syncs via the "Sync with QuickBooks" action.
• AC31: Transactions for disconnected brands do not show sync icons or sync options.
• AC32: Historical transactions (before connection) are not synced retroactively.
• AC33: Multiple payers on the same invoice are handled via Primary Client approach with payer info in notes.
• AC34: All memos are written to the "Memo on statement" field in QuickBooks.

10. Manual Test Cases

Link: Test Cases - Pixally to QuickBooks Sync of Income and Expense

11. Dependencies

Dependency Type

Dependency Name

Description

Impact if Unavailable

External Service

QuickBooks Online API

Handles all data sync operations

Syncing fails; transactions remain in Pixally only

External Service

QuickBooks Customers API

Creates/retrieves customer records

Cannot link payments to customers

External Service

QuickBooks Vendors API

Creates/retrieves vendor records

Cannot link contractor payments to vendors

External Service

QuickBooks Invoices API

Creates/updates invoice records

Cannot create invoices; payment sync fails

External Service

QuickBooks Sales Receipts API

Creates Sales Receipt records

Cannot record client payments in QB

External Service

QuickBooks Refund Receipts API

Creates Refund Receipt records

Cannot record refunds in QB

External Service

QuickBooks Expenses API

Creates/updates Expense records

Cannot record contractor payments in QB

External Service

QuickBooks Accounts API

Creates expense accounts (for fees)

Cannot auto-create fee account; manual setup required

External Service

Stripe API

Provides transaction and fee details

Fee information unavailable; only gross amount synced

Internal Module

Billing/Payments Module

Provides transaction data to sync

No transactions to sync

Internal Module

Projects Module

Provides project and client information

Missing project/client details in sync

Internal Module

QuickBooks Connection Store

Stores OAuth tokens and account mappings

Cannot authenticate with QB; sync fails

Internal Database

Transaction Sync Log

Tracks sync status for each transaction

Cannot determine sync status; potential duplicates

12. References

• Figma Designs:

Modify QB Charts of Accounts from Pixally

Functional Requirements Document (FRD)

Modify QuickBooks Charts of Accounts from Pixally

Module: QuickBooks Integration
Sub-Module: Modify QuickBooks Charts of Accounts from Pixally
Version: 1.1

1. Module Overview

Module Name: Modify QuickBooks Charts of Accounts from Pixally

Purpose: This sub-module allows agency users to view and modify the QuickBooks account mappings for a connected brand without disconnecting and reconnecting. Users can change which QuickBooks accounts are used for income, refunds, COGS, OPEX, and sales tax directly from the expanded row view in the brandwise listing. This enables flexibility in account management as business needs evolve.

Business Goals:

• Enable users to update QuickBooks account mappings without requiring reconnection.
• Provide the ability to refresh the chart of accounts list when new accounts are created in QuickBooks.
• Ensure that changes to account mappings only affect future transactions while preserving historical data integrity.
• Support evolving business accounting structures without disrupting existing financial records.

2. User Roles & Permissions

Role

Access Level

Permissions

Agency Owner

Full Access

View account mappings, modify all dropdowns, refresh account list, save changes

Agency Admin

Full Access

View account mappings, modify all dropdowns, refresh account list, save changes

Agency Manager

View Only

Can expand rows to view mappings; cannot modify or save

Contractor

No Access

Cannot access the Integrations module

Client

No Access

Cannot access the Integrations module

3. User Flow

3.1 The user navigates to Tools > Integrations > QuickBooks Online to access the brandwise listing page.

3.2 The user identifies a brand with "Connected" status that they want to modify.

3.3 The user clicks the expand chevron (▼) on the left side of the brand row.

3.4 The system expands the row to reveal the account mapping section below the brand details.

3.5 The expanded section displays instructional text: "Define the accounts to which payments, taxes, service charges, and refunds should be allocated."

3.6 The system displays five dropdown fields showing the currently mapped QuickBooks accounts: Income, Refund, COGS, OPEX, and Tax Account.

3.7 The user clicks on a dropdown to view available QuickBooks accounts.

3.8 The system displays the list of accounts fetched from QuickBooks, filtered by the appropriate account type.

3.9 The user selects a different account from the dropdown to change the mapping.

3.10 The user cannot clear the mandatory Income dropdown once it has been configured.

3.11 If the user needs accounts that were recently created in QuickBooks, they click the "Refresh" button.

3.12 The system fetches the latest chart of accounts from QuickBooks and updates the dropdown options.

3.13 After making changes, the user clicks the "Save" button to save the new account mappings.

3.14 The system displays a warning message: "Changing this account mapping will only affect future transactions. Previously synced transactions will remain in their original QuickBooks accounts."

3.15 The user confirms the change, and the system saves the new mappings.

3.16 The system displays a success message confirming the changes were saved.

3.17 The user can click the chevron again to collapse the expanded row.

4. Functional Logic

4.1 Expanded Row Access

• Only brands with "Connected" status can have their rows expanded.
• Clicking the chevron icon (▼) on a connected brand expands the row downward.
• The chevron icon rotates to (▲) when the row is expanded, indicating it can be collapsed.
• Clicking the chevron again collapses the row back to its original state.
• Only one brand row can be expanded at a time; expanding a new row auto-collapses the previously expanded row.

4.2 Expanded Section Layout

• The expanded section appears directly below the brand row within the table.
• The section is visually indented or styled to show it belongs to the brand above.
• The section header displays: "Define the accounts to which payments, taxes, service charges, and refunds should be allocated."
• Five dropdown fields are displayed in a grid layout: Income, Refund, COGS, OPEX, and Tax Account.
• A "Refresh" button is available to reload the chart of accounts from QuickBooks.
• A "Save" button is available to save any changes made to the dropdowns.

4.3 Account Mapping Dropdowns (Display)

The expanded section displays five dropdown fields. The Income dropdown is mandatory and cannot be cleared once configured.

Dropdown 1: Income (Mandatory)

• Label: "Select the default QuickBooks account for income"
• Displays the currently selected account, or placeholder if not configured
• Populated with accounts of type "Income" and "Cash on Hand" from QuickBooks
• This field is mandatory and cannot be cleared once an account is selected

Dropdown 2: Refund

• Label: "Select the QuickBooks account to associate with refunds"
• Displays the currently selected account, or placeholder if not configured
• Populated with accounts of type "Income" and subtype "Discounts/Refunds Given" from QuickBooks

Dropdown 3: COGS (Cost of Goods Sold)

• Label: "Select the QuickBooks account for cost of goods sold"
• Displays the currently selected account, or placeholder if not configured
• Populated with accounts of type "Expense" and subtypes "Cost of Goods Sold" and "Labor Cost" from QuickBooks

Dropdown 4: OPEX (Operating Expenses)

• Label: "Select the QuickBooks account for operating expenses"
• Displays the currently selected account, or placeholder if not configured
• Populated with accounts of type "Expense" from QuickBooks

Dropdown 5: Tax Account (Sales Tax Payable)

• Label: "Select the QuickBooks account for sales tax payable"
• Displays the currently selected account, or placeholder if not configured
• Populated with accounts of type "Other Current Liability" and subtype "Sales Tax Payable" from QuickBooks
• If no liability accounts exist, shows prompt: "No tax accounts found. Please create a Sales Tax Payable account in QuickBooks."
• If Automated Sales Tax is detected, dropdown is disabled with message: "Your QuickBooks uses Automated Sales Tax. Please use your existing tax agency account."

4.4 Viewing Current Mappings

• When the row is expanded, all five dropdowns display the currently saved account mappings.
• If an account was not previously configured (e.g., user clicked "Skip for Now" during initial setup), the dropdown shows the placeholder text: "Select your QuickBooks account".
• The current selection is highlighted in the dropdown when opened.
• Users can see at a glance which accounts are configured and which are missing.
• The Income dropdown always has a value (since it is mandatory during initial setup).
• The Tax Account dropdown may be disabled if Automated Sales Tax is detected in QuickBooks.

4.5 Modifying Account Mappings

• Users can click any dropdown to open it and view available accounts.
• Selecting a different account changes the dropdown value but does not save immediately.
• The user must click "Save" to persist the changes.
• Multiple dropdowns can be changed before clicking Save; all changes are saved together.
• If the user collapses the row without saving, unsaved changes are discarded.

4.6 Dropdown Value Restrictions

• Users cannot clear a dropdown back to empty/unselected once an account has been previously configured.
• The dropdown must always have a valid selection after initial configuration.
• This ensures that transactions continue to sync properly without interruption.
• If users need to stop syncing a specific transaction type, they should disconnect QuickBooks entirely.

4.7 Refresh Account List Functionality

• The "Refresh" button triggers a real-time fetch of the chart of accounts from QuickBooks.
• This is useful when users have created new accounts in QuickBooks and need them to appear in Pixally.
• Clicking Refresh does not affect current selections; it only updates the available options.
• The refresh operation fetches all account types and tax rates from QuickBooks.
• A loading indicator is displayed while the refresh is in progress.
• Upon completion, a success message confirms: "Account list refreshed successfully."
• If the refresh fails, an error message is displayed with an option to retry.

4.8 Save Behavior

• The "Save" button is always visible in the expanded section.
• Clicking Save validates that all modified dropdowns have valid selections.
• Before saving, the system displays a warning message explaining the impact:
  • "Changing this account mapping will only affect future transactions. Previously synced transactions will remain in their original QuickBooks accounts."
• The warning is displayed as an inline alert or confirmation dialog.
• The user must acknowledge the warning to proceed with saving.
• Upon confirmation, the system saves the new mappings to the database.
• A success toast notification is displayed: "Account mapping saved successfully."

4.9 Impact on Past vs Future Transactions

• Changes to account mappings only affect transactions that are synced AFTER the change is saved.
• Transactions that were previously synced remain in their original QuickBooks accounts.
• This maintains historical accuracy and prevents confusion in financial records.
• If a user changes the "Income" account from "Sales Income" to "Service Revenue", future payments go to "Service Revenue" while past payments remain in "Sales Income".
• This behavior is by design and is communicated clearly in the warning message.

4.10 Incomplete Mapping Warning

• If the user completes account mapping after initially skipping, the warning tooltip on the status badge is removed.
• The brand's sync functionality becomes fully operational once all relevant accounts are mapped.
• Users do not need to configure all five accounts; partial configuration is allowed.
• Transactions will only sync for transaction types that have accounts mapped.

4.11 Concurrent Edit Prevention

• If another admin is editing the same brand's mappings simultaneously, the system handles this gracefully.
• The last save wins; the most recent changes overwrite previous ones.
• No locking mechanism is implemented; users should coordinate changes.

4.12 Session and Token Validation

• Before saving changes, the system validates that the QuickBooks OAuth token is still valid.
• If the token has expired, the system prompts the user to reconnect QuickBooks.
• Changes cannot be saved if the QuickBooks connection is invalid.

5. Field Details & Validations

Field Name

Field Type

Description

Validation Rules

Income Dropdown

Dropdown Select

QuickBooks account for income transactions

Mandatory; cannot be cleared once configured; must be valid Income or Cash on Hand account

Refund Dropdown

Dropdown Select

QuickBooks account for refund transactions

Cannot be cleared once configured; must be valid Income account with Discounts/Refunds Given subtype

COGS Dropdown

Dropdown Select

QuickBooks account for cost of goods sold

Cannot be cleared once configured; must be valid Expense account with COGS or Labor Cost subtype

OPEX Dropdown

Dropdown Select

QuickBooks account for operating expenses

Cannot be cleared once configured; must be valid Expense account

Tax Account Dropdown

Dropdown Select

QuickBooks account for sales tax payable

Cannot be cleared once configured; must be valid Other Current Liability account; disabled if Automated Sales Tax detected

Refresh Button

Button

Reloads chart of accounts from QuickBooks

Enabled when row is expanded; disabled during refresh operation

Save Button

Button

Saves changes to account mappings

Enabled when row is expanded; triggers validation and warning

6. Success Message Handling

Action

Success Message

Display Location

Post-Action Behavior

Refresh account list

"Account list refreshed successfully."

Toast notification (top-right)

Dropdowns update with new accounts

Save account mappings

"Account mapping saved successfully."

Toast notification (top-right)

Row remains expanded; new values persisted

Expand row

N/A (No message)

N/A

Row expands with animation

Collapse row

N/A (No message)

N/A

Row collapses; unsaved changes discarded

7. Error Message Handling

Error Scenario

Error Message

Display Location

Trigger Condition

User Action Required

Refresh failed

"Unable to refresh account list. Please try again."

Toast notification

QuickBooks API error during refresh

Click Refresh again

Save failed

"Failed to save account mappings. Please try again."

Toast notification

Database or API error during save

Click Save again

OAuth token expired

"QuickBooks connection expired. Please reconnect to make changes."

Inline error in expanded section

Token invalid or expired

Reconnect QuickBooks from Integrations

Network error during refresh

"Network error. Please check your connection and try again."

Toast notification

No internet connectivity

Check network and retry

Network error during save

"Network error. Your changes were not saved."

Toast notification

No internet connectivity

Check network and click Save again

Invalid account selected

"The selected account is no longer valid in QuickBooks."

Inline error below dropdown

Account deleted in QB since last refresh

Refresh account list and select a different account

Concurrent edit conflict

N/A (Last save wins)

N/A

Another user saved changes simultaneously

Refresh the page to see latest mappings

8. Edge Cases

Edge Case

Scenario Description

Expected System Behavior

No changes made, Save clicked

User clicks Save without changing any dropdown

System saves (no-op); success message displayed

All dropdowns already configured

User expands row for a fully configured brand

All dropdowns show current selections; user can modify any

Some dropdowns not configured

User expands row for a partially configured brand

Unconfigured dropdowns show placeholder; user can select accounts

Account deleted in QuickBooks

A previously mapped account is deleted in QB

Dropdown shows the old account name; sync may fail; user should select new account

New account created in QB

User creates a new account in QB and wants to use it

User clicks Refresh to load the new account into dropdown options

Rapid Save clicks

User clicks Save multiple times quickly

System processes first click; subsequent clicks ignored until complete

Page refresh during edit

User refreshes browser while editing mappings

Unsaved changes are lost; page reloads with last saved mappings

Collapse without saving

User collapses row with unsaved changes

Changes are discarded; no warning shown (changes not critical)

Session expires during edit

User's Pixally session expires while editing

Session expired message on Save attempt; re-login required

QuickBooks disconnected

User tries to expand row after QB was disconnected

Row cannot be expanded; chevron is disabled

Expand during slow network

User clicks expand on slow connection

Loading indicator shown while fetching current mappings

Multiple brands expanded rapidly

User tries to expand multiple rows quickly

Only the last clicked row expands; others auto-collapse

Automated Sales Tax enabled

QuickBooks company has Automated Sales Tax

Tax Account dropdown is disabled with informational message

9. Acceptance Criteria

• AC1: Connected brands display an enabled expand chevron; clicking it expands the row.
• AC2: The expanded section shows instructional text and five account mapping dropdowns: Income, Refund, COGS, OPEX, and Tax Account.
• AC3: Each dropdown displays the currently mapped QuickBooks account (or placeholder if not configured).
• AC4: Dropdowns are populated with accounts from QuickBooks filtered by appropriate account type: Income (Income + Cash on Hand), Refund (Income + Discounts/Refunds Given), COGS (Expense + COGS/Labor Cost), OPEX (Expense), Tax Account (Other Current Liability + Sales Tax Payable).
• AC5: Users can select different accounts from the dropdowns to change mappings.
• AC6: Users cannot clear a dropdown back to empty once an account has been configured.
• AC7: The Income dropdown is mandatory and always has a value.
• AC8: The Tax Account dropdown shows only liability accounts (not tax rates).
• AC9: If no Sales Tax Payable accounts exist, the Tax Account dropdown shows a prompt to create one in QuickBooks.
• AC10: If Automated Sales Tax is detected, the Tax Account dropdown is disabled with an appropriate message.
• AC11: The Refresh button fetches the latest chart of accounts from QuickBooks.
• AC12: The Save button saves all dropdown changes and displays a success message.
• AC13: Before saving, a warning message explains that changes only affect future transactions.
• AC14: Changes to account mappings only affect transactions synced after the change.
• AC15: Previously synced transactions remain in their original QuickBooks accounts.
• AC16: Collapsing the row without saving discards any unsaved changes.
• AC17: Only one brand row can be expanded at a time.
• AC18: Appropriate error messages are displayed for refresh failures, save failures, and expired tokens.

10. Manual Test Cases

Link: Test Cases - Modify QuickBooks Charts of Accounts from Pixally

11. Dependencies

Dependency Type

Dependency Name

Description

Impact if Unavailable

External Service

QuickBooks Chart of Accounts API

Fetches available accounts for dropdown options

Dropdowns may be empty or stale; Refresh fails

External Service

QuickBooks Tax Rates API

Fetches available tax rates

Tax Account dropdown empty

Internal Module

QuickBooks Connection Store

Stores and retrieves account mappings

Cannot display current mappings; cannot save changes

Internal Module

OAuth Token Manager

Validates and refreshes OAuth tokens

Cannot communicate with QuickBooks

Internal Database

Account Mapping Storage

Persists user's account mapping selections

Changes are not saved

12. References

• Figma Designs:

Disconnect and Reconnect QB Integration

Functional Requirements Document (FRD)

Disconnect and Reconnect QuickBooks Integration with Pixally

Module: QuickBooks Integration
Sub-Module: Disconnect and Reconnect QuickBooks Integration with Pixally
Version: 1.0

1. Module Overview

Module Name: Disconnect and Reconnect QuickBooks Integration with Pixally

Purpose: This sub-module enables agency users to disconnect their Pixally brand from QuickBooks and subsequently reconnect if needed. It handles the complete disconnection flow including confirmation, cleanup of OAuth tokens, and provides guidance on reconnection. This supports scenarios where users need to switch QuickBooks accounts, troubleshoot issues, or temporarily disable the integration.

Business Goals:

• Allow users to cleanly disconnect QuickBooks when needed without affecting historical synced data.
• Provide clear warnings about the impact of disconnection on future sync operations.
• Enable easy reconnection to the same or a different QuickBooks account.
• Handle subscription downgrades that affect QuickBooks integration eligibility.

2. User Roles & Permissions

Role

Access Level

Permissions

Agency Owner

Full Access

Disconnect QuickBooks, initiate reconnection, view all brands

Agency Admin

Full Access

Disconnect QuickBooks, initiate reconnection, view all brands

Agency Manager

No Access

Cannot disconnect or reconnect QuickBooks

Contractor

No Access

Cannot access the Integrations module

Client

No Access

Cannot access the Integrations module

3. User Flow

Disconnection Flow:

3.1 The user navigates to Tools > Integrations > QuickBooks Online to access the brandwise listing page.

3.2 The user identifies a brand with "Connected" status that they want to disconnect.

3.3 The user clicks the "Disconnect" button in the Actions column for that brand.

3.4 The system displays a confirmation modal titled "Disconnect QuickBooks for [Brand Name]?".

3.5 The modal displays two warning bullet points:

• "Pixally will stop syncing transactions with your QuickBooks account."
• "Your current synced data in QuickBooks will remain unchanged."

3.6 The user reviews the warnings and can either click "Cancel" to abort or "Yes, Disconnect" to proceed.

3.7 If the user clicks "Cancel", the modal closes and no changes are made.

3.8 If the user clicks "Yes, Disconnect", the system revokes the OAuth tokens and removes the connection.

3.9 The system displays a success message: "QuickBooks disconnected for [Brand Name]."

3.10 The brand's row updates to show "Not Connected" status with a "Connect" button.

3.11 The expand chevron for that brand becomes disabled.

Reconnection Flow:

3.12 After disconnection, the user can reconnect by clicking the "Connect" button for the brand.

3.13 The system initiates the standard connection flow (as covered in FRD 2).

3.14 During the "Define The Accounts" modal, the system displays a warning about data gaps:

• "Note: Transactions that occurred while QuickBooks was disconnected will not be synced."

3.15 The user completes the connection setup as normal.

3.16 After reconnection, only new transactions (from the reconnection date forward) will sync.

4. Functional Logic

4.1 Disconnection Initiation

• The disconnection flow is initiated when a user clicks the "Disconnect" button for a connected brand.
• The system first validates that the user has permission to disconnect (Agency Owner or Agency Admin only).
• The system displays a confirmation modal before proceeding with disconnection.
• No disconnection occurs until the user explicitly confirms by clicking "Yes, Disconnect".

4.2 Confirmation Modal

• The modal header displays: "Disconnect QuickBooks for [Brand Name]?"
• The modal body contains two warning bullet points explaining the impact.
• The first warning: "Pixally will stop syncing transactions with your QuickBooks account."
• The second warning: "Your current synced data in QuickBooks will remain unchanged."
• The modal footer contains two buttons: "Cancel" (secondary) and "Yes, Disconnect" (primary, red/danger style).

4.3 OAuth Token Revocation

• Upon confirmation, the system revokes the OAuth access and refresh tokens with QuickBooks.
• The system calls the Intuit OAuth revocation endpoint to invalidate the tokens.
• Even if the revocation API call fails, the local connection is removed (tokens become orphaned).
• The system clears all stored OAuth tokens and connection metadata for the brand.

4.4 Account Mapping Cleanup

• When a brand is disconnected, the account mapping selections are NOT retained.
• If the user reconnects, they must configure the account mappings again.
• This ensures clean state and prevents stale mappings from causing issues.

4.5 Post-Disconnection State

• After disconnection, the brand's status changes to "Not Connected" in the brandwise listing.
• The QuickBooks Company ID column is cleared (shows empty).
• The "Disconnect" button is replaced with a "Connect" button.
• The expand chevron becomes disabled and grayed out.
• The QuickBooks sync icon no longer appears next to transactions for this brand.

4.6 Impact on Synced Data

• Previously synced transactions remain in QuickBooks; they are NOT deleted.
• Customers, invoices, and payments created in QuickBooks are unaffected.
• The disconnection only stops future syncing; it does not undo past syncs.

4.7 Impact on Pending Transactions

• If there are transactions in "Processing" state when disconnection occurs, they will not sync.
• Transactions created after disconnection will not sync until reconnection.
• This creates a "data gap" in QuickBooks for the disconnected period.

4.8 Reconnection Process

• Users can reconnect at any time by clicking the "Connect" button.
• The reconnection follows the same flow as initial connection (FRD 2).
• The user can reconnect to the same QuickBooks account or a different one.
• New OAuth tokens are obtained during reconnection.
• Account mappings must be reconfigured during reconnection.

4.9 Data Gap Warning on Reconnection

• During reconnection, the "Define The Accounts" modal displays an additional warning.
• The warning states: "Note: Transactions that occurred while QuickBooks was disconnected will not be synced."
• This ensures users understand that historical data from the gap period is not retroactively synced.

4.10 Subscription Downgrade Handling

• If a user's subscription is downgraded and no longer includes QuickBooks integration, the integration is automatically disconnected.
• The QuickBooks card is hidden from the Integrations page for downgraded users.
• If the user later upgrades their subscription:
  • The QuickBooks card becomes visible again.
  • All brands show "Not Connected" status (previous connections are not restored).
  • The user must manually connect each brand to QuickBooks.
  • Data gap exists from downgrade date to reconnection date.

4.11 Accidental Disconnection Prevention

• The confirmation modal with clear warnings helps prevent accidental disconnection.
• The "Yes, Disconnect" button is styled in red to indicate a destructive action.
• Users must explicitly click the red button to proceed; there is no auto-dismiss.
• The "Cancel" button provides an easy way to abort the action.

4.12 Multiple Brands Disconnection

• Each brand must be disconnected individually; there is no bulk disconnect option.
• Disconnecting one brand does not affect other brands' connections.
• Users can have a mix of connected and disconnected brands.

4.13 Sync Status After Reconnection

• After reconnection, the QuickBooks sync icon reappears next to transactions for that brand.
• Only transactions created after the reconnection date will attempt to sync.
• Transactions from the disconnection period remain without sync status/icon.

5. Field Details & Validations

Field Name

Field Type

Description

Validation Rules

Brand Name

Text (Display)

Name of the brand being disconnected

Read-only; dynamically populated in modal title and body

Cancel Button

Button

Dismisses the modal without action

Always enabled

Yes, Disconnect Button

Button

Confirms and executes disconnection

Requires click to proceed; styled in red

Connect Button

Button

Initiates reconnection flow

Enabled only for "Not Connected" brands

6. Success Message Handling

Action

Success Message

Display Location

Post-Action Behavior

Disconnect confirmed

"QuickBooks disconnected for [Brand Name]."

Toast notification (top-right)

Modal closes; row updates to "Not Connected"

Reconnection complete

"QuickBooks connected successfully for [Brand Name]."

Toast notification (top-right)

Row updates to "Connected" with new QB Company ID

Cancel disconnection

N/A (No message)

N/A

Modal closes; no changes made

7. Error Message Handling

Error Scenario

Error Message

Display Location

Trigger Condition

User Action Required

Disconnection failed

"Unable to disconnect QuickBooks. Please try again."

Toast notification

API or database error during disconnection

Retry by clicking Disconnect again

OAuth revocation failed

"Disconnected locally. QuickBooks may still show this app as connected."

Toast notification

QuickBooks API fails to revoke token

No action needed; local state updated

Network error during disconnect

"Network error. Please check your connection and try again."

Toast notification

No internet connectivity

Check network and retry

Session expired

"Your session has expired. Please log in again."

Modal dialog

User session timed out

Re-authenticate into Pixally

Permission denied

"You don't have permission to disconnect QuickBooks."

Toast notification

Non-admin user attempts to disconnect

Contact an Agency Owner or Admin

Subscription downgrade auto-disconnect

"Your plan no longer includes QuickBooks integration. All QuickBooks connections have been disconnected."

Banner notification

User downgrades subscription

Upgrade subscription to reconnect

8. Edge Cases

Edge Case

Scenario Description

Expected System Behavior

Disconnect during active sync

A transaction is being synced while user clicks Disconnect

Sync attempt completes (success or fail), then disconnection proceeds

Disconnect then immediate reconnect

User disconnects and immediately clicks Connect

Full reconnection flow starts; no shortcuts

Cancel then Disconnect again

User cancels modal, then clicks Disconnect again

Modal reappears with same warnings

Multiple admins, one disconnects

Admin A disconnects while Admin B is viewing the page

Admin B's page updates on refresh to show disconnected state

Disconnect non-existent connection

Attempting to disconnect an already disconnected brand

Button not visible; action not possible

Reconnect to same QB company

User disconnects and reconnects to the exact same QB company

New OAuth tokens issued; must reconfigure account mappings

Reconnect to different QB company

User reconnects to a different QB company

New company connected; old company's data remains in old QB account

Subscription downgrade with pending syncs

User downgrades while transactions are pending sync

Pending syncs fail; integration disconnected

Subscription upgrade after downgrade

User upgrades subscription plan

QB card becomes visible; all brands show "Not Connected"; manual reconnection required

Rapid Disconnect clicks

User clicks "Yes, Disconnect" multiple times quickly

System processes first click; subsequent clicks ignored

Browser back during modal

User clicks browser back while modal is open

Behavior depends on browser; modal may close without action

Long disconnection period

User disconnects for months then reconnects

Large data gap; only new transactions sync

Reconnect with different user account

Different Intuit user reconnects the same brand

New user's QB company connected; old connection overwritten

9. Acceptance Criteria

• AC1: The "Disconnect" button is visible only for brands with "Connected" status.
• AC2: Clicking "Disconnect" opens a confirmation modal with the brand name displayed.
• AC3: The modal displays two warning bullet points about losing sync and automatic updates.
• AC4: Clicking "Cancel" closes the modal without making any changes.
• AC5: Clicking "Yes, Disconnect" disconnects the brand and displays a success message.
• AC6: After disconnection, the brand shows "Not Connected" status with a "Connect" button.
• AC7: The QuickBooks Company ID column is cleared after disconnection.
• AC8: The expand chevron is disabled for disconnected brands.
• AC9: Previously synced transactions remain in QuickBooks (not deleted).
• AC10: Reconnection follows the standard connection flow from FRD 2.
• AC11: A data gap warning is displayed during reconnection explaining that past transactions won't sync.
• AC12: Users can reconnect to the same or a different QuickBooks account.
• AC13: Previous account mappings are not retained after reconnection.
• AC14: Subscription downgrade automatically disconnects all brands and hides the QB integration option.
• AC15: Subscription upgrade makes QB integration visible but requires manual reconnection.

10. Manual Test Cases

Link: Test Cases - Disconnect and Reconnect QuickBooks Integration with Pixally

11. Dependencies

Dependency Type

Dependency Name

Description

Impact if Unavailable

External Service

QuickBooks OAuth Revocation API

Revokes OAuth tokens on disconnection

Tokens may remain valid in QB; local state still updated

Internal Module

Subscription/Billing Module

Determines if plan includes QB integration

Cannot determine eligibility; may block disconnection

Internal Database

QuickBooks Connection Store

Stores and removes connection data

Cannot update connection status

Internal Database

Account Mapping Storage

Stores and removes account mappings

Mappings may persist incorrectly

Internal Module

Notification System

Displays toast messages and banners

Users may not receive feedback

12. References

• **Figma Designs:
  **
• **Known Limitations:
  **
  • Manual sync of historical transactions (data gap period) is not supported in Phase 1.
  • Retroactive syncing is documented as a future enhancement.

Deprecated

QuickBooks Integration

Functional Requirement Document

BA & Ideation: Dakshraj Jhala

Reviewed By: KG (Project Manager)

Updated Date: 06 October 2025
Status:

Version 1.0

Functional Requirements Document (FRD) - Quick Book Integration

1. Module Overview

• Module Name: Quick Book Integration
• Purpose: The QuickBooks Integration module syncs financial data one-way from Pixally CRM to QuickBooks Online. When integrated, it automatically transfers client invoices (income), refunds, contractor payments (expenses), and tax details from Pixally to QuickBooks—keeping financial records accurate without manual entry. This allows agency owners to manage finances within Pixally while ensuring accurate bookkeeping and tax compliance in QuickBooks.
• Business Goal: To simplify and automate bookkeeping for agency owners by eliminating manual data entry between Pixally and QuickBooks. The integration provides one-way synchronization of income, refunds, expenses, and tax details from Pixally to QuickBooks. By automating expense tracking, contractor payments, and tax calculations, Pixally helps agency owners maintain consistent, compliant, and transparent financial records with a unified accounting workflow.

2. User Roles & Permissions

• Link - Roles and permissions - draft

3. User Flow

4. Functional Logic

4.1 What is QuickBooks Integration?

• The QuickBooks Integration in Pixally enables a one-way synchronization of financial data from Pixally CRM to QuickBooks Online, ensuring that all income, expense, and tax transactions recorded within Pixally are accurately reflected in QuickBooks for bookkeeping and compliance. This integration eliminates manual data entry by transferring key financial information, including:
  • Client Invoices (Income): Created in Pixally and pushed to QuickBooks when the first invoice payment is received from the client.
  • Refunds: Records refunds issued to customers against the corresponding invoice in QuickBooks.
  • Contractor Payments (Expenses): Outgoing contractor payments are recorded as expense entries in QuickBooks under the selected expense category.
  • Tax Details: Applies the applicable tax on both income and expenses based on the invoices

4.2 Zero State – If No Integration

• When the QuickBooks integration is not connected, Pixally displays a zero state, indicating that no QuickBooks account has been linked. In this state, users can still access all Pixally financial features; however, no financial data will be synced or transferred to QuickBooks
• Integration Module (Tools → Integration → QuickBooks Online → Manage Integration → Brands Listing) and Finances Module → QuickBooks Screen → Brands Listing:
  • Each brand row displays:
    • Status: Not Connected
    • Action Button: Connect
    • QuickBooks Company ID: Blank (no data displayed)
• Finances → Billing → Transactions → Paid Sub-tab → QuickBooks Button (each row) and Finances → Contractor Invoices → Paid tab → QuickBooks Button (each row):
  • Each transaction row shows a QuickBooks button in the table
  • Clicking Connect QuickBooks from the Actions (kebab) menu under any transaction redirects the user to the Manage Integration screen under Finances Module → QuickBooks Screen → Brands Listing

4.3 Multiple Brand Integration

Pixally allows agency owners managing multiple brands to flexibly integrate QuickBooks—either by using a single shared QuickBooks account across all brands or by connecting separate accounts per brand

Each brand operates its own QuickBooks connection and maintains distinct mapping settings for Income, Refunds, Taxes, and Expenses, ensuring accurate synchronization and reporting across all configurations

When using a shared QuickBooks account, data from all brands will sync to that same QuickBooks company but under their respective account mappings, keeping brand-level transactions organized and distinguishable within QuickBooks

When using separate QuickBooks accounts, each brand’s financial data will sync only to its own corresponding QuickBooks company

4.4 Step-by-Step Connection Process

Entry Points

Tools → Integrations → QuickBooks Online → Manage Integration → Brands Listing → Connect button

Finances → QuickBooks → Brands Listing → Connect button

Finances → Billing → Transactions tab → Paid sub tab → QuickBooks Button (each row)

Finances → Contractor Invoices → Paid tab → QuickBooks Button (each row)

On click, the QuickBooks button in rows → opens Finances > QuickBooks > Brands Listing

Row Kebab Actions (In Billing and contractor invoices) → On click Connect QuickBooks button → opens Finances module > QuickBooks sub module > Brands Listing

Step 1 — Open Manage Integration (either from integration module > QuickBooks > manage integrations > Brands Listing OR finances module > QuickBooks submodule > Brands Listing)

Displays a table of all Brands of the agency with columns: Brand Name, QuickBooks Company ID, Integration Status, and Actions

Brands not linked show Integration status - Not Connected and a Connect button in the actions column of the brands listing (In QuickBooks, manage integration)

Step 2 — “Choose Brand”

Click Connect on the desired brand row

Pixally opens the Connect Your QuickBooks Account pop-up

Step 3 — “Start Authentication”

Click the Connect QuickBooks button in the pop-up

Opens the Intuit OAuth login screen

User signs in and authorizes

Step 4 — “Define the Accounts” (per brand)

Pixally fetches the brand user’s QuickBooks Chart of Accounts and shows the mapping modal:

Dropdown Fields:

“Select the default QuickBooks account for incoming deposits.”

Dropdown values: QuickBooks all account names with Account Type = Income

“Select the QuickBooks account to associate with refunds.”

Dropdown: QuickBooks all account names with Account Type = Refunds (or Contra Income)

“Select the QuickBooks tax rate to connect with your Pixally account.”

Dropdown: QuickBooks all tax rate names with Account Type = Tax Rate

“Select the default QuickBooks account for expenses.”

Dropdown: QuickBooks all account names with Account Type = Expense

Notes

All fields are optional

Whatever the user maps is what will sync one-way (Pixally → QuickBooks) for this brand

Example: If only the “Select the default QuickBooks account for incoming deposits” dropdown value is selected, only income will sync to QuickBooks for this brand

Controls

Skip for Now → proceed without mappings (no data sync occurs until a field is mapped later)

Finish Setup → save mappings

Step 5 — Save & Complete

On Finish Setup, Pixally stores the mappings for the brand and activates sync for the selected types.

Return to the Manage Integration list

Step 6 — Post-Connection Status

• • Impact on Brand Listing in:
    • Finances > QuickBooks > Brands Listing &
    • Integrations > QuickBooks > Manage Integrations > Listing

After a successful QuickBooks connection for a brand, the corresponding brand row updates to:

Integration Status: Connected

QuickBooks Company ID: shows the connected QuickBooks accounts company name (e.g., Emma Taylor LLC)

Actions: Disconnect

The Manage Integrations button will be displayed in Integrations > Brands Listing (only for brands that have been successfully integrated with QuickBooks)

When clicked, it will redirect the user to Finances > Brands Listing

The “Define Account Payments Type” section will automatically open for the selected brand

It will display the pre-set value (if it was configured during the “Define the Account” step in the QuickBooks integration process)

A dropdown button will be displayed in Finances > QuickBooks > Brands Listing for the brands that are connected to QuickBooks.

When clicked, it will open the “Define Account Payments Type” dropdown

The dropdown will display the pre-set value (if it was configured during the “Define the Account” step in the QuickBooks integration process)

4.5 After Successful Connection

4.5.1 Income (Client Payments)

When a client makes a successful payment in Pixally (paid status), Pixally automatically syncs the transaction to QuickBooks. This process creates or updates the corresponding Customer, Invoice, and Payment records in QuickBooks based on the data mapped during the integration setup

A Customer is created in QuickBooks only when the first successful payment is received from a client. All subsequent payments from the same client are automatically recorded under the same customer. If the customer already exists in QuickBooks, Pixally identifies and links the record using the name or email for consistency. The resulting income transaction is logged in QuickBooks under the mapped Income Account selected from the Chart of Accounts dropdown defined during setup, or if updated later

Trigger

Payment status = Paid in Pixally

Brand linked to QuickBooks

“Income” account selected in the Define Account dropdown from the Chart of Accounts

Actions Performed

Customer Record created in QuickBooks

Field

Source (from Pixally)

Customer Name

Client name from Pixally

Payment Date

Date of payment

Payment Amount

Total paid amount

Transaction Fee

Stripe/Pixally fee (recorded separately under Expenses)

Brand / Project Name

Added in Memo or Description

Email

Client email (if available)

Invoice Creation

Pixally automatically creates an Invoice linked to the customer in QuickBooks.

Each new payment updates the existing invoice or closes it if fully paid

Field

Source (from Pixally)

Invoice ID

Pixally Invoice ID

Customer

Linked the customer in QuickBooks

Invoice Date

Payment date

Amount

Payment amount (before tax/fees)

Tax

Applied from the mapped tax rate

Project Reference

Added in Memo

Status

Paid

Payment Record

The transaction is logged in QuickBooks under the selected Income Account from the Chart of Accounts.

• • Chart of Accounts Entry - The income entry appears under the mapped Income Account in QuickBooks, linked to its corresponding Customer and Invoice

Field

Source (from Pixally)

Payment Date

Date of transaction

Amount

Amount received

Payment Method

Stripe / ACH / Card

Brand / Project

Added in Memo

Chart Mapping

Selected Income Account from the dropdown

4.5.2 Refunds (Client Refunds)

When a refund is processed in Pixally for a previously paid invoice, Pixally automatically syncs the refund details to QuickBooks. The refund transaction is linked to the same Customer and Invoice that were originally synced during the income process, ensuring proper reconciliation in QuickBooks.

A Refund Receipt or Credit Memo is created in QuickBooks under the Refund Account selected from the Chart of Accounts dropdown during integration setup.

This allows QuickBooks to correctly reduce the income balance and maintain transparent financial tracking.

Trigger

Refund marked as Refunded in Pixally

Associated payment or invoice already synced with QuickBooks

“Refund” account selected in the Define Account dropdown from the Chart of Accounts

Actions Performed (Customer Reference)

Refunds are always attached to the same Customer record that was created or linked in QuickBooks during income synchronization

Field

Source (from Pixally)

Customer Name

Client name from Pixally

Refund Date

Date of refund processed

Refund Amount

Total amount refunded to client

Linked Invoice ID

Original Pixally Invoice ID

Brand / Project Name

Added in Memo or Description

Refund Transaction

Pixally creates a Refund Receipt or Credit Memo in QuickBooks under the mapped Refund Account

Field

Source (from Pixally)

Refund ID

Pixally Refund Transaction ID

Customer

Linked the customer in QuickBooks

Invoice Reference

Original paid invoice

Refund Date

Refund date in Pixally

Refund Amount

Total refund amount

Payment Method

Stripe payment method

Memo

Brand and Project Name reference

Chart Mapping

Selected Refund Account from the dropdown in the Define Account Type

Chart of Accounts Entry

The refund transaction is recorded in the mapped Refund Account in QuickBooks

4.5.3 Expenses (Contractor Payouts)

When a contractor payment is marked as Paid in Pixally (from Financial Management → Contractor Invoices → Paid tab), Pixally automatically syncs the payout details to QuickBooks. This process includes creating or updating a corresponding Vendor profile and recording the payout as an Expense transaction under the mapped Expense Account selected from the Chart of Accounts dropdown during integration setup

Each subsequent payment made to the same contractor is automatically recorded under the same vendor profile, maintaining consistency across transactions and ensuring all project-related expenses are traceable in QuickBooks

Trigger

Contractor payment status = Paid in Pixally

Brand linked to QuickBooks

“Expense” account selected in the Define Account dropdown from the Chart of Accounts

Actions Performed (Vendor Creation & Management)

A Vendor record is created in QuickBooks upon the first successful contractor payment from Pixally. All future contractor payouts are automatically linked to that vendor record

Field

Source (from Pixally)

Vendor Name

Contractor name from Pixally

Payment Date

Payout date

Payment Amount

Total payout amount

Brand / Project Name

Added in Memo or Description

Email

Contractor email (if available)

Expense Transaction

Pixally creates an Expense entry in QuickBooks under the Expense Account defined in the Chart of Accounts mapping. Each transaction links to the corresponding vendor and project reference for complete traceability

Field

Source (from Pixally)

Expense ID

Pixally Transaction ID

Vendor

Linked vendor in QuickBooks

Payment Date

Date of contractor payout

Amount

Total amount paid

Expense Category

Selected Expense Account from the dropdown

Brand, Project Reference

Added in Memo

Chart Mapping

Selected Expense Account from the dropdown

Chart of Accounts Entry

The expense entry appears under the mapped Expense Account in QuickBooks, linked to the respective vendor and brand. This ensures that each payout is properly categorized and reflected in QuickBooks reports, such as Profit and Loss and Expense by Vendor.

4.5.4 Taxes (Collected & Applied)

Pixally automatically syncs applicable tax details to QuickBooks whenever a client payment (income) or contractor payment (expense) is recorded and the brand is connected to QuickBooks.

The tax information is applied according to the Tax Rate Account selected from the Chart of Accounts dropdown during integration setup.

QuickBooks automatically determines and records the correct tax rate on each synced transaction using the mapped account, ensuring all tax liabilities and credits are accurately reflected for compliance and reporting.

Trigger

A payment (income or expense) is marked as “Paid” in Pixally

Brand is connected to QuickBooks

“Tax Rate” mapping is selected in the “Define Account” dropdown from the Chart of Accounts

Actions Performed (Tax Calculation & Sync )

For every eligible transaction (client payment or contractor expense), Pixally pushes tax details to QuickBooks, allowing it to calculate the appropriate tax automatically.

Field

Source (from Pixally)

Tax Name

Selected from the QuickBooks Tax Rate list

Tax Type

Sales Tax / Service Tax (as configured in QuickBooks)

Applied On

Income and Expense transactions synced from Pixally

Tax Amount

Derived from Pixally invoice or payout

Brand / Project

Added in Memo or Description

Tax Entry in QuickBooks

Tax information appears within the synced Invoice, Expense, or Sales Receipt records, applied using the mapped tax rate.

Each tax entry is associated with the corresponding Tax Agency in QuickBooks (e.g., state, local, or city tax), ensuring proper tracking of payable or receivable tax amounts

Chart of Accounts Entry

All collected taxes and applicable expense taxes are recorded under the mapped Tax Rate Account in QuickBooks, contributing to accurate Tax Liability and Sales Tax Summary reports

4.5.5 Transaction Fees (Pixally & Stripe)

Every time a client payment is processed through Pixally’s connected payment gateway (e.g., Stripe), the associated transaction fee is automatically synced to QuickBooks as an Expense entry.

This ensures that the agency’s net income in QuickBooks accurately reflects payment-processing costs

Transaction fees are treated as operational expenses and are recorded under the Expense Account selected during the “Define Account” mapping step in the integration setup.

Trigger

A client payment is marked as Paid in Pixally

Brand is connected to QuickBooks

The payment is processed via Stripe or Pixally’s integrated payment system

“Expense” account mapping is defined during setup

Actions Performed (Fee Recording in QuickBooks)

When a payment is received, Pixally calculates the transaction fee (e.g., Stripe’s service fee) and pushes a corresponding expense record to QuickBooks. This entry links to the same customer and payment for accurate reconciliation

Field

Source (from Pixally)

Expense Type

Transaction / Processing Fee

Payment Date

Same as the payment transaction date

Amount

Deducted fee amount

Linked Customer

Same client associated with the payment

Brand / Project Name

Appears in Memo or Description

Chart Mapping

Selected “Expense Account” from the dropdown

Chart of Accounts Entry

Each transaction fee appears in QuickBooks under the mapped Expense Account, typically within Operating Expenses or Payment Processing Fees. This provides visibility into total fees incurred for processing payments, allowing users to reconcile gross vs. net income per transaction.

4.6 What if the User Connects to QuickBooks After Some Transactions?

If the user connects their QuickBooks account after transactions have already occurred in Pixally, the system allows those previously completed transactions to be manually synced once the integration is active

Behavior After Connection

• Once QuickBooks is successfully connected for a brand:
  • All future transactions (client payments, client refunds, contractor payouts, and taxes) will automatically sync to QuickBooks as per the mapping settings
  • All previous transactions (recorded before the integration) will remain unsynced by default, but can be manually synced by the user

Manual Sync Options for Past Transactions

For transactions completed before QuickBooks integration, users can manually sync them after successfully connecting a QuickBooks account for the respective brand

Available Options

Finances → Billing → Transactions → Paid Tab

Each transaction displays a QuickBooks icon button beside it

When the brand is connected to QuickBooks, the button shows the green QuickBooks logo with a tick mark

Clicking the icon opens the Sync with QuickBooks option, allowing the user to manually push that transaction to QuickBooks

Actions (Kebab Menu)

The kebab menu includes either:

“Sync with QuickBooks” — if the brand is already connected (the QuickBooks icon shows green with a tick)

“Connect QuickBooks” — if not connected (icon appears grey with a red cross)

Clicking Connect QuickBooks redirects the user to Integration → QuickBooks → Manage Integration to complete setup

Finances → Contractor Invoices → Paid Tab

Each contractor payout displays a QuickBooks icon button beside it

If connected, clicking the icon triggers the Sync with QuickBooks process, recording the payout as an expense and linking it to the respective vendor in QuickBooks

Once synced successfully, the icon updates to the green tick-mark indicating completion

Sync Logic for Previous Transactions

Only transactions belonging to brands currently connected to QuickBooks will display the Sync with QuickBooks option

Clicking Sync with QuickBooks triggers the one-way data push logic used for new transactions — creating or updating Customers, Vendors, Invoices, or Expenses according to the mapped accounts. Refer - Click Here

After a transaction has been successfully synced, the QuickBooks button updates to a green icon with a tick, and the Sync with QuickBooks action becomes disabled to prevent duplicates

Transactions under brands that are not yet connected will continue showing the grey QuickBooks icon with a red cross and the Connect QuickBooks option, which redirects to Finance→ QuickBooks → Brands Listing

4.7 Disconnect QuickBooks and Reconnect Again

• Pixally allows users to disconnect and reconnect their QuickBooks integration at any time.
• When a user disconnects from QuickBooks, all future synchronization between Pixally and QuickBooks stops immediately. However, any financial data already synced before disconnection remains intact within QuickBooks.
• Reconnecting establishes a new link, allowing synchronization to resume based on fresh account mappings.

Disconnect Flow

1. Entry Points
   • Tools → Integrations → QuickBooks Online → Manage Integration → Brands Listing → Disconnect Button
   • Finances → QuickBooks → Brands Listing → Disconnect Button
2. Confirmation Pop-Up

• When the user clicks Disconnect, Pixally displays a confirmation pop-up as follows:
  • Title: Disconnect QuickBooks for [Brand Name]
  • Message: “Are you sure you want to disconnect this QuickBooks account from [Brand Name]? You can reconnect anytime to restore syncing.”
  • Details:
    • You’ll lose the ability to sync invoices for this brand.
    • Automatic updates between QuickBooks and your workspace will stop.
      Buttons:
    • Cancel – closes the popup without any change.
    • Yes, Disconnect – confirms disconnection and executes the action.
• System Behavior After Disconnection
  • Synchronization between Pixally and QuickBooks stops immediately.
  • Any data previously synced (invoices, refunds, expenses, and payments) remains in QuickBooks.
  • No new financial data created in Pixally after disconnection will sync to QuickBooks.
  • The Integration Status updates to Not Connected.
  • The QuickBooks Company ID column becomes blank
  • The define account type dropdown Preferences section will not be displayed
  • The Actions column in Billing > Transactions > Paid & Contractor Invoices > Paid updates to show a Connect QuickBooks instead of Sync with QuickBooks button again, and the QuickBooks icon changes to grey with a red cross to visually indicate disconnection

4.8 Chart of Accounts Synchronization Logic

• Pixally dynamically syncs the Chart of Accounts from QuickBooks to ensure that any newly created or updated accounts in QuickBooks are always reflected in Pixally’s account mapping dropdowns. This ensures all financial mappings remain accurate, current, and aligned between both systems.

Functional Logic

1. **Real-Time Chart of Accounts Update
   **

   • When a user adds a new account or updates the name of an existing account in QuickBooks (Income, Refunds, Taxes, or Expenses), Pixally automatically fetches these updates and reflects them in the relevant dropdown lists.

   • This ensures that users always interact with the most current Chart of Accounts data during account mapping.

2. **Dropdown Synchronization
   **

   • Updated Chart of Accounts values are displayed in:
     • **Finances → QuickBooks → Brands Listing (expanded “Define Accounts” section)
       **
     • **Tools → Integrations → QuickBooks Online → Manage Integration → Expanded “Define Accounts” section (Opens in Finances > QuickBooks)
       **
   • Each dropdown (Income, Refunds, Tax, Expenses) dynamically fetches and lists accounts according to their Account Type in QuickBooks.

3. **Manual Refresh
   **

   • A Refresh Accounts icon beside each dropdown allows users to instantly pull the latest Chart of Accounts from QuickBooks.

   • Clicking refresh immediately updates all dropdown options to reflect any additions or modifications made in QuickBooks.

4. **Change & Mapping Behavior
   **

   • Newly Added Accounts: Appear in the dropdown under the appropriate Account Type.

   • Renamed Accounts: Instantly update their labels across Pixally dropdowns.

   • Deleted Accounts: Are removed from the dropdown. If a mapped account is deleted, Pixally flags it for re-selection before future sync.

   • **Mapping Update Logic:
     **When a user changes a dropdown selection (e.g., selects a new Income or Expense account), all future transactions will automatically sync to the newly selected QuickBooks account.
     Previously synced transactions remain in their original mapped accounts within QuickBooks.

5. **Sync Direction
   **

   • The Chart of Accounts synchronization is strictly one-way (QuickBooks → Pixally). Pixally only reads and updates account data from QuickBooks; it does not modify, create, or delete any accounts within QuickBooks

4.9 Change the QuickBooks Account for Any Brand

• The user can disconnect an existing QuickBooks account for any brand at any time.

• After disconnection, the brand’s status changes to Not Connected, and the Connect button becomes available again.

• The user can reconnect to the same or a different QuickBooks company by following the standard connection flow.

• Once reconnected, Pixally automatically fetches the new company’s Chart of Accounts for mapping.

• All future transactions for that brand will now sync to the newly connected QuickBooks account.

• Data already synced to the previous QuickBooks account will remain there and will not be transferred.

5. Success Message Handling

Validation Scenario

Success Message

QuickBooks account connected successfully

“QuickBooks account has been connected successfully.”

QuickBooks account disconnected successfully

“QuickBooks account has been disconnected successfully.”

6. Error Message Handling

Field

Validation Scenario

Error Message

QuickBooks Connection

OAuth authorization failed

"Failed to connect to QuickBooks. Please try again."

General

Calendly service unavailable

"Something went wrong."

8. Edge Cases

Scenario

Expected Behavior

User connects the same QuickBooks account for multiple brands

All brand data syncs to the same QuickBooks company under their respective mapped accounts. Brand-wise segregation remains based on chart mapping selections.

User connects a new QuickBooks account after disconnection

Previously synced data remains in the old QuickBooks account. Future transactions sync only to the newly connected account.

QuickBooks connection expires or access is revoked

Syncing stops automatically. User is notified with an alert and must reconnect to resume synchronization.

User adds or renames a Chart of Accounts in QuickBooks

Pixally automatically refreshes the dropdown list in the Define Account and Manage Integration screens to reflect the updated Chart of Accounts.

User changes a mapped account after sync

New transactions are synced to the newly selected account. Old synced records remain unchanged in QuickBooks.

User issues a refund for a client before the QuickBooks connection

Once the brand connects to QuickBooks, the refund appears with a “Sync with QuickBooks” button for manual sync.

Duplicate client names (same name, different email)

Pixally matches based on both name and email. If both match, it links to the existing QuickBooks customer; otherwise, a new customer record is created.

User manually marks a payment as Paid without an actual transaction

Transaction syncs to QuickBooks as a $0 payment, triggering a warning prompt to confirm before syncing.

Contractor payout created before connection

Appears with the “Sync with QuickBooks” option for manual syncing once connected.

User disconnects during an active sync

The current sync completes. All future transactions stop syncing until reconnected.

User edits the project/brand name after integration

The project/brand name in QuickBooks remains unchanged until the next new transaction sync.

Multiple users (admins) attempt to connect to QuickBooks simultaneously

Only the latest connection is retained. Pixally prevents concurrent setup and displays a validation message.

9. Test Cases

• Link:

10. Acceptance Criteria

11. Dependencies

Module / System

Dependency Type

Impact if Unavailable

QuickBooks Online API (Intuit API)

External Service

The integration cannot establish a connection, fetch the Chart of Accounts, or sync any financial data.

Pixally Financial Management Module

Internal Dependency

Client payments, refunds, and expense data will not be available for synchronization.

Pixally Contractor Module

Internal Dependency

Contractor payout data (expenses) cannot be created or synced to QuickBooks.

User Authentication System (OAuth)

Internal / External Dependency

Users cannot authenticate or authorize the QuickBooks connection.

Project & Brand Management Modules

Data Dependency

QuickBooks mappings and transactions cannot be associated with specific brands or projects.

Stripe Integration

Data Source Dependency

Payment and transaction fee details required for syncing income and expenses to QuickBooks will be unavailable.

Pixally Tax Management Module

Data Dependency

Tax rate mappings and calculations cannot be synced or validated in QuickBooks.

**

12. References**

• Figma Link: Click Here