ONDC Integration for Sellers: A Developer's Primer

The Open Network for Digital Commerce is India's experiment in decoupling buyers and sellers from any single marketplace platform. It's been live for two years, has real volume in some categories, and the protocol is finally stable enough that integrating now isn't a research project. Here's the developer's view.

Key takeaways

• ONDC is a network of independent buyer apps (BAPs) and seller apps (BPPs) that interoperate via a shared Beckn-based protocol.
• As a seller, you integrate as a BPP; your products are then discoverable on every BAP on the network.
• The integration is HTTP-based, asynchronous (callbacks), and uses a defined schema for catalog, search, select, init, confirm, status, track, cancel, update.
• The hard parts are matching the schema, handling async callbacks reliably, and getting onboarded by a network participant.

Why this matters

ONDC volume is real and growing, particularly in groceries, food, and certain B2B categories. For sellers, ONDC is incremental demand. For platforms, ONDC participation is increasingly expected. Engineering ahead of competitors gives you network presence with lower CAC than running paid ads on traditional marketplaces.

The architecture in plain terms

A buyer on a buyer app (let's say Paytm) searches for "atta 5kg". The buyer app sends a search call to the ONDC network. Your seller app (your BPP), registered on the network, receives the search, responds with matching products via an on_search callback. The buyer sees products from many sellers, chooses one, places an order. The order flows back through the network to your BPP. You fulfill it. Status updates flow back asynchronously.

The BAP / BPP roles

• BAP (Buyer App Platform): the consumer-facing app where buyers discover and purchase.
• BPP (Buyer Platform Provider, confusingly named): the seller-side platform. This is what you build or integrate to.
• Gateway: routes between BAPs and BPPs.
• Registry: a discovery layer for who's on the network.

You'll likely operate as a BPP or partner with a Technology Service Provider (TSP) who runs one for you.

The core API flows

The Beckn protocol defines a request/callback pattern. You receive a search POST; you respond async by POSTing an on_search back. Same pattern for select / on_select, init / on_init, confirm / on_confirm, status / on_status, track / on_track, cancel / on_cancel, update / on_update.

Every payload has a signed envelope and a structured body. Catalog format is defined per domain (retail, food, mobility, etc.).

What to build

A Beckn protocol adapter that sits between your existing commerce backend and the ONDC network. It handles authentication, signature verification, schema mapping (your product model ↔ ONDC's catalog schema), and the async callback pattern. Don't build it from scratch unless you have to, a few open-source BPP frameworks (most notably Beckn-ONIX) handle the boilerplate.

Common pitfalls

The first is treating ONDC like a sync REST integration. It's not. Every meaningful action has an async callback you have to handle, log, and reconcile. Build solid queueing.

The second is undertesting on the sandbox. Onboarding has staged tests; some BAPs have additional integration tests. Allocate 3-4 weeks for testing.

The third is schema drift. ONDC catalog schema evolves. Build the mapping layer to be easy to update.

What we recommend

Phase 1: pilot with one or two BAPs and one product category. Phase 2: expand to all relevant categories. Phase 3: optimize (search relevance, pricing, fulfillment SLAs). Plan 8-12 weeks for a working pilot.

FAQs

Is ONDC mandatory? No, but for several categories it's becoming expected.

Does ONDC handle payments? Payment is settled via integrated payment processors (Razorpay, Cashfree, others), ONDC orchestrates, doesn't process.

What about returns and disputes? ONDC has defined flows for both, but operational maturity varies by category.

Can we operate both our own storefront and ONDC? Yes, most sellers do.

Talk to Techpuvi about eCommerce engineering, including ONDC integration.