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
  active + private
• Restore to marketplace
  active + public

Public Read Rule

For public client work, use the durable public listing routes and handle workflow and visibility according to the API payload rather than guessing from older compatibility behavior.