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
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
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 differentFulfillments(if there are multiple):- For example: for one
Offerwith multiple items, it is possible that there are:- 2 Fulfillments of type PURCHASE
- 3 Fulfillments of type REIMBURSEMENT
- For example: for one
- 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 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
Fulfillments Flow
| State | Description |
|---|---|
| QUEUED | The fulfillment is waiting to be processed (the item is being sent back to the seller or to the buyer) |
| PROCESSING | Item is being sent to the buyer (in case of a PURCHASE) or back to the 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 Fulfillment has to be taken into account. To do this, two methods can be used:
- Call
GET /fulfillmentsfor theOfferand check theFulfillmentstates individually. - Use the
amountPurchased,amountReimbursedoramountTerminatedvalues onOffer- 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 Future if |
Offer.state = REFUSED || ERROR | REFUSED | Past |
Offer.state = READY | ACTIVE | Current if Future if |
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 |
Updated 6 months ago