# UpdateShipment

## Permission Scope

shipment

## Overview

UpdateShipment revises draft shipment details before posting. It supports correction of shipment lines, addresses, ship dates, carrier metadata, or tracking references.

## Business Rules

- Only DRAFT shipments may be updated directly.
- Updated shipment quantities must remain within remaining shippable order quantities.

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B[Load shipment]
    B --> C{Status is DRAFT?}
    C -->|No| D[Return SHIPMENT_NOT_EDITABLE]
    C -->|Yes| E[Validate updated shipment details]
    E --> F[Persist shipment changes]
    F --> G[Return updated shipment]
```

## External Dependencies

- [getShipment](../queries/GetShipment.md) - Load current shipment state before applying changes.

## Error Scenarios

- **SHIPMENT_NOT_FOUND**: Referenced shipment does not exist.
- **SHIPMENT_NOT_EDITABLE**: Only DRAFT shipments may be updated.
- **INVALID_SHIPMENT_LINE**: Shipment line quantity or reference is invalid

## Test Cases

- updates draft shipment metadata
- returns error when updating a posted shipment
- returns error when updated quantity exceeds remaining order quantity
