discussion #1

[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 or proposed price at each item level.

"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 - Intent to Bid

   • 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"
        },
        "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 the structure of 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.