PRIVATE and UNLISTED Offers

This page describes the different visibility options for Offer

Offer visibility
By default, an Offer is publicly available, this means:
It can be retrieved by the public endpoint GET /offers ; and
It is shown on the Venly Marketplace: https://venly.market/search (and any other marketplace integrating the Venly API).
Users can search for the offer, view the offer, bid on an auction or buy the offer.
This means that any offer that you create through the API, will also be available on the Venly marketplace and all other marketplaces that use our marketplace API (they can retrieve this offer through the GET /offers endpoint).
If you do not want this behaviour (for example, you are creating a closed marketplace), you can change the visibility of the Offer.
Public / Unlisted and Private
The following options are available regarding the visibility of an Offer:
PUBLIC
UNLISTED
PRIVATE
Feature
Technical
PUBLIC
UNLISTED
PRIVATE
Is shown / searchable on the Venly (and other) Marketplaces
Is returned in 
GET /offers
✅ 
❌
❌
Is shown to the owner of the Offer.
Is shown in “My Listings” on the Venly Marketplace
Is returned in 
GET /user/offers
✅
✅
✅
Is shareable through a link
Is returned in the 
GET /offers/{id}
✅
✅
❌✅
(see note)
Can be bought
POST /fulfillments 
is allowed
✅
✅
❌✅
(see note)
Can be bid on
POST /offers/{id}/bid 
is allowed
✅
✅
❌✅
(see note)
(NOTE) Only if the seller of the offer equals, or is a sub-user of, the logged in user (API Client owns the offer)
In summary:
PUBLIC Offers: are for Offers that can be shown / bought on any Marketplace integrating the Venly API
UNLISTED Offers: are for Offers that can be shown / bought by a select audience (they need to know the Offer.id), on any Marketplace integrating the Venly API.
PRIVATE Offers: are Offers that are strictly private to yourself. Only the API client that created the Offer can also request / buy the Offer.
If you are creating a closed marketplace (offers can only be shown / sold on your own marketplace), you should always use the private visibility.
Using the visibility
The visibility of an Offer can be set at creation time of the Offer, or changed later on.
At Offer creation time
Use the visibility parameter in the Offer creation request.
Example:
Request
POST https://api.venly.market/offers
Request Body
{
    "type": "SALE",
    "nft": {
        "tokenId": "2",
        "address": "0x492aef91afb79efaa508debbed7b3e21069d13e3",
        "chain": "ETHEREUM"
    },
    "sellerAddress": "0xdb7c22EA49EF93F753F2ed4c9E1A2589aC6E7690",
    "price": 25,
    "visibility": "PRIVATE"
}
Changing the visibility
PATCH the offer the change its visibility
Request
PATCH https://api.venly.market/offers/69a25826-6bb6-4ab7-a26f-ab8f5f8dcbeb
Request Body
{
    "visibility": "PRIVATE"
}
Retrieving your offers (closed marketplace)
Retrieving only your own offers, can be done with the following call.
Request
GET https://api.venly.market/user/offers 
This returns all the Offers for which you are the SELLER, BUYER or BIDDER. You can filter these offers by using the relation query parameter: 
GET https://api.venly.market/user/offers?relation=SELLER
​

Feature	Technical	PUBLIC	UNLISTED	PRIVATE
Is shown / searchable on the Venly (and other) Marketplaces	Is returned in `GET /offers`	✅	❌	❌
Is shown to the owner of the Offer. Is shown in “My Listings” on the Venly Marketplace	Is returned in `GET /user/offers`	✅	✅	✅
Is shareable through a link	Is returned in the `GET /offers/{id}`	✅	✅	❌✅ (see note)
Can be bought	`POST /fulfillments` is allowed	✅	✅	❌✅ (see note)
Can be bid on	`POST /offers/{id}/bid` is allowed	✅	✅	❌✅ (see note)

How to build an in-app marketplace?

Offer states

Last modified 10mo ago