WORKING

Listings

post/merchant/listings

Create or sync a listing. Upserts on (merchantId, merchantListingRef) — a repeat call with the same ref updates the existing listing rather than creating a duplicate. See docs/api/merchant-integration-guide.md "Sync your listings".

Parameters

optional

Request body

Field	Type	Required
merchantId	string (uuid)	yes
merchantListingRef	string	yes
sellerId	string (uuid)	yes
title	string	yes
category	string	yes
subcategory	string	—
brand	string	—
model	string	—
size	string	—
condition	string	—
year	integer	—
originalPrice	number	yes
currency	string	yes
visibility	PRIVATE \| GLOBAL \| BOTH \| ENTERPRISE	yes
listingType	SALE \| TRADE \| BOTH	yes
deliveryMethod	LOCAL_PICKUP \| SHIPPING \| BOTH	—
preferredSpaceBranchId	string (uuid)	—
merchantItemUrl	string (uri)	—
requestedAmount	number	—
willingToPay	number	—
note	string	—
images	string[]	—
wants	object[]	—

Response (201)

Field	Type	Required
id	string (uuid)	—
merchantId	string,null (uuid)	—
merchantListingRef	stringnull	—
sellerId	string (uuid)	—
title	string	—
category	string	—
subcategory	stringnull	—
brand	stringnull	—
model	stringnull	—
size	stringnull	—
condition	stringnull	—
year	integernull	—
originalPrice	number	—
currency	string	—
visibility	PRIVATE \| GLOBAL \| BOTH \| ENTERPRISE	—
status	ACTIVE \| RESERVED \| SOLD \| UNAVAILABLE \| DELETED	—
listingType	SALE \| TRADE \| BOTH	—
deliveryMethod	LOCAL_PICKUP \| SHIPPING \| BOTH \|	—
preferredSpaceBranchId	string,null (uuid)	—
merchantItemUrl	string,null (uri)	—
requestedAmount	numbernull	—
willingToPay	numbernull	—
note	stringnull	—
images	string[]	—
wants	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
syncedAt	string (date-time)	—
deletedAt	string,null (date-time)	—

put/merchant/listings/{id}

Update a listing by id (partial — only supplied fields change)

Parameters

id	path	required
		optional

Request body

Field	Type	Required
merchantId	string (uuid)	yes
merchantListingRef	string	yes
sellerId	string (uuid)	yes
title	string	yes
category	string	yes
subcategory	string	—
brand	string	—
model	string	—
size	string	—
condition	string	—
year	integer	—
originalPrice	number	yes
currency	string	yes
visibility	PRIVATE \| GLOBAL \| BOTH \| ENTERPRISE	yes
listingType	SALE \| TRADE \| BOTH	yes
deliveryMethod	LOCAL_PICKUP \| SHIPPING \| BOTH	—
preferredSpaceBranchId	string (uuid)	—
merchantItemUrl	string (uri)	—
requestedAmount	number	—
willingToPay	number	—
note	string	—
images	string[]	—
wants	object[]	—

Response (200)

Field	Type	Required
id	string (uuid)	—
merchantId	string,null (uuid)	—
merchantListingRef	stringnull	—
sellerId	string (uuid)	—
title	string	—
category	string	—
subcategory	stringnull	—
brand	stringnull	—
model	stringnull	—
size	stringnull	—
condition	stringnull	—
year	integernull	—
originalPrice	number	—
currency	string	—
visibility	PRIVATE \| GLOBAL \| BOTH \| ENTERPRISE	—
status	ACTIVE \| RESERVED \| SOLD \| UNAVAILABLE \| DELETED	—
listingType	SALE \| TRADE \| BOTH	—
deliveryMethod	LOCAL_PICKUP \| SHIPPING \| BOTH \|	—
preferredSpaceBranchId	string,null (uuid)	—
merchantItemUrl	string,null (uri)	—
requestedAmount	numbernull	—
willingToPay	numbernull	—
note	stringnull	—
images	string[]	—
wants	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
syncedAt	string (date-time)	—
deletedAt	string,null (date-time)	—

delete/merchant/listings/{id}

Soft-delete a listing

Parameters

id	path	required
		optional

post/merchant/listings/{id}/availability

Report an availability change. reservation-service is the primary caller for RESERVED during a trade session; merchants call this directly for SOLD/UNAVAILABLE from their own inventory changes outside of TBBN trades.

Parameters

id	path	required
		optional

Request body

Field	Type	Required
status	ACTIVE \| RESERVED \| SOLD \| UNAVAILABLE	yes

Response (200)

