OrderItem

The OrderItem entity represents a line item within an order. Each OrderItem references an article (catalog product) and includes quantity, pricing, and measurement units. OrderItems can be organized hierarchically to represent product kits or grouped items.

---

Key Properties

Core Identifiers

Property	Type	Description	Validation
id	UUID	Unique item identifier	Generated automatically
orderId	UUID	Parent order reference	Optional, references Order entity
articleId	UUID	Product reference	Optional, references Article entity

Pricing

Property	Type	Description	Validation
quantity	number	Quantity ordered	Required, must be positive
unitPrice	number	Price per unit	Optional, double precision
totalPrice	number	Total line price	Optional, double precision, min: 0, default: 0
unit	string	Measurement unit	Optional (e.g., “pcs”, “kg”, “m”)

Pricing Calculation: totalPrice = quantity * unitPrice

Organization

Property	Type	Description	Validation
position	number	Display order in list	Optional, default: 1
parentId	UUID	Parent item for hierarchy	Optional, self-reference

Metadata

Property	Type	Description	Validation
createdById	UUID	User who created item	Optional, references User entity
commentId	UUID	Associated comment	Optional, references Comment entity
createdAt	Date	Creation timestamp	Auto-generated
updatedAt	Date	Last update timestamp	Auto-generated
deletedAt	Date	Soft delete timestamp	Optional, indexed

---

Main Relationships

Relationship	Type	Target Entity	Description	Required
order	Many-to-One	Order	Parent order	No
article	Many-to-One	Article	Product reference	No
parent	Many-to-One	OrderItem	Parent item for hierarchy	No
children	One-to-Many	OrderItem	Child items in hierarchy	No
createdBy	Many-to-One	User	User who created item	No
comment	One-to-One	Comment	Associated comment/note	No

---

Item Types

OrderItem can reference different types of products:

1. Article Reference (Primary Use Case)

Description: References a catalog product (Article entity)

When to Use:

• Ordering from product catalog
• Standard inventory items
• Pre-configured products

Properties Used:

• articleId: Links to Article entity
• Article provides: name, code, price, inventory status
• Article may link to BriefElement for manufacturing specs

Example:

{
  "orderId": "order-uuid",
  "articleId": "article-uuid",
  "quantity": 1000,
  "unitPrice": 1.50,
  "totalPrice": 1500.00,
  "unit": "pcs"
}

2. Standalone Item

Description: Item without article reference (rare)

When to Use:

• Custom one-off items
• Special pricing scenarios
• Non-inventory items

Example:

{
  "orderId": "order-uuid",
  "quantity": 1,
  "unitPrice": 500.00,
  "totalPrice": 500.00,
  "unit": "service"
}

---

Hierarchical Structure

OrderItems support parent-child relationships for complex order structures.

Use Cases

1. Product Kits: Parent represents the kit, children are components
2. Grouped Items: Organize related items under a parent
3. Assembly Orders: Parent is assembled product, children are parts

Hierarchy Example

Order with Product Kit:

Order
  └── OrderItem (parent) → Product Kit
        ├── OrderItem (child) → Component A
        ├── OrderItem (child) → Component B
        └── OrderItem (child) → Component C
  └── OrderItem → Standalone Product

Implementation:

// 1. Create Parent Item (Kit)
POST /order-items
{
  "orderId": "order-uuid",
  "articleId": "kit-article-uuid",
  "quantity": 100,
  "unitPrice": 50.00,
  "totalPrice": 5000.00,
  "unit": "kits"
}
// Response: { "id": "parent-uuid", ... }

// 2. Create Child Items (Components)
POST /order-items
{
  "orderId": "order-uuid",
  "parentId": "parent-uuid",
  "articleId": "component-a-uuid",
  "quantity": 100,
  "position": 1
}

POST /order-items
{
  "orderId": "order-uuid",
  "parentId": "parent-uuid",
  "articleId": "component-b-uuid",
  "quantity": 200,
  "position": 2
}

---

Article Relationship

OrderItems typically reference Articles for product details:

Article Properties Used

When articleId is set, the Article provides:

• Product Information: code, name, description
• Pricing: Default price (can be overridden in OrderItem)
• Inventory: stocked, quantity (stock levels)
• Manufacturing: briefElementId (links to production specifications)
• ERP Integration: externalId (for external system sync)

BriefElement Link (via Article)

Articles can link to BriefElements for manufacturing specifications:

Scenario 1: Article from Configured Product:

• Article created after product configuration
• Article.briefElementId → BriefElement (existing Brief)
• Provides full manufacturing specs for production

Scenario 2: Article from ERP/Catalog:

• Article created independently or from ERP
• May auto-create BriefElement for manufacturing
• May exist without BriefElement (non-packaging items)

Scenario 3: Standalone Article:

• Article without BriefElement link
• Used for non-manufactured items (e.g., tape, labels, services)

---

Related Endpoints

Endpoint	Method	Description
/order-items	POST	Create order item
/order-items/:id	GET	Get single item
/order-items/:id	PATCH	Update order item
/order-items/:id	DELETE	Delete order item
/order-items	GET	List order items

---

Usage Examples

Example 1: Add Article to Order

POST /order-items
{
  "orderId": "order-uuid",
  "articleId": "article-uuid",
  "quantity": 500,
  "unitPrice": 2.00,
  "totalPrice": 1000.00,
  "unit": "pcs",
  "position": 1
}

Example 2: Update Item Quantity

PATCH /order-items/item-uuid
{
  "quantity": 750,
  "totalPrice": 1500.00
}

Example 3: Create Hierarchical Items

// Parent Item (Product Bundle)
POST /order-items
{
  "orderId": "order-uuid",
  "articleId": "bundle-uuid",
  "quantity": 50,
  "unitPrice": 100.00,
  "totalPrice": 5000.00,
  "unit": "bundles"
}
// Response: { "id": "parent-uuid" }

// Child Item 1
POST /order-items
{
  "orderId": "order-uuid",
  "parentId": "parent-uuid",
  "articleId": "item-1-uuid",
  "quantity": 100,
  "position": 1
}

// Child Item 2
POST /order-items
{
  "orderId": "order-uuid",
  "parentId": "parent-uuid",
  "articleId": "item-2-uuid",
  "quantity": 150,
  "position": 2
}

Example 4: Custom Item (No Article Reference)

POST /order-items
{
  "orderId": "order-uuid",
  "quantity": 1,
  "unitPrice": 250.00,
  "totalPrice": 250.00,
  "unit": "service",
  "position": 10
}

---

Best Practices

1. Pricing Consistency

• Always ensure totalPrice = quantity * unitPrice
• Update totalPrice when changing quantity or unit price
• Use consistent decimal precision (typically 2 decimal places)

2. Position Management

• Use position to control display order
• Increment positions (1, 2, 3…) for clear ordering
• Update positions when reordering items

3. Hierarchical Items

• Create parent items first, then children
• Use parentId to establish relationships
• Ensure parent and children belong to same order

4. Article References

• Prefer using articleId over standalone items
• Verify article exists and is active before creating item
• Use Article’s default price but allow overrides for special pricing

5. Units of Measurement

• Use consistent unit naming (e.g., “pcs”, “kg”, “m”)
• Match units to article specifications
• Include unit in all item records for clarity

---

See Also

• Order Entity - Parent order container
• Article Entity - Product catalog
• Orders Integration Guide - Complete order workflow
• Quote Entity - Quote system (similar structure)
• QuoteItem Entity - Quote line items (similar to OrderItem)