B2B - Buyer Proposed Price | Bid Price

[tanyamadaan]

Context

In agricultural markets, such as Agri Mandis, farmers list their produce for sale, and traders participate in bidding for the products. Traders, acting as buyers, submit bid prices. The bidding process involves multiple traders proposing their bid prices, competing to secure the purchase. The highest bidder ultimately wins the trade and proceeds to either pick up the produce from the farmer's location or gets delivered based on the agreed fulfillment terms.

Problem

Proposed Solution

Considering that same attributes should not be modified by both provider and consumer, proposing to create a new attribute for buyer provided bid - message.order.bid same as message.order.quote.

/select:

"message": {
  "order": {
    "bid": {
      "price": {
        "currency": "string",
        "value": "string"
      },
      "breakup": [
        {
          "title": "string",
          "price": {
            "currency": "string",
            "value": "string"
          },
          "item": {
            "id": "string",
            "descriptor": {...},
            "quantity": {
              "selected": {
                "count": "string",
                "measure": {
                  "unit": "string",
                  "value": "string"
                }
              },
            },
            "price": {
              "currency": "string",
              "value": "string"
            }
          }
        }
      ],
      "ttl": "string"
    }
  }
}

@ravi-prakash-v @nitinmish

[tanyamadaan]

Minutes of Meeting (MOM) - Discussion Highlights:

1. Order.Bid Definition:

   • We agreed to define message.order.bid as a new object, similar to message.order.quote.
   • order.bid is the responsibility of the buyer/buyer apps (BAP) and can only be updated by BAP.
   • order.quote is the responsibility of the seller/seller apps (BPP) and can only be updated by BPP.

2. Usage of Bid Object:

   • The bid object may be utilized by BAP to send the total proposed price - order.bid.price or proposed price for each item selected - order.bid.breakup.0.price mapped to item.id

"bid": {
  "price": {
    "currency": "INR",
    "value": "1500"
  },
  "breakup": [
    {
      "title": "Potato lot",
      "price": {
        "currency": "INR",
        "value": "1500"
      },
      "item": {
        "id": "I1",
        "quantity": {
          "selected": {
            "measure": {
              "unit": "quintal",
              "value": "1"
            },
            "count": "10"
          }
        },
        "price": {
          "currency": "INR",
          "value": "1500"
        }
      }
    }
  ]
}

3. Confirmation and Status Update:

   • Placement of a bid is equivalent to placing an order.
   • To propose a bid, /confirm API to be used.
   • Use of /on_status to provide the new item.price.minimum_value based on bids received within a specified timeframe (e.g., every 5 mins).

4. Negotiation Flows:

   • For negotiation flows, the buyer's proposed bid - order.bid is sent as part of /select.
   • The seller sends an updated quote - order.quote based on the buyer's proposed price in /on_select.
   • Multiple rounds of negotiation can occur through repeated /select - /on_select.
   • Once the buyer agrees with the provided quotation, the buyer proceeds with the initialization of the order through the /init API.

[tanyamadaan]

Based on the discussion, we intend to use /confirm API to place bid and hence for better understanding of the complete auction flow, trying to map high level auction flow with beckn APIs.

Use Case: Agri Mandi

• In Agri Mandi use case, farmers list their produce, and traders bid for the product.
• Traders, being the buyers, provide a bid price on the unit quantity listed as per catalog/ lot.
• The highest bidder wins the trade, and the transaction concludes based on agreed fulfillment terms (Self-pickup or delivery)

Proposed Flow:

1. /on_search - Lot Creation
   • Farmer creates a lot with detailed produce information, base price, and available quantity.
   • This has to be broadcasted to all buyer apps subscribed to agri domain.

    "message": {
      "catalog": {
        "providers": [
          {
            "id": "P1",
            "items": [
              {
                "id": "I1",
                "descriptor": {...},
                "price": {
                  "currency": "INR",
                  "minimum_value": "1000.00"
                },
                "quantity": {
                  "unitized": {
                    "measure": {
                      "unit": "quintal",
                      "value": "1"
                    }
                  },
                  "available": {
                    "count": "10"
                  }
                }}
            ] } ]}}

