Sales Module — User Guide
All guides

Sales Module — User Guide

Orders and customer follow-up.

ProductVertex ERP
ModuleSales (`modules/sales`)
AudienceSales clerks, AR staff, and managers who confirm orders and post invoices
FormatHTML + Mermaid diagrams

1. Overview

The Sales module supports a lean commercial flow: sales order → sales invoice → Finance accounts receivable. Customers and cash collections are managed in Finance; Sales focuses on orders and invoices.

Area Capability
Orders Draft, confirm, convert to invoice, cancel
Invoices Create standalone or from order; post/unpost to Finance
Customers Finance partner sub-ledgers (Customer type)
Collections Finance receipt / payment vouchers with allocations
flowchart LR Cust[Finance customer] --> Ord[Sales order] Ord --> Inv[Sales invoice] Inv -->|Post| Fin[Finance JE and AR] Fin --> Coll[Receipt voucher] Coll -->|Allocate| Inv

Not in this module today: stock delivery, quotations, price lists, sales returns as Sales documents, or automatic Inventory movements. Deliveries/quotations mentioned in some localization keys are not implemented as Sales screens.

2. Getting started

2.1 Prerequisites

flowchart TD A[Finance chart of accounts] --> B[Fiscal year and periods] B --> C[Currencies and rates] C --> D[Customer partner sub-ledgers] D --> E[Sales permissions on roles] E --> F[Create orders and invoices]
  1. Finance chart of accounts ready (typical defaults used in posting include AR, sales revenue, and output VAT accounts).
  2. Open fiscal year/periods.
  3. Currencies configured (UI often defaults to base currency and rate 1).
  4. Customers created under Finance subsidiary customers.
  5. Users granted Sales order/invoice permissions (and Finance journal post for posting).

2.2 Main navigation

Menu Path Behavior
Overview /sales/overview Dashboard-style overview (prototype metrics)
Customers /sales/customers Redirects to Finance subsidiary customers
Sales invoices /sales/invoices Live invoice list and actions
Collections /sales/collections Redirects to Finance payment vouchers
Sales orders /sales/orders Live order list and actions

3. Customers

Customers are not owned by Sales. They are Finance partner sub-ledgers with partner type Customer.

Field (Finance) Use in Sales
Code / name Shown in order and invoice partner pickers
Contact info Master data in Finance
GL account Optional AR control account override when posting
Active Only active partners should be used

How to maintain: open Customers from the Sales menu (goes to Finance) or go directly to Finance → Subsidiary ledger — customers.

When creating an order or invoice, select the customer from the partner list filtered to Customer type.

4. Sales orders

4.1 Header fields

Field Meaning
Order number Unique per tenant
Partner Customer sub-ledger
Order date Document date
Fiscal period Accounting period
Currency / exchange rate Document currency
Status Lifecycle state
Subtotal / tax / total Amounts
Notes Free text
Sales invoice id Set after conversion

4.2 Lines

Line number, description, quantity, unit price, line total (quantity × price), optional revenue account.

4.3 Statuses

Status Meaning
Draft Editable / deletable
Confirmed Ready to convert to invoice
Invoiced Converted; locked for cancel
Cancelled Abandoned

4.4 Actions

Action From Rules
Create — Starts as Draft
Update / Delete Draft only Not after confirm
Confirm Draft Requires lines and total greater than zero
Convert to invoice Confirmed Creates Draft invoice; order becomes Invoiced
Cancel Draft or Confirmed Blocked if Invoiced
flowchart TD A[Create Draft order] --> B[Confirm] B --> C[Confirmed] C --> D[Convert to invoice] D --> E[Order Invoiced] D --> F[Draft Sales Invoice] A --> G[Cancel] C --> G

Convert defaults: invoice number often SI-{OrderNumber} if not supplied; invoice date from order date; due date typically order date + 30 days; copies partner, period, currency, rate, notes, lines, and tax.

5. Sales invoices

5.1 Header fields

Field Meaning
Invoice number Unique
Partner Customer
Sales order Optional link
Invoice date / due date Billing and payment due
Fiscal period / currency / rate Accounting context
Status Lifecycle
Subtotal / tax / total Amounts
Paid amount / open amount Open = Total − Paid
Journal entry Set after post
Notes Free text

5.2 Lines

Same shape as order lines. Optional revenue account per line overrides the default sales revenue account when posting.

5.3 Statuses

Status Meaning
Draft Editable / deletable / cancellable
Posted Posted to Finance; open AR
Partially paid Some receipts allocated
Paid Fully allocated
Cancelled Abandoned (from Draft)

