# ConvertChannelOrder

## Permission Scope

marketplace

## Overview

ConvertChannelOrder materializes or links the internal sales order for a pending channel order once required mappings succeed. It is the write path that moves normalized external demand into the standard sales-order lifecycle without bypassing sales rules.

## Business Rules

- Only PENDING_CONVERSION channel orders may be converted.
- Required customer, listing, item, currency, and company mappings must be valid before conversion.
- Successful conversion must create or update the internal sales order before the channel order moves to CONVERTED.

## Process Flow

```mermaid
flowchart TD
    A[Receive convert request] --> B[Load pending channel order]
    B --> C[Validate customer, listing, item, and currency mappings]
    C --> D{Mappings valid?}
    D -->|No| E[Return CHANNEL_ORDER_MAPPING_FAILED]
    D -->|Yes| F[Create or update SalesOrder]
    F --> G[Store linked sales order reference and set status to CONVERTED]
    G --> H[Return converted channel order]
```

## External Dependencies

- [getChannelOrder](../queries/GetChannelOrder.md) - Load pending conversion context.
- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Validate resolved customer mapping.
- [getListingByExternalIdentifier](../queries/GetListingByExternalIdentifier.md) - Validate listing to item mapping.
- [primitives::GetCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validate resolved currency.

## Error Scenarios

- **CHANNEL_ORDER_NOT_FOUND**: Referenced channel order does not exist.
- **INVALID_CHANNEL_ORDER_STATUS**: Channel order status does not allow this operation
- **CHANNEL_ORDER_MAPPING_FAILED**: Required customer, listing, item, or currency mapping is missing.

## Test Cases

- converts a pending channel order into a sales order
- stores linked sales order reference after conversion
- throws when channel order is not pending conversion
- throws when required mappings are missing
