Sales Module

Back

Overview

The Sales module is responsible for managing all sales-related data, including orders, order lines, time tracking, categorisation and status workflows. It defines how sales are created, processed, and tracked within the system.

Sales is a foundational module and is required for:

• recording customer orders
• processing individual order lines
• managing order statuses and types
• time tracking against orders
• tracking payments, dispatch, and fulfillment
• auditing all sales activity

All operations are tenant-aware and scoped to the current tenant.

Services

The Sales module consists of the following services:

• Documents - transactional documents (sales orders, credit notes, quotes, etc.)
• Document Lines - individual line items within a document
• Cart - shopping carts with anonymous support and document conversion
• Document Types - classification of documents (e.g. Sales Order, Credit Note)
• Document Categories - grouping/classification for documents
• Document Action Statuses - configurable workflow status definitions
• Document Action Status Map - status history log per document
• Document Time Task Types - types of billable/trackable work
• Document Time Entries - time logged against a document

Models

This module exposes and consumes the following models:

• Document Model — see Document Service
• Document Line Model — see Document Service
• Cart Model
• Cart Item Post DTO
• Document Type Model
• Document Category Model
• Document Action Status Model
• Document Action Status Map Model
• Document Time Task Type Model
• Document Time Entry Model

Cart Model

Represents a shopping cart that can be created anonymously and later converted to a document (sales order).

Fields:

• Id (type: long) - internal identifier
• DateAdded (type: DateTime?) - creation timestamp
• Guid (type: string?) - client-assigned GUID (used for anonymous cart lookup)
• DeviceId (type: string?) - device identifier
• UserId (type: long?) - associated user
• CartTypeId (type: int?) - FK to CartType (1=Guest, 2=Wishlist, 3=Saved For Later, 4=Quote)
• DateLastUpdated (type: DateTime?) - last update timestamp
• Items (type: List<CartItemModel>?) - cart line items (populated on read)

Validation:

• IsReadyToAdd() — requires at least one of Guid, DeviceId, or UserId

Cart Item Post DTO

Used when upserting items via POST /api/v1/Cart/items.

Fields:

• Sku (type: string) - product SKU
• Quantity (type: int) - quantity (set to 0 or negative to remove the item)

Document Type Model

Represents the type/classification of a document (Sales Order, Credit Note, Quote, etc.).

Fields:

• Id (type: int) - internal identifier
• Title (type: string?) - document type name
• IsCredit (type: bool?) - indicates if the type represents a credit document

Validation:

• IsReadyToAdd() - requires Title
• IsReadyToUpdate() - requires Id > 0, Title

Document Category Model

Represents a grouping or classification label for documents.

Fields:

• Id (type: int) - internal identifier
• Name (type: string?) - category name
• Description (type: string?) - optional description
• SortOrder (type: int) - display order
• IsActive (type: bool) - active flag
• CreatedAt (type: DateTime?) - creation timestamp

Validation:

• IsReadyToAdd() - requires Name
• IsReadyToUpdate() - requires Id > 0, Name

Notes:

• Only one category can exist per name

Document Action Status Model

Represents a configurable action status that can be applied to a document (e.g., Pending Review, Approved, On Hold).

Fields:

• Id (type: int) - internal identifier
• Name (type: string?) - status name
• Description (type: string?) - optional description
• SortOrder (type: int) - display order
• IsActive (type: bool) - active flag
• CreatedAt (type: DateTime?) - creation timestamp

Validation:

• IsReadyToAdd() - requires Name
• IsReadyToUpdate() - requires Id > 0, Name

Document Action Status Map Model

Represents a status assignment on a specific document — acts as a status history log.

Fields:

• Id (type: int) - internal identifier
• DocumentId (type: long) - parent document
• ActionStatusId (type: int) - applied action status
• Notes (type: string?) - optional notes
• CreatedByUserId (type: int?) - user who applied the status
• CreatedAt (type: DateTime?) - timestamp when applied

Validation:

• IsReadyToAdd() - requires DocumentId > 0, ActionStatusId > 0
• IsReadyToUpdate() - requires Id > 0, DocumentId > 0, ActionStatusId > 0

Notes:

• Multiple status entries per document are allowed — full history is preserved

Document Time Task Type Model

Represents a category of work that can be time-tracked against a document (e.g., Design, Development, Support).

Fields:

• Id (type: int) - internal identifier
• Name (type: string?) - task type name
• Description (type: string?) - optional description
• SortOrder (type: int) - display order
• IsActive (type: bool) - active flag
• CreatedAt (type: DateTime?) - creation timestamp

Validation:

• IsReadyToAdd() - requires Name
• IsReadyToUpdate() - requires Id > 0, Name

Document Time Entry Model

Represents a block of time logged by a user against a document.

Fields:

• Id (type: int) - internal identifier
• DocumentId (type: long) - parent document
• UserId (type: int) - user who performed the work
• TaskTypeId (type: int) - type of work performed
• WorkDate (type: DateOnly?) - date the work was performed
• TotalMinutes (type: int) - duration in minutes
• Notes (type: string?) - optional notes
• CreatedByUserId (type: int?) - user who created the entry
• CreatedAt (type: DateTime?) - creation timestamp

Validation:

• IsReadyToAdd() - requires DocumentId > 0, UserId > 0, TaskTypeId > 0, TotalMinutes > 0, WorkDate
• IsReadyToUpdate() - requires Id > 0, DocumentId > 0, UserId > 0, TaskTypeId > 0