5.4 Create paths

  1. From order — Convert confirmed order.
  2. Standalone — Create invoice directly (optional order link).

5.5 Actions

Action Rules
Create / Update / Delete Draft only for update/delete
Post Draft with total greater than zero → Finance JE + AR open item → Posted
Unpost Reverse Finance posting → Draft; blocked if payments reduced open amount
Cancel Draft only
flowchart TD A[Draft invoice] --> B[Post] B --> C[Posted] C --> D[Finance receipt allocations] D --> E{Fully paid} E -->|No| F[Partially Paid] E -->|Yes| G[Paid] C --> H[Unpost if no payments] H --> A A --> I[Cancel]

5.6 Tax and amounts

Tax amount is maintained on the invoice header. On post, if tax is greater than zero, Finance credits the output VAT account. Total should equal subtotal + tax. Finance validates line sums against subtotal and totals within a small tolerance.

6. Collections

Collections are not entered in Sales. Use Finance receipt / payment vouchers:

  1. Open Collections from Sales (redirects to Finance payment vouchers) or Finance directly.
  2. Create a Receipt for the customer and treasury account.
  3. Allocate to the posted sales invoice open item.
  4. Sales invoice paid/open amounts and status update automatically via Finance allocation.

Unposting a receipt allocation reverts the invoice payment amounts.

flowchart TD A[Posted Sales Invoice] --> B[Finance Receipt voucher] B --> C[Allocate to invoice] C --> D[PaidAmount increases] D --> E[Status PartiallyPaid or Paid]

7. Overview screen

/sales/overview provides a sales overview experience for navigation and pipeline-style presentation. Treat operational truth as the live Orders and Invoices lists plus Finance customer/collection screens. Prototype components for customers/collections/invoices exist in the codebase but are not the live routes (customers/collections redirect to Finance; invoices use the real API screen).

8. Permissions summary

Permission group: Sales.

Permission Typical use
Orders List and view orders
Orders.Create Create orders
Orders.Update Confirm, cancel, convert to invoice
Orders.Delete Delete draft orders
Invoices List and view invoices
Invoices.Create Create invoices / convert
Invoices.Update Update, unpost, cancel
Invoices.Delete Delete draft invoices
Invoices.Post Post invoice to Finance

Posting also requires Finance ability to post journal entries. Convert needs both order update and invoice create rights.

9. Integration with Finance

flowchart TB subgraph Sales O[Sales Order] I[Sales Invoice] end subgraph Finance P[Customer PartnerSubLedger] JE[Journal Entry] SL[AR Sub-ledger transaction] RV[Receipt voucher] end P --> O P --> I O -->|Convert| I I -->|Post| JE I -->|Post| SL RV -->|Allocate| I
Event Finance effect
Invoice Post Debit AR, credit revenue (and output VAT if tax); create customer sub-ledger invoice open item; store journal entry id
Invoice Unpost Reverse posting if no payments applied
Receipt allocation Increases PaidAmount; may set PartiallyPaid / Paid
Customer master Maintained only in Finance

Default posting accounts are configured in Finance posting services (AR, revenue, output VAT), with optional overrides from partner GL account or invoice line revenue account.

Appendix A — Quick procedures

A.1 Order to cash

  1. Ensure customer exists in Finance.
  2. Create sales order → Confirm.
  3. Convert to invoice.
  4. Post the invoice.
  5. Create Finance receipt and allocate to the invoice until Paid.

A.2 Standalone invoice

  1. Create Draft sales invoice with lines, tax, and totals.
  2. Post.
  3. Collect via Finance receipt allocations.

A.3 Correct a posted invoice before payment

  1. Ensure PaidAmount is still zero.
  2. Unpost → Draft.
  3. Edit and post again, or cancel the draft if abandoning.

Appendix B — Operating notes

Topic Guidance
Inventory No stock issue/delivery from Sales in the current module
Multi-line UI Current create dialogs may focus on a simple line entry; use API/full form capabilities as exposed in your build
Invoice cancel Available in API for Draft; confirm UI button availability in your build
Menu vs route policy Invoices route requires Sales.Invoices; ensure roles have invoice permissions, not only order permissions
Overview Use for orientation; rely on Orders/Invoices/Finance for transactions

Appendix C — Document control

Item Value
Title Sales Module User Guide
Source of truth modules/sales and frontend/src/app/modules/sales
Format Markdown + Mermaid (PDF edition embeds rendered figures)
Screenshots Not included (by design)

This guide describes functional capabilities of the Sales module as implemented in the Vertex ERP codebase. UI labels may appear in English or Arabic depending on language settings.

Vertex ERP documentation. Generated from Markdown sources in docs/.