# PlaceSalesOrderOnCreditHold

## Permission Scope

salesOrder

## Overview

PlaceSalesOrderOnCreditHold suspends further shipment or invoice release on an executable order without cancelling the underlying customer commitment. The command is used for credit, compliance, or dispute review events that temporarily block execution.

## Business Rules

- Only executable orders may be placed on credit hold.
- A non-empty hold reason is required.
- Placing the order on hold must not erase already posted shipment or issued invoice progress.

## Process Flow

```mermaid
flowchart TD
    A[Receive hold request] --> B[Load sales order]
    B --> C{Order executable?}
    C -->|No| D[Return INVALID_ORDER_STATUS]
    C -->|Yes| E{Reason provided?}
    E -->|No| F[Return HOLD_REASON_REQUIRED]
    E -->|Yes| G[Store hold reason and set status to CREDIT_HOLD]
    G --> H[Return held order]
```

## External Dependencies

- None

## Error Scenarios

- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
- **INVALID_ORDER_STATUS**: Sales order status does not allow this operation
- **HOLD_REASON_REQUIRED**: A hold reason is required.

## Test Cases

- places a confirmed order on credit hold
- preserves prior shipment and invoice progress when placing hold
- throws when order is not in an executable status
- throws when hold reason is empty