2. /select

   • Buyer selects the lot for bidding. While selecting the lot for bidding, buyer may provide:
   • specific license (if required for bidding)
   • may choose a payment type from available options
   • Choose fulfillment type from available fulfillment options

3. /on_select

   • Seller app sends EMD (Earnest Money Deposit) requirements and performs a serviceability check based on buyer's GPS coordinates ( if the fulfillment type is delivery ).

4. /init

   • Buyer is ready to place a bid and provides billing details.

5. /on_init

   • Trade terms (if any) are shared with the buyer.

6. /confirm

   • Buyer places a bid, confirms EMD payment status, and agrees to trade terms.

"message": {
  "order": {
    "id": "O1",
    "state": "Created",
    "provider": {
      "id": "P1"
    },
    "items": [
      {
        "id": "I1",
        "fulfillment_ids": [
          "F1"
        ],
        "quantity": {
          "selected": {
            "count": 10
          }
        }
      }
    ],
    "billing": { ... },
    "fulfillments": [
      {
        "id": "F1",
        "type": "self_pickup",
        "stops": [ .... ]
      }
    ],
    "bid": {
      "price": {
        "currency": "INR",
        "value": "1100"
      },
      "breakup": [
        {
          "title": "Potato Lot",
          "price": {
            "currency": "INR",
            "value": "1100"
          },
          "item": {
            "id": "I1",
            "quantity": {
              "selected": {
                "measure": {
                  "unit": "quintal",
                  "value": "1"
                },
                "count": "10"
              }
            },
            "price": {
              "currency": "INR",
              "value": "1100"
            }
          }
        }
      ]
    },
    "payments": [
      {
        "params": {
          "currency": "INR",
          "amount": "1100",
          "transaction_id": "xxxxxxxxxxxxxx",
        },
        "status": "Paid",
        "type": "PRE-FULFILLMENT",
        "collected_by": "BAP"
      }
    ],
    "created_at": "2024-01-12T09:30:00.000Z"
  }
}

7. /on_confirm - Bid Submission

   • Bid submission with the order status still pending (order confirmation/rejection to come post bidding window).

8. /on_update (unsolicited)

   • Sent by BPP to update the new minimum price for each transaction_id (for which /confirm was received) at regular intervals (e.g., every 5 mins). [Instead of /on_status, we may use /on_update as the item object is getting updated. Share your thoughts.]

9. /update

   • If buyer wishes to update the bid price, buyer can update the bid price using the same message.order.bid object.

10. Multiple update and on_update calls may occur for the each transaction_id.

11. Final /on_update (Post Auction Window)

• For Highest bidder - BPP sends order state as confirmed and updated quote object.

{
  "message": {
    "order": {
      "id": "O1",
      "state": "Accepted",
      "provider": {
        "id": "P1"
      },
      "items": [
        {
          "id": "I1",
          "fulfillment_ids": [
            "F1"
          ],
          "quantity": {
            "selected": {
              "count": 200
            }
          }
        }
      ],
      "billing": { ... },
      "fulfillments": [
        {
          "id": "F1",
          "state": {
            "descriptor": {
              "code": "Pending"
            }
          },
          "type": "self_pickup",
          "stops": [ ... ]
        }
      ],
      "quote": {
        "price": {
          "currency": "INR",
          "value": "1200"
        },
        "breakup": [
          {
            "title": "Potato Lot",
            "price": {
              "currency": "INR",
              "value": "1100"
            },
            "item": {
              "id": "I1",
              "quantity": {
                "selected": {
                  "measure": {
                    "unit": "quintal",
                    "value": "1"
                  },
                  "count": 10
                }
              }
            }
          },
          {
            "title": "Convenience Fee",
            "price": {
              "currency": "INR",
              "value": "100"
            }
          }
        ],
        "ttl": "P1D"
      },
      "payments": [
        {
          "params": {
            "currency": "INR",
            "amount": "1200"
          },
          "status": "PAID",
          "uri": "https://snp.com/pg",
          "type": "PRE-FULFILLMENT"
        }
      ],
      "created_at": "2024-01-12T09:30:00.000Z",
      "updated_at": "2024-01-12T12:30:00.000Z"
    }
  }
}

And multiple /on_update to all other bidders with error object defining - bid did not match highest bid.

