Payment Status: Unpaid for a long time #819
Description
Context and Overview
Meteroid currently uses standard payment statuses to track the lifecycle of an invoice (Unpaid, Paid, Partially Paid, Errored). While the 'Unpaid' status covers all invoices that have not yet been paid, Account Managers require a clear, automated flag for invoices that have entered a severe state of delinquency, often requiring a different set of collection actions.
The goal of this V1 feature is to introduce a new payment status, "Unpaid for a long time", and the configuration logic to automatically transition invoices to this status.
1. Scope
This V1 feature covers:
- Defining and implementing the new payment status.
- Adding a configurable field in Invoice Settings to define the delinquency threshold.
- Implementing the automated logic to move invoices from 'Unpaid' to 'Unpaid for a long time' based on the configured threshold.
2. Implementation Details
2.1. New Payment Status Definition
- Status Name: Unpaid for a long time
- Definition: This status applies to invoices that have remained in the 'Unpaid' status for a period exceeding the configured delinquency threshold after their original due date. This status signals a severe delinquency level.
- Transition Pre-condition: An invoice can only transition to this status directly from the 'Unpaid' status.
2.2. Invoice Settings Configuration
Account Managers need to define the acceptable window before an invoice is flagged as severely delinquent.
- Placement: Settings > Invoices
- New Field: A new input field must be added, labeled: "Unpaid Delinquency Threshold (Days)".
- Description: This field defines the number of days after the invoice's original Due Date that must pass before the status transitions to 'Unpaid for a long time'.
- Default Value: The default value for this field must be 0 (ie. move to Unpaid for a long time status if the invoice is not paid at the due date).
- Input Type: The field must accept an integer value (number of days).
2.3. Automated Status Transition Logic
A scheduled background job must be implemented to manage the automatic status update.
- Transition Rule: For every invoice currently in the 'Unpaid' status, the system must check the following condition:
Current Date > Invoice Due Date + Unpaid Delinquency Threshold
- Action: If the condition is met, the invoice status must be immediately updated from 'Unpaid' to 'Unpaid for a long time'.
- Exclusion: Invoices currently in 'Partially Paid', 'Paid', or 'Errored' status must be explicitly excluded from this transition logic.