07 · Sales — sales, delivery, and field visits

Solution(2) layer. Depends on Common, Organization, Accounting, Tax, Inventory, and Costing. This is the largest model in the contour: goods issue, customer receivables, delivery, and field sales.

← General specification

Purpose#

Sales manages the chain from sales order to money and to the buyer's door. An order reserves goods, the realization writes them off from the picking cell and recognizes revenue, and a payment clears the receivable. The same model also covers delivery trips, routes, drivers, vehicles, and field visits by sales agents.

Transaction terms do not live on the document. They live on the contract, and the contract belongs to the outlet. Without a contract, the order cannot be saved or posted.

For the process view, see Sales and purchasing. This page is the object-level reference.

What is created#

Total: 10 dictionaries, 9 documents, 6 registers, 6 services, 2 link tables, 4 enums, 21 commands, and 1 job.

model.json#

Solution(2) layer. Dependencies: Accounting, Common, Inventory, Organization, Tax, and Costing.

The dependency on Costing points from Sales to Costing because Sales computes margin in GrossMarginService. A reverse edge would create a cycle. See 10 · Costing.

Number sequences#

One sequence per object: SalesOrderSeq, SalesRealizationSeq, SalesReturnSeq, SalesCreditNoteSeq, SalesDebitNoteSeq, CustomerPaymentSeq, DeliveryTripSeq, VisitRouteSeq, AgentVisitSeq, SalesContractSeq, SalesPersonSeq, DeliveryRouteSeq, DeliveryRouteStopSeq, DeliveryScheduleSeq, DriverSeq, VehicleSeq, AbcProfileSeq, AbcClassBandSeq, SalesSettingsSeq.

SalesInvoiceLines and SalesInvoiceReserveTx are historical physical names, and this is not an error. The document is SalesRealization (menu Sales realizations). The sequence is SalesRealizationSeq. The table part stayed SalesInvoiceLines / TP_SalesInvoiceLines. Renaming it would replace the physical table. Tax calculations still key by the reason prefix "Sales invoice <id>".

Table parts#

SalesOrderLines, SalesInvoiceLines (realization lines), SalesReturnLines, SalesCreditNoteLines, SalesDebitNoteLines, CustomerPaymentLines, DeliveryTripLines, and VisitRouteStops.

EDT#

References: RefSalesContract, RefSalesPerson, RefDeliveryRoute, RefDriver, RefVehicle, RefAbcProfile. Enums: SettlementKindEdt, StopOutcomeEdt, VehicleKindEdt, WeekdayEdt. Scalars: AbcClassCode, AbcManualFlag, AbcSubjectKey, GeoValue, BatteryLevel, IdempotencyKey, MobileActionName, MobileEntityRef, MobileStatusCode, MobileResponseText.

Dictionaries#

SalesContract#

SalesContract is the center of the model. It belongs to a customer outlet: CustomerOutlet is required, and the buyer is copied from the outlet, not selected separately. The contract carries currency, settlement type (SettlementKind), payment term (PaymentTerm), delivery term (DeliveryTerm, Incoterms), price type, credit limit, and effective date window.

Contract prices are entered in link tables. SalesContractPrice stores the price per item. SalesContractQtyBreak stores volume discounts. They are not fields because one contract can have many dated prices and breaks.

Routes and delivery#

DeliveryRoute is the route. DeliveryRouteStop stores its stops in order. DeliverySchedule stores the weekdays (Weekday) when the route runs. Driver and Vehicle (VehicleKind) store who drives and what vehicle is used.

ABC/XYZ#

AbcProfile sets calculation parameters, and AbcClassBand sets class boundaries. The result is written to AbcClassification. RecalcAbcClassifications recalculates it.

Documents#

SalesOrder#

Subtypes: Draft → Submitted → Confirmed. Confirmation reserves goods in ReservedStock and creates a realization.

Commands: SubmitSalesOrder, ApproveSalesOrder, RejectSalesOrder, CancelSalesOrder, and FillSalesPrices.