{
  "context": { ... },
  "message": {
    "order": {
      "id": "O1",
      "state": "Accepted",
      "provider": {
        "id": "P1"
      },
      "items": [
        {
          "id": "I1"
        }
      ],
      "quote": {
        "price": {
          "currency": "INR",
          "value": "0"
        },
        "breakup": [
          {
            "title": "Potato Lot",
            "price": {
              "currency": "INR",
              "value": "0"
            },
            "item": {
              "id": "I1",
              "quantity": {
                "available": {
                  "measure": {
                    "unit": "quintal",
                    "value": "1"
                  },
                  "count": 0
                }
              }
            }
          }
        ]
      },
      "created_at": "2024-01-12T09:30:00.000Z",
      "updated_at": "2024-01-12T12:30:00.000Z"
    }
  },
  "error": {
    "code": "xxxxx",
    "message": "Proposed bid did not match highest bid"
  }
}

Open Points:

• In the context of item.quantity, attributes like available, maximum, and minimum can only be updated by BPP. On the other hand, item.quantity.selected is updated by BAP only.
  Similarly in item.price, we currently have attributes like offered_value, maximum_value, and minimum_value. To enhance flexibility, we can also introduce item.price.proposed_value apart from order.bid, which aligns with item.quantity.selected. This new attribute is intended to be updated only by the BAP, similar to item.quantity.selected.
• The bidding process focuses on the item's base price; however, the final quote may include additional components as part of breakup, for ex. delivery charges, packaging charges, convenience charges ( Mandi charges or any platform charges or any other convenience charges ). Should these additional breakup components to be updated in order.quote.breakup through /on_update during order confirmation? Which means my total order quote - order.quote.price will change and might not match order.bid.price. Which also means that the /confirm - /on-confirm does not become the final digital contract.

Kindly provide your thoughts, suggestions, or any alternative approaches regarding the considerations in the overall flow.

@ravi-prakash-v @nitinmish @pramodkvarma @sjthnrk @venkatramanm @92shreyansh

[venkatramanm]

My thoughts:

• Lot creation.
  • Publishing to Baps is not a scaleable idea in the long run. May be it is time to introduce the Search provider feature (Check draft branch , BECKN-011 Draft document) and publish the inventory/lot to this entity. all baps/bg can use the information from here. May be, we could have webhooks like new_item_available on baps which may be published by search providers to interested baps. Infact the current pull-based incremental search being used by ondc is not a scalable solution in the long run as baps and bpps may be added to network in tandom and it would not be possible to do one on one catalog publishing.
  • Flow can start with search instead of on_search. (The inventory publishing can be like any other item)
• /select, on_select, /init and /on_init usage is fine.
• After this I don't personally prefer to use /confirm & /on_confirm, may be we could use a new pair of optional apis /book and /on_book for communicating deposit amount payments, new quote (min_value) and raising bids.(order status could be 'Pending/Biding Open' as suggested).
• once auction is closed, the seller would send a /on_book with status as "Bid Accepted" to the bap Where (min_value = bid_value). At this point the quote is also updated with other charges.
• Finally the buyer moves forward and would send a /confirm , get an on_confirm and things move as usual.
• All other buyers would be sent /on_book with Status "Bidding Closed" with Error "Lost to a higher Bid". @ravi-prakash-v @tanyamadaan @nitinmish @pramodkvarma @sjthnrk @92shreyansh

[tanya-ondc]

Thank you for sharing your thoughts and insights on the proposed flow. Here are some thoughts around this -

• Lot Creation:

  • We will need separate and detailed discussion around catalog refresh. There is another approach that we were thinking of around this. Will document and share it across for further discussion.
  • Here in Agri Mandi use case, a lot created is a live catalog and will be created at different times by different BPPs or by providers within a BPP. For BAP to promptly receive the available lots open for auction, they would need to keep an event listener live for higher ttl or would need to send search requests at very high frequency (less interval). Hence, was proposing to start the journey from BPP broadcasting the lot open for auction to all BAPs subscribed to Agri domain.

• book/ on_book - I think the flow you have suggested using /book /on_book resembles to what was defined using /update, /on_update APIs. The suggestion is more around implementing new APIs /book /on_book instead of using /confirm and /update.

