# Channel Listing Management

## Overview

Channel Listing Management controls where and how the company offers items on external sales channels. A `Channel` defines a sell-side integration context such as a marketplace, storefront, or distributor feed, while a `Listing` defines the item's channel-specific sellability, publication state, external identifiers, and optional commercial metadata required for that channel. Together they express whether a given item may be sold on a given channel under a governed assortment policy.

This feature is intentionally distinct from core product definition and from order synchronization. Product-management owns the channel-agnostic product identity; item-management owns the SKU-level sellable unit; sales owns the channel-specific commercial representation that decides whether an item is exposed externally and under which identifiers or operational constraints. Actual API synchronization is tracked by `SyncJob` in the separate channel-order sync workflow.

## Business Purpose

- Control which items are sellable on each external channel without changing the core product definition
- Preserve channel-specific identifiers, statuses, and assortment rules required for marketplace or storefront operations
- Prevent inactive items or inactive channels from remaining externally sellable
- Support different commercial presentation or operational settings per channel while keeping the internal item canonical
- Provide the lookup bridge needed for channel-originated orders to map back to internal sales items
- Maintain an auditable listing history for publish, pause, re-list, and retire decisions

## Process Flow

```mermaid
flowchart TD
    A[Create Channel] --> B[Configure company, type, and status]
    B --> C[Create Listing for item]
    C --> D[Assign channel identifiers and publication settings]
    D --> E{Ready to publish?}
    E -->|No| F[Keep listing in draft or paused state]
    E -->|Yes| G[Activate listing]
    G --> H[Listing becomes eligible for external sync]
    H --> I[Channel order sync can map inbound orders by listing]
    G --> J{Deactivate item or channel?}
    J -->|Yes| K[Listing becomes unsellable]
```

## Scenario Patterns

- **Marketplace assortment setup**: A merchandising user creates a channel for a marketplace and lists selected items with marketplace-specific identifiers
- **Direct storefront catalog**: A B2C storefront channel lists a subset of the internal assortment while the B2B direct-sales channel lists a different subset
- **Channel-specific pause**: An item remains sellable directly but its marketplace listing is paused because margin or service-level conditions changed
- **Inactive item protection**: An item is set inactive internally, and all active listings tied to that item become non-sellable for new channel exposure
- **External identifier mapping**: A listing stores the external SKU or listing ID required for inbound order normalization and outbound status sync
- **Fulfillment-policy distinction**: One channel requires only shippable items from a specific company or site, and listings record the operational rule without moving warehouse logic into the listing itself
- **Re-list after correction**: A listing is paused because required content or price configuration is missing, then reactivated once the issue is fixed
- **Catalog split by company**: Two companies sell the same item family on different channels, and listing ownership stays isolated per company
- **Future content extension**: Channel-specific titles, descriptions, or images may later extend the listing without forcing those fields into the core product model

## Test Cases

- Creating a channel with valid company and channel type should succeed
- Creating a listing must require a valid ACTIVE item and an ACTIVE channel
- A listing must not be activated unless required internal and external identifiers are present
- Duplicate external listing identifiers on the same channel should be rejected
- Inactive channels must not accept newly activated listings
- Inactive items must not remain actively sellable through newly activated listings
- A listing should be isolated by company and must not point to a channel owned by another company
- Deactivating a channel should prevent its listings from being used for new channel order intake
- A listing may be paused and resumed without losing its historical identifiers and audit trail
- A listing should preserve the internal item reference needed for channel-order mapping
- If listing publication depends on channel-specific price configuration, missing required price linkage should block activation
- Only authorized sales or commerce users should be able to create, activate, pause, or retire channels and listings
- Listing changes must remain auditable, including publish, pause, identifier change, and retirement actions
- A listing used by historical channel orders must remain referenceable even after it is no longer actively sellable
- Channel and listing names should be unique according to company policy where operational ambiguity would otherwise occur

## Reference Links

- [Shopify product and publication concepts](https://shopify.dev/docs/apps/build/online-store/product-publishing)
- [Amazon marketplace listing concepts](https://developer-docs.amazon.com/sp-api/)
- [Odoo website and marketplace connector concepts](https://www.odoo.com/documentation/19.0)