A line price is not copied directly from a price record. It is calculated through PricingService from Inventory, subject to the contract. The price origin remains visible, so the manager can see why the amount was selected.

SalesRealization#

Subtypes: Reserved … Issued. Stock, receivable, output tax, and loyalty are posted only in Issued. Intermediate subtypes do not move anything.

Commands: StartPicking, MarkPacked, MarkShipped, MarkDelivered, IssueInvoice, and ReleaseRealization.

Paid and Voided are not realization states. Payment is a separate CustomerPayment document. Cancellation is a SalesReturn or SalesCreditNote.

CustomerPayment, SalesReturn, SalesCreditNote, SalesDebitNote#

Payment clears Receivable. Returns and notes adjust revenue and tax. Commands: ReceiveCustomerPayment, MarkPaid, PostSalesReturn, PostSalesCreditNote, and PostSalesDebitNote.

Exchange differences: ExchangeRate, ReceivableRevaluation#

A contract may be in a currency other than its legal entity's. SalesRealization stamps ExchangeRate (contract currency to the entity's, on the invoice date) when it moves to Issued and refuses without a rate; SalesCreditNote, SalesDebitNote and SalesReturn take the original invoice's rate. Receivable keeps Amount in the contract's currency and AmountFunc in the entity's; Revenue, the ledger legs and the output-tax base are amount × rate. CustomerPayment lines stamp the payment-date ExchangeRate and the CarryingAmount they settle (the slice's average carrying value), and CustomerPaymentGLTx books the gap to FxGainAccountCode / FxLossAccountCode.

ReceivableRevaluation (Draft → Posted) books the unrealised difference at period end. Commands: FillReceivableRevaluation (every open foreign-currency slice of the legal entity, at the rate on the document date), PostReceivableRevaluation, CancelReceivableRevaluation. ReceivableRevaluationTx moves AmountFunc by the difference; ReceivableRevaluationGLTx books gains and losses as two sums. The revalued value is not reversed; the next payment measures its difference against it. ISalesFx (SalesFx) answers the rate for a contract, the functional amount and the carrying value. A contract's Currency cannot change while its slice is open. With AccountingSettings.RevalueFxOnPeriodClose on, closing a FiscalPeriod first posts the receivable and payable revaluations dated its last day (FiscalPeriodSalesFxEventHandler, FiscalPeriodPurchaseFxEventHandler); a failure keeps the period open. Process view: exchange differences.

DeliveryTrip, VisitRoute, AgentVisit#

A trip is assembled from a route with FillTripFromRoute, dispatched with DispatchTrip, and completed with CompleteTrip. An agent visit is opened and closed by CheckInVisit and CheckOutVisit. The stop result is StopOutcome.

Example#

Outlet Outlet-1 has a SalesContract in USD. Item Widget is in picking cell Cell-1. Before the scenario, stock is 100 pcs. SalesLinePricing returns a price of 15.00 per unit. Tax and cost are omitted to keep the table readable; the realization really posts output tax and entries in ItemCostFifo/InventoryValue. See Costing.

Scenario result: the buyer still owes 15.00. The picking cell has 8 pcs less than at the start (100 → 92). Recognized revenue is 120.00: 150.00 sale minus 30.00 return minus 10.00 credit note. The 5.00 debit note does not change the Revenue column in this example because it charges a delivery service, not goods.

Registers#

Register dimensions and resources: see Receivable, ReservedStock, Revenue, AbcClassification, AgentGpsLog, and MobileCommandReceipt in Objects below.

ReservedStock uses the same coordinates as Stock in Inventory: cell and item. Otherwise free = Stock - Reserved would not make sense. The reserve is released in the SalesRealization example: Confirmed added 10, and Issued took them back to 0 in the same movement that wrote off Stock.

AgentGpsLog and MobileCommandReceipt are information registers, not accumulation registers. The first stores track points over time. The second stores a response by idempotency key so a repeated mobile command does not create a second document.

