These docs are for v2.0. Click to read the latest docs for v3.0.

Offer States

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

🚧

The Market API will be discontinued, in Q3 2024 we will be sunsetting this product

Context

The domain of Offer looks like this:

Offer Model

Offer Model

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 was returned to the seller
    • PURCHASE: an item in the Offer was bought and the item is sent 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

Offer States

StateDescription
NEWThe Offer is created, waiting for approval for the in-custody transaction.
INITIATING_OFFERThe item is taken into custody. Waiting for finality on the blockchain.
WAITING_FOR_ASSOCIATIONHEDERA specific: a token association is needed before the item can be taken into custody.
READYThe item is taken into custody. The Offer is ready to be purchased.
CLOSEDAll the items in the Offer are either reimbursed or purchased. The Fulfillment details need to be checked.
REFUSED / ERRORSomething went wrong in the in-custody blockchain flow.
TERMINATEDA Market Admin terminated the offer

Fulfillment

Fulfillments Flow

Fulfillments Flow

StateDescription
QUEUEDThe fulfillment is waiting to be processed (the item is being sent back to the seller or to the buyer)
PROCESSINGItem is being sent to the buyer (in case of a PURCHASE) or back to the seller (in case of a REIMBURSEMENT)
COMPLETEDThe item has arrived at the seller or buyer.
ERRORA blockchain error occurred.
WAITING_FOR_ASSOCIATIONHEDERA 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 Fulfillment has 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:

RuleOffer State shown to the userFuture / Current or Past Listing
Offer.state = NEW || INITIATING_OFFER || WAITING_FOR_ASSOCIATIONINITIALISING

Current if startDate <= today

Future if startDate > today

Offer.state = REFUSED || ERRORREFUSEDPast
Offer.state = READYACTIVE

Current if startDate <= today

Future if startDate > today

Offer.state = CLOSED
&& amountPurchased = 0
CANCELEDPast
Offer.state = CLOSED
&& amountPurchased > 0
&& (amountReimbursed + amountTerminated ) = 0
SOLDPast
Offer.state = CLOSED
&& amountPurchased > 0
&& (amountReimbursed + amountTerminated ) > 0
PARTIALLY SOLDPast