• The reason of using /confirm /on_confirm was:

  • in auction, bid submission is actually a confirmation of order from buyer side.
  • what if the bid gets selected and buyer does not raise a /confirm request, post auction window closure

What we can also explore is increasing the ttl of /confirm equal to the auction window, which means the /on_confirm is received as soon as the auction window is closed. We can also utilize /on_search to broadcast new min_value, if not /on_update (considering it is tagged to fulfillment phase). I feel we do not need new APIs specifically for auction use case. We can leverage the existing APIs itself. Open for discussion.

[sjthnrk]

Bids are essentially init/on_init as it initialises the terms of your bids at which you are communicating your bid terms. On_init is way to accept or seek nee bids.   Confirm is a natural extension to confirm on a particular unit whose bid has been selected.Not sure why book/on_book is separately required for receiving bids.Also, At ApI layer where beckn operates, we can live with abstractions. What init at ApI later actually means in the experience user journeys - be it a “bid”, an “order” or “a booking” has little to do with how APIs talk to each other at protocol layer.   We had stress tested Init for bidding and multi- negotiation use cases. Ravi can share examples for this. 

[venkatramanm]

idea to keep using init/on_init is workable.
Instead of new api pairs book/on_book. Just that validations for first init and subsequent inits would be different and may not be describable easily in documentation.

Baring that complexity, init on_init seems workable.

[sjthnrk]

Agreed.  But let me break this down into a few distinct points of discussion Firstly there is the care  about: a) case of Use case Documentation versus beckn documentation.  we could be dealing with the expectation of covering every use case possible with beckn in the documentation. b) ease of documenting a use case with beckn. I’m afraid we may be prescriptive on ‘a way’ to implement bidding on beckn. There could be multiple ways that some others can think of. Therefore, are we trying to solve for documentation stand point on bidding by defining new APIs as ‘the way’? Thinking aloud, Like HTTP, we don’t have to document every imagination of the possibilities with GET and POST. Just like how the ecosystem could present applications of GET and POST for myriad of possibilities instead creating Myriad of new APIs. This  is an evolution in engg peer learning that we could all enable.  We could perhaps Immediately document “ a way” not “the way” to implement bidding usecase with existing APIs of beckn.  But with lack of other ways documented, did we solve for documentation ease? Maybe better than nothing but not adequately, and that sufficiency is not a protocol documentation objective. Secondly there is care of what are the larger principles at play: adding new api cannot be made by overlooking Minimalism and universality, for the want of specificity ( “the way” over “ a way”)Beckn is a Multi purpose abstraction, by design.  Its strength, in my view, is its generalisation and universality, all with same set of minimal APIs. We could stress test our thinking really hard on how bidding is different and as to why  it is not just a variant of same DOFP cycle that existing APIs enable, and as to why certain usecase requires a new use case altogether. Else we will end up have a new api for every variant of the same purpose. Thirdly,  is it just about what names we want to give to the same thing?: We confuse APi names themselves for purpose.  What we are calling as “Book” is actually enabled by existing APIs  with different name. Sometimes debate is on deriving meaning from names itself.  And on the Name of API -  many have a view on the proper nkuns, more than the purpose it enables. “Why not “book?”“why not “subscribe”?” , why not “source” etc.   This in my view is an endless debate.  People associate with names differently despite the literal meanings in the dictionary. I don’t think there will be universal consensus. We have some names already, we could just go with them. Names are nothing but  pointer to purpose and its underlying function, and we should not worry about them.   We could discuss if the purpose behind calling anything like Book could be resolved agnostic of what name we give it.   I personally may have a view on GET and POST as names, but that’s what we have :)

[ravi-prakash-v]

Interesting discussiion. My thoughts below.

1. Let us decouple the need for a search provider from the current use case. I agree having a search provider as a new actor in the network is a good idea but let us focus on implementing the bidding use case in the current version of the protocol.
2. I believe we do not need additional endpoints to enable negotiations and auctions. It has been conclusively proven that any transaction between a consumer and a provider is either a Discovery, Ordering, Fulfillment or Post-fulfillment that can be enabled using the 10 actions of beckn protocol.
3. The endpoints are purpose-specific, not form-specific. Meaning every interaction has been assigned a specific purpose which is indisputable. However, it is left to the implementing networks to agree on which sequence of actions can enable a specific use case.
4. An auction can be implemented using the following flow

