Workflow Playbook
Purchase Payments and Payables
How supplier payments are validated and how they update purchase payment status and supplier balances.
Audience: Accounts payable team and financial controllers.
Collections and Responsibilities
Supplier Payments
supplierPayments
Payment document for settlements to suppliers, linked or unlinked to a purchase.
Purchases
purchases
Receives rolled-up amountPaid/paymentStatus/paymentPercentage values.
Supplier Ledger
supplierBalance
Stores payment and payment_reversal movements for audit and running balance.
Workflow Timeline
Step 1
Step 1: Create supplier payment
Enter supplier, amount, date, and optionally attach the purchase document.
Step 2
Step 2: Validate business constraints
If purchase is linked, it cannot be draft and supplier must match purchase supplier.
Step 3
Step 3: Post payment movement
Payment ledger entry is created and supplier current balance is reduced.
Step 4
Step 4: Recalculate purchase payment status
System sums all payments for purchase and computes unpaid/partial/paid/overpaid.
Step 5
Step 5: Handle deletions with reversal
Deleting payment recalculates purchase totals and posts payment_reversal.
Field Guide (Required vs Optional)
| Field | Requirement | Behavior |
|---|---|---|
Supplier supplier | Required | Supplier receiving the payment. |
Amount amount | Required | Must be numeric and > 0. |
Date date | Required | Required transaction date. |
Purchase Reference purchase | Optional | Optional relation. If set, strict validation rules apply. |
Payment Method & Supporting Info method, stage, invoiceReference, invoice | Optional | Operational metadata and evidence fields. |
Decision Scenarios
If this happens
Payment linked to draft purchase
Save is blocked by validation.
Timing: beforeValidate on supplierPayments.
If this happens
Payment supplier does not match purchase supplier
Save is rejected to prevent cross-supplier posting errors.
Timing: beforeValidate on supplierPayments.
If this happens
Total paid exceeds purchase total
paymentStatus becomes overpaid and paymentPercentage goes above 100%.
Timing: After payment status recalculation.
Automatic Side Effects
- Purchase payment metrics are recalculated from full DB history, not incremental assumptions.
- Ledger posting/reversal keeps supplier current balance synchronized.
Operational Controls
- Require reference and attachment policy for high-value payments.
- Investigate overpaid statuses weekly and resolve by credit allocation process.
- Do not manually edit supplier.currentBalance outside ledger workflows.