# RetireListing

## Permission Scope

marketplace

## Overview

RetireListing permanently removes a listing from active sellability while preserving its history for channel-order traceability.

## Business Rules

- DRAFT, ACTIVE, and PAUSED listings may be retired.
- Retiring a listing must preserve historical channel-order references and external identifiers for support lookup.

## Process Flow

```mermaid
flowchart TD
    A[Receive retire request] --> B[Load listing]
    B --> C{Status allows retirement?}
    C -->|No| D[Return INVALID_LISTING_STATUS]
    C -->|Yes| E[Set status to RETIRED]
    E --> F[Return retired listing]
```

## External Dependencies

- None

## Error Scenarios

- **LISTING_NOT_FOUND**: Referenced listing does not exist.
- **INVALID_LISTING_STATUS**: Listing status does not allow this operation

## Test Cases

- retires a draft or active listing
- preserves historical references after retirement
- throws when listing status does not allow retirement
