# CreateShipment

## Permission Scope

shipment

## Overview

CreateShipment creates a draft shipment against open sales-order lines that are ready for fulfillment. It records draft quantities, dates, ship-from site, and optional tracking context before posting.

## Business Rules

- Referenced sales order must be in an executable status and have open shippable quantity.
- Each shipment line must reference a valid sales-order line and a quantity greater than zero.
- Draft shipment data must remain within the same company scope as the order.

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B[Load sales order]
    B --> C[Validate open shippable quantities]
    C --> D[Insert draft shipment and shipment lines]
    D --> E[Return draft shipment]
```

## External Dependencies

- [getSalesOrder](../queries/GetSalesOrder.md) - Validate the source sales order and open quantities.
- [organization::GetSite](../../../organization/docs/queries/GetSite.md) - Validate ship-from site context.

## Error Scenarios

- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
- **ORDER_NOT_SHIPPABLE**: Sales order does not allow new shipment creation.
- **INVALID_SHIPMENT_LINE**: Shipment line quantity or reference is invalid

## Test Cases

- creates a draft shipment against a confirmed order
- throws when order has no open shippable quantity
- throws when shipment line quantity is not positive
