Order

The Order entity represents a confirmed customer order with billing information, delivery tracking, and line items. Orders are created after quotes are accepted or directly for catalog products, and they track the entire fulfillment lifecycle from placement through delivery.

Key Properties

Core Identifiers

Property	Type	Description	Validation
`id`	UUID	Unique order identifier	Generated automatically
`externalId`	string	External system/ERP order ID	Optional, for bidirectional sync

Billing Information

Property	Type	Description	Validation
`billedAmount`	number	Total billed amount	Required on create, double precision
`currencyId`	UUID	Currency for billing	Optional, references Currency entity

Delivery Tracking

Property	Type	Description	Validation
`orderDate`	Date	When order was placed	Optional
`expectedDeliveryDate`	Date	Estimated delivery date	Optional
`actualDeliveryDate`	Date	Actual delivery date	Optional, set when delivered
`trackingId`	string	Shipping tracking number	Optional
`shippingAddressId`	UUID	Delivery address	Optional, references Address entity

Metadata

Property	Type	Description	Validation
`statusId`	UUID	Current order status	Optional, references Status entity
`createdById`	UUID	User who created order	Optional, references User entity
`createdAt`	Date	Creation timestamp	Auto-generated
`updatedAt`	Date	Last update timestamp	Auto-generated, indexed
`deletedAt`	Date	Soft delete timestamp	Optional, indexed

Main Relationships

Relationship	Type	Target Entity	Description	Required
`items`	One-to-Many	OrderItem	Line items in the order	Yes
`company`	Many-to-One	Company	Customer company	No
`project`	Many-to-One	Project	Associated project	No
`status`	Many-to-One	Status	Order status (e.g., pending, shipped)	No
`currency`	Many-to-One	Currency	Billing currency	No
`shippingAddress`	Many-to-One	Address	Delivery destination	No
`createdBy`	Many-to-One	User	User who created order	No
`files`	One-to-Many	File	Attached documents (invoices, receipts)	No
`comments`	One-to-Many	Comment	Order comments and notes	No
`customFields`	One-to-Many	CustomFieldValue	Custom field values	No

Status Management

Orders support customizable status workflows through the Status entity.

Common Status Workflow:

Pending → Order created, awaiting processing
Processing → Order being prepared/manufactured
Shipped → Order dispatched to customer
Delivered → Order received by customer
Cancelled → Order cancelled
On Hold → Order temporarily paused

Status Configuration:

Statuses are configurable per organization
Each status has internal and external labels
Status transitions can be tracked via updatedAt field

ERP Integration

The Order entity supports bidirectional synchronization with ERP systems:

Key Fields for Integration

Field	Purpose	Usage
`externalId`	ERP order reference	Store ERP order ID for sync
`billedAmount`	Total billing amount	Sync with ERP invoicing
`trackingId`	Shipping tracking	Update from shipping system
`orderDate`	Order placement date	Sync with ERP order date
`expectedDeliveryDate`	Delivery estimate	Calculate from ERP production schedule
`actualDeliveryDate`	Confirmed delivery	Update from shipping/delivery confirmation

Integration Patterns

1. Create Order from ERP:

POST /orders
{
  "externalId": "ERP-12345",
  "companyId": "uuid-company",
  "projectId": "uuid-project",
  "billedAmount": 5000.00,
  "orderDate": "2024-01-15T10:00:00Z"
}

2. Query Order by ERP ID:

GET /orders?externalId=ERP-12345

3. Update Delivery Status:

PATCH /orders/:id
{
  "trackingId": "TRACK-987654",
  "actualDeliveryDate": "2024-02-14T14:30:00Z"
}

Endpoint	Method	Description
/orders	POST	Create new order
/orders/:id	GET	Get order with items
/orders/:id	PATCH	Update order
/orders/:id	DELETE	Delete order (soft delete)
/orders	GET	List orders with filtering

Workflow Examples

Example 1: Standard Order Creation

// 1. Create Order
POST /orders
{
  "companyId": "company-uuid",
  "projectId": "project-uuid",
  "billedAmount": 3500.00,
  "currencyId": "currency-uuid",
  "orderDate": "2024-01-15T10:00:00Z",
  "expectedDeliveryDate": "2024-02-15T10:00:00Z",
  "shippingAddressId": "address-uuid"
}

// 2. Add Order Items (see OrderItem entity)
// 3. Track delivery progress via status updates

Example 2: Delivery Tracking Update

// Update tracking information
PATCH /orders/order-uuid
{
  "trackingId": "TRACK-123456",
  "statusId": "shipped-status-uuid"
}

// Later: confirm delivery
PATCH /orders/order-uuid
{
  "actualDeliveryDate": "2024-02-14T09:30:00Z",
  "statusId": "delivered-status-uuid"
}

Query Capabilities

The Order entity supports advanced filtering and pagination:

Filter Parameters:

companyId: Filter by customer
projectId: Filter by project
statusId: Filter by status (comma-separated for multiple)
externalId: Filter by ERP ID
orderDateStart, orderDateEnd: Date range filters
expectedDeliveryDateStart, expectedDeliveryDateEnd: Delivery estimate filters
actualDeliveryDateStart, actualDeliveryDateEnd: Actual delivery filters
createdById: Filter by creator

Pagination:

page: Page number (default: 1)
limit: Items per page (default: 10)
sort: Sort field (e.g., orderDate, updatedAt)
order: Sort direction (ASC, DESC)

Example Query:

GET /orders?companyId=uuid&statusId=uuid-1,uuid-2&orderDateStart=2024-01-01&page=1&limit=50&sort=orderDate&order=DESC