4. Developing the APIs

This guide will walk through the end to end requirements and flow to develop the APIs required to facilitate the transaction between consumer and provider.

Do you need assistance in building the buyer or seller apps? Go through ONDC reference buyer and seller apps source code to help you get started.

ONDC reference Buyer APP:

ONDC reference Seller APP:

ONDC API contracts map business requirements for various use case scenarios to a set of attribute keys in different APIs and ensures interoperability, between a buyer app & seller app, as follows:

• by defining the set of attribute keys that need to be exchanged to establish a handshake between the buyer app & seller app;

• clearly defining the single source of truth for each attribute key and thereby establishing mutability & immutability of these keys on behalf of the participants at each end of the transaction;

1. Retail

Retail Domains live in ONDC:

ONDC APIs is built as an extension to Beckn protocol and closely follows the standards of Open API.

Refer to the complete API specs and try the APIs in swagger hub:

Please refer our API contract to understand the attributes usage and retail specific use cases implemented. These API contracts will help you understand the single source of truth for each attribute key and thereby establishing mutability & immutability of these keys on behalf of the participants at each end of the transaction.

Retail B2C transaction contract between Retail Buyer and Seller:

There is a new version released for retail, which is currently being developed by the existing network participants in staging and pre-prod environment. The new version (v1.2.0) released includes Variants, customization, Add-ons, cross-categories, offers and much more. All the new network participants are expected to develop on the newer version v1.2.0.

1. Logistics

Refer to the logistics API contract to understand the attributes usage and retail specific use cases implemented. These API contracts will help you understand the single source of truth for each attribute key and thereby establishing mutability & immutability of these keys on behalf of the participants at each end of the transaction.

There is a new version released for Logistics, which is currently being developed by the existing network participants in staging and pre-prod environment. All the new network participants are expected to develop on the newer version v1.2.0.

Logistics transaction contract between Logistics Provider and Consumer:

1. B2B

Please refer our API contract to understand the attributes usage and retail specific use cases implemented. These API contracts will help you understand the single source of truth for each attribute key and thereby establishing mutability & immutability of these keys on behalf of the participants at each end of the transaction.

1. Gift Card

The API contract here elaborates the process flows for buying gift cards on the network across four phases of order processing flow of discovery of gift cards available on the network, order placement, fulfillment of the order and post fulfillment requirements.

1. Mobility

ONDC mobility & travel aims to build a nationwide multi-modal network that provides seamless experiences, supports growth & innovation by,

• bringing together a diverse set of mobility, travel & transportation players who can engage with the open network on their own terms

• fostering collaboration, sharing & new models

• facilitating responsive policy by bringing onboard decision making authorities

In the mobility space, the intent is to enable seamless and truly multimodal transit options by bringing in diverse inventory onboard at scale that will serve the country’s population.

This would be possible in the mobility domain by making sure all mobility apps in the network are built in such a way as to enable them to communicate with each other in the same language.

1. Financial Services

ONDC financial services aims to build a nationwide multi-modal network that provides seamless experiences, supports growth & innovation by

• bringing together a diverse set of financial services players who can engage with the open network on their own terms

• fostering collaboration, sharing & new models

• facilitating responsive policy by bringing onboard decision making authorities

In the financial service space, the intent is to enable seamless and truly interoperable service options by bringing in diverse inventory onboard at scale that will serve the country’s population. This would be possible in the financial service domain by making sure all financial services apps in the network are built in such a way as to enable them to communicate with each other in the same language.

The Issue & Grievance Management (IGM) for ONDC is a mechanism via which issues between users of the network are resolved. The IGM flow developed acts as a facilitator to resolve issues, grievances and disputes between a Complainant and a Respondent in a manner that ensures transparency, fairness and data security to the parties. The framework is built on the interactions of Network Participants (NPs) for unique transactions including logistics services by Logistics Service Provider (LSP) procured over the network. This implies that a complainant shall be raising an issue for a particular transaction on the network which may involve buyer app, seller app, logistics service provider app or any other participants for a given transaction.

Try the APIs on swagger hub:

Refer to the IGM MVP API Contract here:

Refer to IGM API contract here:

The objective is to design Reconciliation and Settlement framework for NPs, providing a framework for the participants to settle funds against transactions to respective parties and create an audit trail of transactions. Following are the enumerated design principles for reconciliation and settlement framework:

1. Enable seamless settlement of funds collected by participants

2. Non-repudiable information dissemination all through network entities

3. Maintaining Audit trail to ensure evidence security 

4. Defining standards of message communication for transparency, efficiency and machine readability of Information

5. Building trust through safeguarding fund flow for a transaction through well defined triggers for money withdrawal from Nodal Like account

6. Ensuring non-repudiability through digital signatures and payload authentication

7. Seamless integration using protocol with all stakeholders including settlement agency, reconciliation service providers and participants

Try the APIs on swagger hub:

Refer to RSF API contract here:

The ONDC Network Rating framework is to enable the collection & collation of the various ratings from a Buyer and then transmit them to the Seller Application(s). Buyer Apps will collect, collate and send the raw ratings and Seller App(s) will store the raw ratings. An aggregated score, as calculated by the Network Score Ledger shall be transmitted to whoever wants to consume the data (e.g. reporting agencies, scoring agencies, badging agencies etc.). Seller Applications will also send out the scores to the Buyer Applications as and when they receive a search request as part of the product/ service catalog shared by the Seller Application.

The serviceability construct will allow a buyer app to display catalogs, for only those stores, that can fulfill orders for a buyer, at a specific time, at their location.

Please go through the serviceability construct here

City-State codes are defined here:

The objective is to propose process flows for Cancellation, Return & Replacement. Cancellation, Return & Replacement can be processed by Buyer & Seller Apps, using existing protocol APIs. The detailed process flows and sequence diagrams are defined below.

This note proposes detailed process flows for the following:

• Cancellation - for the full order or for part of an order, i.e. some of the items in an order;

• Return - for one or more items in an order. A part return will be defined as return of one or more items in an order but not return of all items in the order. A full return will be defined as the return of all items in the order.

• Replacement - for one or more items in an order. A part replacement will be defined as replacement of one or more items in an order but not replacement of all items in the order. A full replacement will be defined as the replacement of all items in the order. Note that a replacement can also be handled by part or full return of the order and creating a new order with the items that are being partly or fully replaced.

Please go through the complete flow here:

Error Codes