Field	Type	Required
id	string (uuid)	—
merchantId	string,null (uuid)	—
merchantListingRef	stringnull	—
sellerId	string (uuid)	—
title	string	—
category	string	—
subcategory	stringnull	—
brand	stringnull	—
model	stringnull	—
size	stringnull	—
condition	stringnull	—
year	integernull	—
originalPrice	number	—
currency	string	—
visibility	PRIVATE \| GLOBAL \| BOTH \| ENTERPRISE	—
status	ACTIVE \| RESERVED \| SOLD \| UNAVAILABLE \| DELETED	—
listingType	SALE \| TRADE \| BOTH	—
deliveryMethod	LOCAL_PICKUP \| SHIPPING \| BOTH \|	—
preferredSpaceBranchId	string,null (uuid)	—
merchantItemUrl	string,null (uri)	—
requestedAmount	numbernull	—
willingToPay	numbernull	—
note	stringnull	—
images	string[]	—
wants	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
syncedAt	string (date-time)	—
deletedAt	string,null (date-time)	—

put/merchant/listings/{id}/wants

Replace a listing's wants array (full replace, not merge) — see docs/business/glossary.md "Wants"

Parameters

id	path	required
		optional

Request body

Field	Type	Required
wants	object[]	yes

Response (200)

get/v1/listings/{id}/wants

Read a listing's wants array

Parameters

path

required

Response (200)

get/v1/listings/{id}

Get a listing

Parameters

path

required

Response (200)

Field	Type	Required
id	string (uuid)	—
merchantId	string,null (uuid)	—
merchantListingRef	stringnull	—
sellerId	string (uuid)	—
title	string	—
category	string	—
subcategory	stringnull	—
brand	stringnull	—
model	stringnull	—
size	stringnull	—
condition	stringnull	—
year	integernull	—
originalPrice	number	—
currency	string	—
visibility	PRIVATE \| GLOBAL \| BOTH \| ENTERPRISE	—
status	ACTIVE \| RESERVED \| SOLD \| UNAVAILABLE \| DELETED	—
listingType	SALE \| TRADE \| BOTH	—
deliveryMethod	LOCAL_PICKUP \| SHIPPING \| BOTH \|	—
preferredSpaceBranchId	string,null (uuid)	—
merchantItemUrl	string,null (uri)	—
requestedAmount	numbernull	—
willingToPay	numbernull	—
note	stringnull	—
images	string[]	—
wants	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
syncedAt	string (date-time)	—
deletedAt	string,null (date-time)	—

get/v1/listings

Directory-lite listing read across all visibilities the caller is entitled to — full ranked search lives in Search/Matching

Parameters

category	query	optional
merchantId	query	optional
visibility	query	optional
		optional
		optional

Response (200)

Field	Type	Required
data	object[]	—
nextCursor	stringnull	—

post/v1/listings/individual

Self-service individual (non-Merchant) listing (Phase 26) — sellerId is resolved from the caller's own marketplace-member session, never the request body.

Parameters

optional

Request body

Field	Type	Required
title	string	yes
category	string	yes
subcategory	string	—
brand	string	—
model	string	—
size	string	—
condition	string	—
year	integer	—
originalPrice	number	yes
currency	string	yes
listingType	SALE \| TRADE \| BOTH	yes
deliveryMethod	LOCAL_PICKUP \| SHIPPING \| BOTH	—
preferredSpaceBranchId	string (uuid)	—
requestedAmount	number	—
willingToPay	number	—
note	string	—
images	string[]	—
wants	object[]	—

Response (200)

Field	Type	Required
id	string (uuid)	—
merchantId	string,null (uuid)	—
merchantListingRef	stringnull	—
sellerId	string (uuid)	—
title	string	—
category	string	—
subcategory	stringnull	—
brand	stringnull	—
model	stringnull	—
size	stringnull	—
condition	stringnull	—
year	integernull	—
originalPrice	number	—
currency	string	—
visibility	PRIVATE \| GLOBAL \| BOTH \| ENTERPRISE	—
status	ACTIVE \| RESERVED \| SOLD \| UNAVAILABLE \| DELETED	—
listingType	SALE \| TRADE \| BOTH	—
deliveryMethod	LOCAL_PICKUP \| SHIPPING \| BOTH \|	—
preferredSpaceBranchId	string,null (uuid)	—
merchantItemUrl	string,null (uri)	—
requestedAmount	numbernull	—
willingToPay	numbernull	—
note	stringnull	—
images	string[]	—
wants	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
syncedAt	string (date-time)	—
deletedAt	string,null (date-time)	—