• Seller declares a set of items available for an auction using on_search. That can be either a category in the catalog, or as a new provider itself. In a typical auction, the auctioneer declares one item at a time which the bidders collectively bid for. Once the item has been sold, the auctioneer moves on to a different item. This is not a standard workflow. Other workflows are possible.
• The buyer uses a confirm call to place the bid with a proof of deposit
• The seller uses an on_confirm call to confirm the placement of the bid
• The seller uses on_status calls to notify the bidders about the ongoing status of the sale. i.e "Going once", "Going twice", "Going thrice", and "Sold! To Mr John Doe for 4000 USD".
• The BPP uses an on_update call to the bidder that wins the bid
• The BPP uses on_cancel to notify the bidders who haven't won the bid

5. Important point to consider - How the auction is discovered may vary. It could be a QR code pointing to a specific search request to a specific BPP. Or it could be a specific category code that the buyer may search by.

[venkatramanm]

@ravi-prakash-v, your solution works.

I am convinced, we don't need any new endpoint.

Update with update target works. Personally I think update api is heavily overloaded and implementations can be simplified by breaking this api by more granular purpose. Like cancel_line... .but this is a discussion for a later time.

Some question:

1.how do bidders raise the bid(update?),
2.is the current highest bid value sent on on_status?

[venkatramanm]

@tanya-ondc Confirm is not final digital contract, even today. There are updates and cancels and price mod possible.

So this may not be an open issue any more than its already. .

Infact thinking on the lines of it being open issue was why i wanted to close the bids before confirming and introduced the book api possibility which would be binding as confirm in this domain. But after seeing Ravi and Sujit's points, it believe we can do without it.

We can negotiate post confirm with out loss of generality.

[sjthnrk]

Absolutely, Ravi and Venky. And we can technically do this other ways too Even with either select and init pairs followed by ./confirm. Or ./confirm ./on_confirm followed by on_update as Ravi suggested. Latter approach looks better as thats where generally market builds the formal order ledger, as it helps governance functions like accounting and observability. Bid is an order “placed/received, not yet accepted”

[tanyamadaan]

Thanks for everyone's inputs here.

Absolutely agree, as proposed earlier as well, we definitely do not need new endpoints specifically for auction use case.

@venkatramanm

• Had proposed to have bid placement in /confirm and bid submitted/ received (not yet accepted) through /on_confirm.
• New bid price to be proposed through /update.
• The only difference I see in the suggestion from Ravi is around updating the new base price through /on_status, which I had suggested through /on_update. As in Mandi use case, the bidding closes only post auction window and hence, if bidding window is for example open for 2 hours, there would be multiple bids submitted and in open bidding the buyer apps needs to know the new highest bid (new min_price for the lot). As this is an update to the item, hence was suggesting /on_update here. Open for discussion.
• The open point was across the change in the total quote value, due to additional charges like logistics, commission, etc. which will get added and communicated post bid acceptance window, through /on_update. And as we are thinking of using order.bid, where order.bid.price is equivalent to total price as per order.bid.breakup, just trying to highlight that order.bid.price might not match the order.quote.price, as the bid is happening on the item price and not on the total quote or other breakup line items. The order.bid.breakup.0.price will match the order.quote.breakup.0.price (for specific item.id). Hence, the attributes should clearly define which line item in breakup is being finalized post bidding, and should not lead to different interpretation.

Either the bid for item to be defined like below:

"bid": {
      "price": {
        "currency": "INR",
        "value": "" --> Total quote is not being finalised in bidding, probably not to be sent as well in this use case.
      },
      "breakup": [
        {
          "title": "Potato Lot",
          "price": {
            "currency": "INR",
            "value": "1100" --> Bid price for specific lot - Item.id = I1.
          },
          "item": {
            "id": "I1",
            "quantity": {
              "selected": {
                "measure": {
                  "unit": "quintal",
                  "value": "1"
                },
                "count": "10"
              }
            },
            "price": {
              "currency": "INR",
              "value": "1100"
            }
          }
        }
      ]
    }

