ondc-official / ondc-protocol-specs

Open Network for Digital Commerce (ONDC) Open API Specifications. ONDC is an ambitious initiative to democratize digital commerce by creating a decentralized network of buyer apps and seller apps through an interoperable protocol specification.

Open Network for Digital Commerce (ONDC) Protocol Open API Specifications

Latest Release

1.0.0-draft | March 15th 2022

Current Working Draft Version:

1.0.0-draft

Versioning Scheme

Semantic Version Scheme 2.0.0

Releases

ONDC Protocol Specification Version	Beckn Protocol Core Specification Version
1.0.0-draft	0.9.4-draft

ONDC is an ambitious initiative to democratize digital commerce by creating a decentralized network of buyer apps and seller apps through an interoperable protocol specification. ONDC Protocol is maintained by the Open Source Community to create API specifications, schemas and taxonomy for Retail, Logistics and other domains.

Please see documentation for understanding purpose, architecture, and the actual APIs. Participate in the community discussions to leverage ONDC Protocol as well as to contribute towards development of ONDC Protocol by providing ideas, reporting issues, contributing to documentation, and contributing code.

ondc-protocol-specs's Issues

ONDC data encryption policy

Define ONDC data encryption policy:

1. Key exchange - X25519
2. Encryption
3. Data elements to be encrypted

The format of the `id` which is a property of `Item` is invalid.

File path: ONDC-Protocol-Specs/protocol-specifications/core/v0/api/retail-hyperlocal.yaml.
Item is present inside the schemas which inside the components have a property id whose format is #/components/schemas/Item/properties/id, which is the address to the id property only. This is entirely invalid though it does not cause errors on swagger it will throw during open API validation.

Other than that bap_id and bpp_id should be string and their format should not be uri.

Add "Update" to Order.state

Enhance Order.state to add "update". An order can be updated in case of updated fulfillment details (e.g. different address, delivery time slots)

Standard error code for logistics order serviceability

Define standard reason code for logistics order serviceability

[Refund] Add field to specify the refund amount to the buyer

Need to have cancellation_reason_id at ONDC level

We should have cancellation_reason_id defined at global (ONDC) level. As cancellation_reason_id acts on similar lines to that of status codes (few semantic bucket of reasons) which can be collated at ONDC level, this will also help in following:

• BAP need not map the cancellation_reason_id for integration with each new BPP (retail/logistics)
• BAP can avoid an extra API call to fetch cancellation_reason_id (as caching may fail, if BPP modifies the cancellation_reason_id)

cancellation_reason_id can be thought similar to order_status_codes, which work great at ONDC level, independent from all BPP implementations.

Ready to Ship status

When the Retail Seller wants to inform Logistics Provider that the order is ready for pickup, which API will communicate take this proposed payload ?
Seller app needs to differentiate between an order that's ready for delivery vs an order that's being created that is not yet ready. This is actually a common use case, and could be handled either having 2 APIs (/create and /ship API) or having a flag in the order creation API called readyForDelivery and using the edit API for updating this later.
What flag can we use in the order create API /create to indicate whether this order is NOT yet ready for delivery ?
So, what we need is order is immediately ready for delivery - BAP will call /create and that's all order is created but after sometime will be marked as ready for shipping - BAP will call /create followed by /update
What we need is some guideline on how
(a) in /create a seller can indicate the readytoship status - ready or not yet ready
(b) confirmation that this order property will be changed for the order via an /update call .
If I can get sample payloads for these 2, we can go ahead with this use case
This scenario is applicable in logistics-only txn also. There are cases where one might want to create the order in bulk and and only mark them ready for shipping after its made ready
Think of Bluedart customer service end point - they'll create an order with logistics to confirm price and availability and saying delivery is for tomorrow. But they themselves can handover the shipment only after its handed over to them by customer which might be tomorrow morning. an exec will check everything, confirm packaging is tight and scan it to say, its ready now.
As a short term solution, I can think of an informal agreement to have a specific note (via Tag mechanism) only to be used in this type of scenario, and by default one can assume its ready for delivery immediately

