Venly API
Search
K

Offer states

This page describes how to check the Offer state: how to know when an offer is sold, etc.

Context

The domain of Offer looks like this:
Offer domain
Offer
  • This is the Offer that is put on sale, it can be an AUCTION or SALE.
  • The Offer can be
    • for one non-fungible item; OR
    • for one or more fungible items.
      • Such a multi-item offer can be bought multiple times (by the same person, or by different persons)
Fulfillment
  • This represents the BUYING or CANCELING of one item of the offer.
  • A Fulfillment can have the following types:
    • REIMBURSEMENT: an Offer was canceled and the item is returned to the seller
    • PURCHASE: an item in the Offer was bought and the item is send to the buyer
    • TERMINATION: the offer was terminated by a Market Admin
  • Because of the multi-item offers, an Offer can be linked with multiple Fulfillments (it can be bought multiple times)
The Offer - Fulfillment link has the following consequences:
  • To know the state of the Offer , an aggregation needs to be done on the state of the different Fulfillments (if there are multiple):
    • For example: for one Offer with multiple items, it is possible that there are:
      • 2 Fulfillments of type PURCHASE
      • 3 Fulfillments of type REIMBURSEMENT
  • If you want to show an aggregated state to an end-user, you will need to decide on how to visually represent this scenario.

States

Offer

Offer states
State
Description
NEW
The Offer is created, waiting for an approval for the in-custody transaction.
INITIATING_OFFER
The item is taken into custody. Waiting for finality on the blockchain.
WAITING_FOR_ASSOCIATION
HEDERA specific: a token association is needed, before the item can be taken into custody.
READY
The item is taken into custody. The Offer is ready to be purchased.
CLOSED
All the items in the Offer are either reimbursed or purchased. The Fulfillment details need to be checked.
REFUSED / ERROR
Something went wrong in the in-custody blockchain flow.
TERMINATED
A Market Admin terminated the offer

Fulfillment

State
Description
QUEUED
The fulfillment is waiting to be processed (item is being sent back to the seller or to the buyer)
PROCESSING
Item is being sent to buyer (in case of a PURCHASE) or back to seller (in case of a REIMBURSEMENT)
COMPLETED
The item has arrived at the seller or buyer.
ERROR
A blockchain error occurred.
WAITING_FOR_ASSOCIATION
HEDERA specific: the receiver of the item needs to create a token association, before the item can be received.

State Aggregation

As mentioned, to know the true state of an offer (e.g. to know if it is sold or not), the state of the underlying Fulfillments have to be taken into account. To do this, two methods can be used:
  • Call GET /fulfillments for the Offer and check the Fulfillment states individually.
  • Use the amountPurchased , amountReimbursed or amountTerminated values on Offer
    • These represent the respective underlying Fulfillment states.
For example, our own Marketplace-UI uses the following logic:
Rule
Offer State shown to the user
Future / Current or Past Listing
Offer.state = NEW || INITIATING_OFFER || WAITING_FOR_ASSOCIATION
INITIALISING
Current if startDate <= today
Future if startDate > today
Offer.state = REFUSED || ERROR
REFUSED
Past
Offer.state = READY
ACTIVE
Current if startDate <= today
Future if startDate > today
Offer.state = CLOSED && amountPurchased = 0
CANCELED
Past
Offer.state = CLOSED && amountPurchased > 0 && (amountReimbursed + amountTerminated ) = 0
SOLD
Past
Offer.state = CLOSED && amountPurchased > 0 && (amountReimbursed + amountTerminated ) > 0
PARTIALLY SOLD
Past