Example slice of AbcClassification. With the default profile and three products by period turnover: Widget has the highest turnover, so AbcClass=A; its demand is stable, so XyzClass=X. A medium item has average turnover and volatile demand, so B/Y. A rare item has rare sales, so C/Z. The scheduled job RecalcAbcClassifications rewrites AbcClass, XyzClass, Score, Share, and Cv, but does not touch ManualAbc or ManualXyz. If an analyst manually raises a rare item to B with ManualAbc, recalculation does not erase it.

Services#

• SalesLinePricing calculates the line price and records its origin.
• SalesContractService selects the contract applicable on a date.
• SalesFulfillmentService handles reservation and fulfillment.
• DeliveryService assembles trips and stop order.
• GrossMarginService calculates gross margin. It lives here, not in Costing, to avoid a dependency cycle.
• AbcClassifier calculates classes by profile.
• SalesFx gives a contract's exchange rate on a date, functional amounts, and the carrying value a payment settles.

Business logic and invariants#

The contract is required. An order is not saved without a contract. The contract is tied to the outlet and copies the buyer from it. This is not duplication; it protects sales when one customer has several outlets.

Reserve is released by subtype rollback. ReservedStock grows on Confirmed and decreases when you roll back. Free balance is counted by cell, not by store.

Postings run only on the target subtype. A command performs the transition, not a dropdown list. The subtype's full tx script list runs by executionOrder.

Manual classification survives recalculation. ManualAbc and ManualXyz on AbcClassification are not overwritten by the scheduled job.

Menu#

Sales tab: Documents (orders, realizations, payments, returns, notes, trips, visits) · Dictionaries (contracts, sales agents, routes, drivers, vehicles) · Registers (receivable, revenue, reserve, classification) · Settings (SalesSettings, ABC profiles).

Customers and outlets are placed here in the menu although the objects belong to Inventory. The menu entry lives where users need it.

Links with other modules#

• Outgoing: Inventory for items, store, stock, and prices; Tax for Tax Engine; Accounting for ledger posting; Costing for margin cost; Common for currency, payment terms, and delivery terms.
• Incoming: CRM builds leads and KPIs over orders and accrues loyalty on Issued; localizations extend realization and build electronic invoices, for example 21 · Saudi Arabia; sales, returns, payments and cost of sales are posted to the ledger by Sales itself (SalesRevenueGLTx, SalesReturnGLTx, CustomerPaymentGLTx, cost of sales in SalesRealizationEventHandler; see Who writes the general ledger).

Objects#

Generated from workspace metadata by node tools/gen-reference.mjs; edit the metadata, not this block.

Dictionaries#

AbcClassBand — ABC class bands

One class interval of a profile on the ABC or XYZ axis. Unique Profile+Axis+ClassCode.

AbcPolicyCell — ABC replenishment cells

One AX…CZ cell of a profile: class pair plus keep-stock or buy-to-order. Letters are data, not hardcoded.

AbcProfile — ABC profiles

Configurable ABC/XYZ scheme: subject, measure, window and methods. Bands live in AbcClassBand.

DeliveryRoute — Delivery route

DeliveryRouteStop — Route stops

Ordered outlet on a delivery route.

DeliverySchedule — Delivery schedules

Recurring weekday wave: route, depart time, default crew.

Driver — Drivers

Delivery driver. Not a sales agent and not an HR employee.

LegacyBasis — Legacy settlement bases

Order of the predecessor system with open debt, not migrated as a document. MetaId equals the Basis used in ReceivableByBasis.

SalesContract — Sales contracts

Commercial terms of an outlet: currency, settlement, payment term, price type, dated window.

SalesPerson — Sales person

SalesSettings — Sales settings

Vehicle — Vehicles

Delivery vehicle: plate, kind, capacity.

Documents#

AgentTask — Agent task

