Listing Lifecycle Spec

Purpose

This document defines the client-facing listing lifecycle and visibility model.

Clients need to handle two dimensions:

workflow state
visibility state

These are separate on purpose.

---

Workflow States

draft
in_review
active
sold
archived

Meaning:

draft

- work in progress

in_review

- waiting for approval or review

active

- live operational listing

sold

- no longer available for sale

archived

- retained but off the active selling flow

---

Visibility States

private
unlisted
public

Meaning:

private

- not publicly accessible

unlisted

- direct-link access without normal browse visibility

public

- normal marketplace browse and listing-detail visibility

---

Default Direction

new listings start as draft + private
activated listings normally become active + public
unlisted is a manual choice, not the default

---

Client Rules

do not collapse workflow and visibility into one UI field
only active listings should be treated as normal publicly discoverable inventory
raw state values are API logic values, not always final display copy
when the API provides matching label fields, use those labels in UI

---

Common Valid Combinations

draft + private
in_review + private
active + private
active + unlisted
active + public
sold + public
archived + private

Clients should not assume every theoretical state combination is valid.

---

Seller Availability Actions

Common seller-facing actions map to lifecycle combinations:

Unlist

- active + unlisted

Hide completely

- active + private

Delete listing

- retained removal, not destructive deletion - archived + private

Restore privately