Manual Invoice Payment Status Updates

[DDU190]

Context and Overview

Currently, invoice payment statuses (Paid, Partially Paid, Errored) are set automatically by the payment processing and reconciliation engine. However, many enterprise customers remit payments via non-integrated methods, such as bank transfers (ACH/Wire) or manual checks. In these cases, the Account Manager or Finance team needs the ability to update the status manually to reflect the payment reality for accurate accounting and customer visibility.

The goal of this V1 feature is to grant Account Managers the capability to manually override and set the payment status for most common scenarios, while keeping critical automated statuses protected and ensuring manual changes persist.

1. Scope

1.1. In-Scope Statuses (Manually Editable)

Account Managers must be able to manually transition an invoice to or from these statuses:

• Paid
• Unpaid
• Partially Paid

1.2. Out-of-Scope Statuses (Automated Only)

The following status must remain controlled exclusively by the system's billing and payment processing logic and cannot be set or altered manually by an Account Manager:

• Errored (This status is reserved for tracking system-triggered payment failures.)

2. Implementation Details

2.1. User Interaction (UI)

• Placement & Interaction: On the Invoice Detail Page, the displayed payment status must be a clickable element. Clicking the status must reveal a dropdown selection list containing the manually editable statuses defined in Section 1.1 (Paid, Unpaid, Partially Paid).
• Action: When an Account Manager selects a new status from the dropdown, the system must initiate the status change process.
• Confirmation: A confirmation must appear when an Account Manager attempts to change a status, requiring confirmation before the change is applied to the database.

2.2. Manual Status Update Logic

The system must allow flexible movement between the in-scope statuses:

• From Unpaid: An invoice can be manually moved to Paid (for full payment outside the system) or Partially Paid (if a partial manual payment is logged).
• From Partially Paid: An invoice can be manually moved to Paid (if the remainder is paid) or reverted to Unpaid (e.g., if the partial payment was disputed or returned).
• From Paid: An invoice can be manually reverted to Unpaid or Partially Paid (e.g., if a payment was later reversed or recalled by the bank).

2.3. System Restrictions and Persistence

• Manual Override Lock: Once an invoice status has been manually updated by an Account Manager (to Paid, Unpaid, or Partially Paid), a permanent flag must be set on the invoice record. This flag must ensure the invoice is excluded from all future automated status change jobs.
• Errored Status Protection: The system must prevent Account Managers from selecting the Errored status via the manual update interface.
• Status Exit Constraint: The system must prevent Account Managers from manually moving an invoice out of the Errored status. The transition away from 'Errored' (e.g., back to 'Unpaid' or 'Paid') must remain strictly automated by the retry logic or payment gateway updates.