Call, collect, or other work assigned to a sales person. Not a visit stop and not a payment.

Header fields:

Subtypes:

Commands:

AgentVisit — Agent visit

Header fields:

Subtypes:

Commands:

CustomerPayment — Customer payment

Header fields:

Subtypes:

Commands:

CustomerRefund — Customer refund

Money paid back to a customer from a cash desk or a bank account (overpayment, returned goods). Posting raises the customer's receivable on the contract and basis, lowers the desk or account balance and debits receivables against its ledger account.

Header fields:

Subtypes:

Commands:

DeliveryTrip — Delivery trip

Header fields:

Subtypes:

Commands:

ReceivableRevaluation — Receivable revaluation

Period-end revaluation of foreign-currency receivables. Fill revaluation lists every open contract slice of the legal entity whose contract currency is not the entity's own, at the rate on the document date; Post revaluation moves Receivable.AmountFunc to the revalued amount and books the unrealised exchange difference. The revalued carrying value stays: the next payment's realised difference is measured against it.

Header fields:

Subtypes:

Commands:

SalesCreditNote — Sales credit note

Header fields:

Subtypes:

Commands:

SalesDebitNote — Sales debit note

Header fields:

Subtypes:

Commands:

SalesOrder — Sales order

Process B: Draft → Submitted → Confirmed (Approved) → Delivered. Confirmed creates a realization invoice in Reserved; its walk to Issued closes the order as Delivered. When that invoice leaves Issued (back to Draft, cancelled, deleted), the order returns to Confirmed (SalesFulfillmentService.ReopenSourceOrderAsync from the invoice's OnBeforeUnpostAsync); another Issued invoice of the order keeps it Delivered.

Header fields:

Subtypes:

Commands:

SalesRealization — Sales realization

Header fields:

Subtypes:

Commands:

SalesReturn — Sales return

Header fields:

Subtypes:

Commands:

VisitRoute — Visit route

Header fields:

Subtypes:

Commands:

Registers#

AbcClassification — ABC classification

SliceLast by Profile + Subject (Item or Customer Guid). Recalc writes Period=asOf; ManualAbc/ManualXyz keep a class across runs.

Dimensions:

Resources:

AbcSuggestion — ABC replenishment suggestion

SliceLast by Profile + Item. Written by IAbcPolicy. A purchase draft is a separate command and does not post stock.

Dimensions:

Resources:

AgentGpsLog — Agent GPS log

Dimensions:

Resources:

MobileCommandReceipt — Mobile command receipt

Dimensions:

Resources:

Receivable — Receivable

Resources:

Analytics:

ReceivableBasis — Receivable by basis

Companion of Receivable: the same debt, sliced by the document it settles against (Basis). Customer x contract x basis. The sum over bases equals the Receivable balance of the same customer and contract.

Dimensions:

Resources:

ReceivableByBasis — Receivable by basis

Companion of Receivable: the same debt, sliced by the document it settles against (Basis). Customer x contract x basis. The sum over bases equals the Receivable balance of the same customer and contract.

Dimensions:

Resources:

ReservedStock — Reserved stock

Resources:

Analytics:

Revenue — Revenue

Recognized sales revenue by item, customer and contract: amount in the legal entity currency and quantity in the item base unit. Optional legal entity and outlet cuts.

Resources:

Analytics:

Table parts#

CustomerPaymentLines — Lines

Used by: CustomerPayment.

DeliveryTripLines — Stops

Used by: DeliveryTrip.

ReceivableRevaluationLines — Lines

Used by: ReceivableRevaluation.

SalesCreditNoteLines — Lines

Used by: SalesCreditNote.

SalesDebitNoteLines — Lines

Used by: SalesDebitNote.

SalesInvoiceLines — Lines

Used by: SalesRealization.

SalesOrderLines — Lines

Used by: SalesOrder.

SalesReturnLines — Lines

Used by: SalesReturn.

VisitRouteStops — Stops

Used by: VisitRoute.