Sale and Sale Payment Workflow

Related Collections

Execution Steps

1. Step 1

   Step 1: Create sale (General tab)

   Choose customer, add sale items, and confirm variant, quantity, and selling price for each line.

2. Step 2

   Step 2: Save sale first

   Click Save to create the sale document. The system auto-generates saleNumber in SALE-XXXX format. Saving is required before payment operations become available.

3. Step 3

   Step 3: Stock is updated immediately after save

   Create: each sold variant stock is reduced by quantity. Update: stock uses delta logic between old and new line items. Result is clamped to zero to avoid negative stock.

4. Step 4

   Step 4: Customer balance ledger is posted

   On sale create, invoice event is posted in customerBalance and customer.currentBalance increases by sale total. On sale total update, invoice_update posts only the difference.

5. Step 5

   Step 5: Open Payments tab (after save)

   After saving the sale, open Payments tab to create linked payment records. Before saving, payment creation is blocked because no persisted sale exists yet.

6. Step 6

   Step 6: Add payment

   Create payment with method, amount, and date. System recalculates sale.amountPaid and sale.paymentStatus (unpaid/partial/paid).

7. Step 7

   Step 7: Payment deletion behavior

   Deleting payment recalculates amountPaid/status and posts payment_reversal in customer balance ledger (adds debt back).

8. Step 8

   Step 8: Delivery (optional)

   Set delivery status, date, address, and notes as needed. Delivery fields do not gate payment flow and do not control stock deduction timing.

Important Callout

• You cannot add payment before sale is saved.
• If Payments tab looks empty, save the sale first then reopen Payments.

Critical Fields and Meaning

• Customer (required).
• Sale items: variant, quantity, selling price.
• Total is auto-calculated.
• Payment Status and Amount Paid are auto-calculated.
• Payment method and payment date are required when creating payment.
• saleNumber is auto-generated after save.

What Updates Automatically

• Stock is updated immediately after save: Create reduces each sold variant by quantity. Update uses delta logic between old and new line items. Result is clamped to zero to avoid negative stock.
• Customer balance increases by sale invoice and decreases by payments.
• Payment status switches between unpaid/partial/paid based on payments.
• Deleting a payment recalculates amountPaid and may change payment status back.

Detailed Payment Rules

• unpaid: amountPaid = 0
• partial: amountPaid > 0 and amountPaid < sale total
• paid: amountPaid >= sale total
• Payment create posts a customer payment ledger entry (reduces debt).
• Payment delete posts a reversal entry (adds debt back).

Detailed Sale Side Effects

• On create, stock is deducted from each selected variant quantity.
• On update, stock uses delta calculation between old and new quantities.
• On sale create, invoice event increases customer balance.
• On sale total change, invoice_update adjustment is posted by difference only.

Troubleshooting

• Problem: “I cannot add payment.” Fix: Save sale first, then open Payments tab.
• Problem: Payment status did not change. Fix: Ensure payment was saved and linked to correct sale.

Screenshots To Include

• Create sale (General tab).
• Save sale button.
• Open Payments tab.
• Create payment form.