and logistics BAP can call update and update this Tag field from false to true to indicate to the logistics BPP. This can be set to false at the time of order's /confirm.
It can be handled by the retail seller to translate the retail order state to logistics order state.
For example:
a food delivery seller can call /update after 15mins of order placement (assuming 15min is the time taken),
a grocery delivery app can mark ready for delivery when, in their picker app, its marked as item picking and packing is complete.

Search API requires geolocation coordinates(Gps as per the schema) of the buyer

The overall transaction flow of customer search for providers detailed in the document states that location of the customer is requested and send to the search API. But the search API schema only has country and city fields under the context. Neither under the context or message there is provision to share the geolocation coordinates(GPS as per the schema) of the customer/buyer.

Having the geolocation coordinates of the buyer and/or buyers delivery location in the search API schema, ( may be under message > intent > descriptor or under context along with buyers country, city and other details) would help BPP fetch all the hyperlocal sellers serving that particular geolocation from the list of all the sellers it will have on its platform. This use case is not limited to hyperlocal retailers but is relevant for other domains as well; for eg. mobility.

Catalog - make fulfillment type mandatory

Requested by paytm

Need to pass Order Item details in /confirm request for cascaded transaction

Reported by Grab:
How Grab will get Item Name, Item Unit Price, Item Wise Total and Item Weight in the confirm request payload? These are mandatory fields for order creation in Grab System.
(Grab should be getting these fields in message.order.items object)

Billing - Tax_number should be mandatory

From phonepe: Billing.tax_number should be mandatory

Need "Convenience Charge" option in @ondc/org/title_type enum

We want to add buyer app commision, seller app commission and ondc commission to a line item in quote. This could be clubbed together in Convenience Charge.

Why do we want to do this?
Grocery.
Small grocery sellers have absolutely thin margins on FCMG products they sell (<2%).
Currently we are adding these commissions to the listed_value such that
value = listed_value+buyer app fee+seller app fee+ ondc fee

Also this needs to be such that - value<=maximum_value
Given that small grocery sellers are generally selling at MRP itself, adding more commission on top will make it go beyond MRP.

To solve this problem - we will send value=listed_value and add the commissions as separate line item inside "Convenience Charge"

Had this discussion with Abhishek earlier and he confirmed that this is fine. Adding this here for tracking purpose.

@BLR-0118

Provide retail order info like retail-order-id while confirming order with Logistics BPP

We need to pass mandatory info like retail order id to Logistics Partner while confirming order. Currently we are just passing fulfilment info like source and destination address (and gps). But delivery agent need to share some order-id (unique identifier) to pick the order.

Currently as a hack we were using field: fulfillment.instructions, but we think it should be stored in a separate field.

