# CreateListing

## Permission Scope

marketplace

## Overview

CreateListing creates a draft channel listing that maps one internal item into one external channel context. It preserves sellability metadata and external identifier placeholders before activation.

## Business Rules

- Referenced channel and item must exist and belong to the same company scope.
- The item must be ACTIVE before a listing can be created for new sellability.
- Listing identity must be unique enough to avoid operational ambiguity within the channel context.

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B[Validate channel and item]
    B --> C[Validate listing identity]
    C --> D[Insert draft listing]
    D --> E[Return created listing]
```

## External Dependencies

- [getChannel](../queries/GetChannel.md) - Validate the target channel exists.
- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate the referenced item exists and is active.

## Error Scenarios

- **CHANNEL_NOT_FOUND**: Referenced channel does not exist
- **ITEM_NOT_FOUND**: One or more referenced items do not exist
- **ITEM_NOT_ACTIVE**: Referenced item is not active for listing use.
- **DUPLICATE_LISTING_IDENTITY**: A conflicting listing identity already exists.

## Test Cases

- creates a draft listing for an active item and valid channel
- throws when channel does not exist
- throws when item is inactive
- throws when listing identity conflicts within the channel