Or we have item.price.proposed_value similar to item.quantity.selected to be tagged to BAP, which clearly communicates the bid price only for specific item and not on total quote.

"message": {
  "order": {
    "items": [
      {
        "id": "I1",
        "location_ids": [
          "L1"
        ],
        "fulfillment_ids": [
          "F1"
        ],
        "quantity": {
          "selected": {
            "count": 200
          }
        },
        "price": {
          "currency": "INR",
          "proposed_value": "1100"
        }
      }
    ]
  }
}

[rajaneeshk90]

Thank you all for the engaging conversation and your enthusiastic participation. Your insights and contributions have truly added value to this discussion, adding depth and perspective that enriches our collective understanding.

As we move forward, I kindly request that we divide our current discussion into two separate topics: negotiation and auction. This segregation will enable us to delve deeper into each subject matter, allowing for a more focused and thorough exploration of the intricacies involved in negotiation strategies and auction dynamics.

By addressing these topics separately, we can better understand and analyze the unique challenges and opportunities associated with each method of transaction.

@tanyamadaan, please help us by dividing our current discussion.

Thank you for your understanding, and we look forward to engaging in in-depth discussions.
Rajaneesh

[tanyamadaan]

Have updated this thread to solely focus on bidding process. Will initiate a new thread for negotiation use case.

[rajaneeshk90]

Thanks @tanyamadaan for taking the time out to update the discussion.

[nitinmish]

Let’s broaden the definition of a Bid. We probably may not need addition of a new structure called bid in the spec definition.

Let me decontextualise the bidding process and attempt to articulate a flow:

There is a seller who may offer an item, or a basket of items for inviting interests from prospective buyer. A bid may be solicited as well as unsolicited in nature. Once discovery of such a basket of items or an item is established through search, or an intent of offering a price to an item listed is firmed, through a select framework, a buyer may assert their value. For certain use cases, a case of explicit definition of an item or basket is required tagged to a bidding process.

I think if we simply allow seller a window to open the quote with an additional tag or assertion/approval/rejection/null, a buyer may be able to use the same quote object without introducing new attribute class in protocol.

I am averse to create use case oriented tags in protocol unnecessarily. It breaks the protocol construct and will make specs very verbose and elaborate.

A seeker has an intent for a transaction. Each transaction before its close can go through multiple iterations within same layer of DOFP framework. Bidding is simply an intent aspect of the protocol with placeholders that provide for same attribute globally defined, but locally assigned within an object. A seller may offer an item from their catalog that is bid friendly. A buyer may simple initiate an intent of a quotation. This should not require addition of a new object. Use case oriented object creation is counterintuitive in my opinion.

@ravi-prakash-v @venkatramanm @BLR-0118 @sjthnrk @92shreyansh

[nitinmish]

It is the same construct that will solve for negotiation as well. Each time a proposal for a price/item is raised, an assertion can be declined opening it for negotiation. Each seeker or provider may decide if they want to engage and open a window for negotiation. Bidding may simply be see as open negotiation.

[ravi-prakash-v]

@nitinmish can you post a json exchange of how exactly are you viewing bidding? It'll help all of us align a lot better if we used JSONs instead of verbal text. If you're also articulating flow, maybe a mermaid sequence diagram as well.

[nitinmish]

@AbhiSIITR

[AbhiSIITR]

@nitinmish, the process flow is available here. The draft examples are available here, select draft_agri_bids_and_auction

[nitinmish]

Can you please put in the search/select/init/confirm and other specs here itself? Its a beckn thread and the model will have global implication.

[AbhiSIITR]

All specs covering search/select/init/confirm and other specs are available here, select draft_agri_bids_and_auction.

[rajaneeshk90]

@AbhiSIITR

Thanks for the process flow.

I tried to go through this link you provided. Link directs to a full swagger doc, I am not sure if I was able to narrow down the part where we are placing and updating a bid. If it is possible can you please copy the relevant portion on this thread, it will help all of us to go though it quickly.

Since @nitinmish suggested that we may not need addition of a new structure called bid, I wanted to check the object/fields inside message.order that you are using to update the bid price as an alternative to message.order.bid that @tanya-ondc suggested.