"fulfillment": {
                "type": "home-delivery",
                "tracking": false,
                "start": {
                    "location": {
                        "id": "4847-OrderEasy-10002-3012_location",
                        "descriptor": {
                            "name": "Pooja Stores"
                        },
                        "gps": "13.08784,80.27847"
                    },
                    "time": {
                        "range": {
                            "start": "2021-12-30T07:09:30.000Z",
                            "end": "2021-12-30T07:10:30.000Z"
                        }
                    },
                    "instructions": {
                        "name": "pick up instructions",
                        "short_desc": "Provide the order id: <retail_order_id>"
                    },
                    "contact": {
                        "phone": "[phone]",
                        "email": "[email protected]"
                    }
                },
                "end": {
                    "location": {
                        "gps": "12.914028, 77.638698",
                        ...

This is the least info that needs to be passed (retail order id), like we aren't still passing items list to be checked before picking the package, so no check at the source yet

Some fields in "Item" need to clarified in the spec on how they are supposed to be used.

Current version of the spec, includes following fields for "Item", that have no detailed description on how they could be used. There are a set of sample values being made available, but some of them do not make sense and needs to be clarified for all Seller side NPs.

fulfillment_id
location_id
matched
related
recommended

@BLR-0118 pls check,

Drive link not working

In below power point presentation
https://github.com/Open-network-for-digital-commerce/ONDC-Protocol-Specs/blob/master/protocol-specifications/docs/draft/Tech%20Quickstart%20Guide.md, this github link (https://github.com/dhiraj-nsdl/Beckn-API) is not working. (Slide 6)

Invalid Fields are required in the `Item` object and `Price` object.

The intended JSON schema for Item requires the name, symbol, short_desc, long_desc, and images inside the Descriptor object, and currency, maximum_value, and value are needed inside the Price object. But the current schema requires fields with the name like descriptor.name, descriptor.symbol, descriptor.short_desc, descriptor.long_desc, and descriptor.images directly inside the object Item which is completely not intended.

[Cancellation] Enums for cancelled_by

Enums for cancelled_by field of cancellation object ("@ondc/org/cancellation") are required.

Need an error code for retail that corresponds to the error code 60001 in logistics

Similar to different Invalid Signature error code that is available for different domain

Mandate Catalog.provider.exp

The "exp" attribute for a provider needs to be made mandatory so that the provider can specify the expiry limit for their catalog. Need to publish guideline for usage of this attribute

Logistics serviceability & payload

From IndiaPost:
Enhance logistics search intent to support weight

New Item attributes for F&B

These attributes will be required for now for F & B segment. We may need to add more ,if any attribute is missed out later.
"./ondc-returnable"
"./ondc-cancellable"
"./ondc-time_to_ship"

Need to pass provider location in Order details for cascaded transactions

Reported by Grab:
Certain logistics providers need the provider location (seller address field) to create merchant record. While Order has provider.locations.id, the location details are only available within the same domain and not cross-domain. For cross-domain cascaded transaction, this information needs to be passed through.

Attribute required to inform the logistics provider that COD collection will be required by the Logistics Agent during search request.

Which attribute should be used to inform the logistics provider while creating a logistics search request, that COD collection is not required?

Basis the order to be picked up is COD or not, logistics seller may make a decision to respond to on_search. That would avoid cancellations later which is important in F &B

How does Retail BuyerApp indicate to Retail SellerApp that logistics would be handled by RetailBAP?

Currently, BAP can only indicate to BPP Retail that the choice of user it Pickup or Delivery. For 'delivery' type orders, BAP needs to inform BPP that it will identify the logistics provider by itself. There is no provision for SellerApp to know this in the spec today.

Bug: Statutory fields as extended properties in Item Schema will lead to break in interoperability.

Currently the Item schema in the retail-hyperlocal.yaml file has extended properties that has been namespaced by the ./ondc- keyword, specifically, the statutory fields.

The namespaced extensions are to be used only as a last resort when the core specification has undergone thorough stress testing against various use cases and not as a convenience.

All these values are read-only and can be accommodated in the tags property of the Item schema. Below is the description of the Tags schema as per beckn protocol version 0.9.3

Tags:
      description: Describes a tag. This is a simple key-value store which is used to contain extended metadata

This schema allows networks to transmit read-only data along with transaction schema.

All the statutory fields that are in-fact merely for display purposes need to be moved into the Tags schema. As you can see from the definition above, the core specification doesn't impose a mandate on what goes into the Tags schema. It simply mentions that all extended "metadata" can go in there.

The ONDC network policy must contain a document called "Supported Tags" that contains the names of those keys and mandate the all BPPs transmit those keys with their corresponding values. Given that these are only for display purposes, it doesn't break interoperability even if we add new fields. The statutory fields are clearly for display purposed and play no role in creating an order and hence must be moved to Tags.

Below is my proposal.

1. I propose we move the statutory fields in Item.tags.
2. Publish a list of supported tags in a document and link them to the Tags schema definition using the externalDocs attribute in OpenAPI.
3. All the keys in the Tags schema must be percent-encoded (a.k.a URI encoding) by the BPP before publishing and must also be decoded as such by the BAP while rendering

@BLR-0118

[Quotation Price Breakup] Add enum value for discount for field "@ondc/org/title_type"

In 1.0.13 schema, the enum values present for @ondc/org/title_type field of quotation.breakup are:
item, delivery, packing, tax, convenience charge

However, there is no enum supporting discounts price breakup type. An enum value should be introduced for this.

For "Pickup" orders, how does BuyerApp communicate logistics status to SellerApp

If the fulfillment.type=Pickup, and Logistics transaction is complete, then Seller needs to be notified about the completion on tx. Since, BuyerApp is responsible for communciation with Logisitcs provider, it will have the status updated, but how should it now pass it to SellerApp?
Should this happen using /status call?
Is /status call allowed update state, or /update call with specific update_target?

Price should be float/double instead of current string

@BLR-0118
price should be float/double instead of string
https://github.com/Open-network-for-digital-commerce/ONDC-Protocol-Specs/blob/a8be803a306780a1697d2eb7ef6bbbbdbdbcfca6/protocol-specifications/core/v0/api/retail-hyperlocal.yaml#L2498

please help in confirming the same

cc @adityapatil123

Error Handling for common conditions

Just returning the error with message "Item quantity unavailable" is not sufficient for BAP.
In case, there are many items added to the cart, BAP will need to present to the user, which item(s) are low on quantity.

I would like to propose, along with error, BPP will return following in the on_init payload, along with "error" object,

message.order.items (which is an array) and BPP sends back current quantity as per below,

{ "id": "73661421", "quantity": { "count": 0 } },

@BLR-0118 pls review,

How do I test these APIs, Where are they hosted?

I want to test these APIs, but I couldn't find relevant documentation on where they are hosted, How do i test?

Is this like a webhook sort of thing where I subscribe to the endpoints like "on_search" if yes, where do i register these endpoints for my service?

Payment status needs additional state apart from "PAID" and "NOT-PAID" as "PENDING" to tell the payment ACK is awaited.

In ecomm platforms , we will have the status as "Pending" till we obtain the confirmation status on the payment. And if payment failed, we are asked to make the payment again. Similarly , in our case if we return "NOT-PAID" it would mean that payment is not done, while ,it only an ACK that is not been obtained. Can we have the additional state as "Pending" , so that it says the seller app that we are waiting for the payment confirmation ?

Provide support to divide big order into multiple fulfillments

BG info required in context object of search request

new field in context object to describe the source of the request origin specially for the search requests. BAP might initiates search directly or through BG but BPP couldn't know

1. Which entity triggers the request BG / BAP ?
2. if its BG which BG?

similar to bpp_id & bpp_url, bg_id, bg_url fields would be helpful.
Thanks

Seller Serviceability

How does the seller indicate area of servecibality for products sold by him ?
If he’s going to use on network logistics partner then serveciability will be checked as part of cascaded transaction flow.
However, if the seller would like to self fulfill or fulfill through off network logistics partners then his store or products from his store shouldn’t appear in the search by the buyer from the area which is not serviceable by his store

In case of return/cancel in progress for a given item, need fields with item object to specify the status, i.e. cancel_accepted, cancel_in_progress and then mapping it's fulfillment details

Documentation needed for APIs

Can we have documentation of all kind of searches which can be done and expectations from Search API like search by item name, store name, category name, category Id etc. What is the result expected in each of these cases. Is it list of stores/categories/items?

From the use case excel, there are some 11 kind of searches that can be done in buyer app, however, only 2 of them returns items to the user. One is searching by item name and second is searching by item Id.
We are trying to understand how is the category flow would look like?
We are assuming this, user searches for a category name, get many categories from various sellers as search results, then he clicks on any one of that and gets all items belonging to that category?? (Which API would enable this if our understanding is right)
Use case excel says, search by category id would return the category info only. I believe it should return all items for that category

Same is the question for store. Which API takes storeId as input and return full catalog for that store?
As per use case doc, Search by storeID -> returns store information for the clicked store.

Having documentation of the scenarios will help in setting right expectations between buyer app and seller apps. Having another document like use case excel will be really helpful

Support for multiple fulfillments for multiple returns in given return window

Is buyer allowed to initiate multiple returns for a given order? If yes, then there will be multiple fulfillments in this case and order object does not support more than 1 fulfillment.

New order states for Logistics

• shipped
  Logistics partner will have reliable, faster update for shipped state

• rto_init
  Once BAP/BPP(retail) has initiated cancellation, then Logistics BPP can mark the order in rto_init to notify the initiation of reverse journey for forward-order

• rto_delivered
  Once order is delivered back to the source/origin (store) then Logistics BPP can mark the order in rto_delivered to notify the completion of reverse journey for forward-order

Maintaining link between retail & logistics order objects

In a cascaded tx, When logistics provider, updates status from say Active to Shipped -> Delivered, the /on_status is sent back to BAP Logistics, but there is no msg_id that can be mapped back to some tx on the BPP Retail side, how is this supposed to be dealt with in the protocol?
One way to handle this would be to pass the logistics Order txn_id back to the retail Order after confirmation of the logistics order.
the txn id is passed by the BPP-logistics in these status updates. Passing the txn id from BPP-Logistics, via BAP-Logistics, it will avoid maintaining the reverse mapping on BAP-logistics side.

Add error code for logistics not serviceable

From Loadshare:
Add standardized error code for "Logistics not serviceable"

Product Specific Description

In the short and long description of the product, we need to have a template (For eg: Nested json) to explain about product in more detail so that multiple and specific product details should be passed. For example if Sari is the product, the description of it can be "long_desc": {"size": "string", "style_code": "string", "occassion": "string", "fabric" : "string", "colour" : "string"} as the keys will vary based on the product and hence can't be pre-defined in protocol.

[Cancellation] Protocol support for list of cancelled/returned items

Protocol support for list of cancelled/returned items

Currently there is no way to understand the list of cancelled or returned items for an order at a later point in time. Please provide a way to support the same from protocol-level.

Updated Order & Fulfilment States

AS per #5 , 3 new states are added for logistics orders. In addition, logistics order also has a state "Active".
It is not clear, how each of these are mapped to corresponding states for Retail Order?

Secondly, the Hyperlocal specification, currently, indicates following fulfillment states.
Describes how a single product/service will be rendered/fulfilled to the end customer. state can have following values - "Searching-for-Agent", "Assigned-Agent", "En-route-to-drop", "At-pickup-location", "At-drop-location", "Delivered-package", "Cancelled-package", "Returned-package"
It is not clear how Logistics order states are mapped to the fulfillment.state specified above.

[Logistics]

Need a flag to indicate the order amount of the goods being carried. This is generally needed to ensure that the logistics for various reasons including (a) knowing the amount to collect (b) to accept/reject this based on declared goods value (ex: if you want to send an iPhone of 1L, and if the delivery is done via gig workers, you want to ensure its done only via right workers, as we cant take that risk.

I suggest adding something like "@ondc/org/order_value" in the logistics order.
For a cascaded transaction, the retail BPP should put the order value here
For a non-cascaded transaction, the logistics BAP can get this value from user and provide here.

For F & B , images should not be mandatory attribute.

Images are not currently mandatory in F & B segment. If we refer popular industries like Zomato , Swiggy as well. We dont see it is as statutory requirement either.

Support to add refund details in payment object

For scenarios where refund needs to be initiated, how to share the refund status, amount, refund method, etc?

Reg:: items.month_year_of_manufacture_packing_import

1. Grocery vertical packing date is an optional one in our side, but in spec the field is mandatory can we consider making it as optional one. because some items were without packing date how to provide packing date for those.
2. for same item there will be multiple batches, so in such cases how to provide the packing month & year
   @BLR-0118

Cancel - who has initiated

Requested by paytm - in case of unsolicited on_cancel, who has initiated cancel?

Amount in price should be int and in paise for INR

The problem is float comparison.
1.0 != 1.000000001 but with floats passing around without bounded with decimal points, we will run into these problems.

The 2 most popular payment gateway (Strip and Razorpay) use paise/cents instead thus forcing these to be integers. That works wonderfully well.

Another alternative solution if to fix the maximum possible decimal points to 2 (Cashfree does this).
Current unbonded decimal space amount though will lead to trouble in future.

Links below for reference --
https://stripe.com/docs/api/orders_v2/object
https://docs.cashfree.com/reference/createorder
https://razorpay.com/docs/api/orders/

@BLR-0118 @core-wg-admin

Need an attribute for specifiying items contains egg for F & B

Currently we see attributes for specifying if the item is veg or non-veg. While there needs to be an attribute which mentions the item contains egg or not