Workflow Playbook

Sales Workflow and Payments

Detailed flow for sales, payment collection, stock deduction, and customer ledger effects.

Audience: Sales operators, cashiers, and receivables users.

Collections and Responsibilities

Sales

sales

Invoice and fulfillment document that posts stock-out and customer debt.

Sale Payments

salePayments

Collection records that update amountPaid/paymentStatus on sales.

Customer Ledger

customerBalance

Receivable ledger for invoice, payment, and reversal events.

Step 1
Step 1: Create sale lines
Select customer, choose product variant, set quantity and selling price.
Step 2
Step 2: Save sale first
Save generates saleNumber and creates persistent sale record required for payment linkage.
Step 3
Step 3: Stock and invoice effects
Sale save deducts variant stock and posts customer invoice ledger events.
Step 4
Step 4: Add payment entries
Create salePayments with amount, method, and date to update amountPaid and paymentStatus.
Step 5
Step 5: Keep deletions controlled
Deleting payment recalculates sale status and posts payment_reversal to customer ledger.

Field	Requirement	Behavior
Sale Customer sales.customer	Required	Mandatory customer on sale header.
Sale Item Quantity sales.saleItems[].quantity	Required	Required and validated against available stock rules.
Sale Selling Price sales.saleItems[].price	Required	Required selling price with validation checks.
Sale Number sales.saleNumber	Auto / System	Auto-generated after first save.
Sale Totals sales.subtotal, sales.taxAmount, sales.total	Auto / System	Server-side tax and total recalculation is source of truth.
Sale Reference salePayments.sale	Required	Required sale relationship.
Sale Payment Core Fields salePayments.amount, method, date	Required	Mandatory fields for valid payment posting.
Payment Number salePayments.paymentNumber	Auto / System	Generated automatically as PAY-XXXX.
Delivery Fields delivery fields (status/date/address/notes)	Optional	Operational delivery tracking, independent from stock deduction timing.

If this happens

Payment is attempted before saving sale

Operationally blocked because no persisted sale context exists yet.

Timing: User workflow order: save sale first, then use Payments tab.

If this happens

Sale line quantities are edited

Stock adjusts by delta between previous and current lines, clamped at zero minimum.

Timing: afterChange on sales update.

If this happens

Payment is created or deleted

Sale amountPaid/paymentStatus and customer ledger are recalculated and synchronized.

Timing: afterChange / afterDelete in salePayments hooks.