ondc-buyer
Skill65 starsChanged 7 months agoMITView on GitHub
Deploy and manage ONDC buyer applications. Set up buyer reference apps with product discovery, cart management, checkout flows, and order tracking. Handle payment integration, delivery tracking, and ONDC protocol compliance for consumer-facing applications.
- Reads credentials
- Installs packages
In this repository22 other files it gives its agents.
- bhagavad-gitaSkill
- cashfreeSkill
- covid-indiaSkill
- gurbaniSkill
- ifsc-apiSkill
- indian-constitutionSkill
- indian-newsSkill
- railradarSkill
- mutual-fundSkill
- namma-yatriSkill
- ondc-sellerSkill
- phonepeSkill
- pincodeSkill
- rapidoSkill
- razorpaySkill
- sarvam-aiSkill
- shiprocketSkill
- thirukkuralSkill
- uber-indiaSkill
- vedic-astrologySkill
- vedic-textsSkill
- zohoSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 11 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 18
Product Discovery: Search and browse products across ONDC network
- Distinctive: line 37
Before using this skill, ensure you have:
- Distinctive: line 235
Create account at https://dashboard.juspay.in
- Distinctive: line 250
Update the payment service to match your gateway's API.
- Very specific: line 271
After deployment, visit https://yourdomain.com/bugzilla/admin
- Very specific: line 275
Add BUGZILLA_API_KEY to environment variables
- Distinctive: line 297
Verify protocol layer is running
- Distinctive: line 298
Check ONDC registry connectivity
- Distinctive: line 300
Ensure catalog service is indexed
- Distinctive: line 307
Test with Juspay sandbox first
- Distinctive: line 312
Check GPS coordinate format
- Very specific: line 313
Verify /track endpoint responses
- Very specific: line 319
Never commit .env files or credentials to version control
- Distinctive: line 320
Use HTTPS for all endpoints
- Distinctive: line 377
Use this skill when you need to:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ONDC Buyer Skill
This skill helps you deploy and manage ONDC (Open Network for Digital Commerce) buyer applications. ONDC is India's digital commerce network enabling buyers to discover and purchase from sellers across multiple platforms.
What This Skill Does
- Deploy ONDC Buyer Apps: Set up the complete buyer reference application
- Product Discovery: Search and browse products across ONDC network
- Shopping Cart: Manage cart, apply customizations, and handle variants
- Checkout Flow: Handle select, init, confirm, and payment flows
- Order Tracking: Track orders in real-time with GPS/URL-based tracking
- Returns & Cancellations: Process returns, cancellations, and refunds
- IGM Support: File and track issues/complaints with sellers
Architecture Overview
The ONDC Buyer App uses microservice architecture:
- biap-client-node-js: Node.js backend API layer
- biap-app-ui-front: React web application (served via nginx)
- py-ondc-protocol: Python protocol layer for ONDC communication
- biap-igm-node-js: Node.js IGM service for issue management
- biap-bugzilla-service: Bugzilla integration for ticket management
- catalog-service: Catalog indexing and search service
Prerequisites
Before using this skill, ensure you have:
- Docker & Docker Compose installed
- Git with submodule support
- Domain name or ngrok for public endpoint
- Required service accounts:
- Firebase (authentication)
- Juspay or other payment gateway
- Map My India (location services)
- MongoDB (included in docker-compose)
- ONDC Registry Access (for production deployment)
Quick Start
1. Clone and Initialize
cd /home/workspace
git clone https://github.com/ONDC-Official/ondc-sdk.git ondc-buyer-app
cd ondc-buyer-app
git submodule init
git submodule update2. Generate Cryptographic Keys
bun /home/workspace/Skills/ondc-buyer/scripts/generate-keys.tsThis creates signing and encryption keys required for ONDC registration.
3. Configure Environment
bun /home/workspace/Skills/ondc-buyer/scripts/setup-env.ts \
--domain "https://buyerapp.example.com" \
--firebase-key "YOUR_KEY" \
--juspay-merchant-id "MERCHANT_ID" \
--mmi-client-id "MMI_CLIENT"4. Deploy Locally (Development)
cd /home/workspace/ondc-buyer-app
docker-compose -f docker-compose-for-local.yaml --env-file .env-local up -dAccess the app at http://localhost (or your configured domain).
5. Register with ONDC
Once deployed, use the registration helper:
bun /home/workspace/Skills/ondc-buyer/scripts/register.ts \
--subscriber-url "https://buyerapp.example.com" \
--signing-key "path/to/signing_public.pem" \
--crypto-key "path/to/crypto_public.pem"Common Operations
Check Application Status
bun /home/workspace/Skills/ondc-buyer/scripts/check-status.tsShows the status of all services (client, frontend, protocol, IGM, catalog).
Search Products
# Search across ONDC network
bun /home/workspace/Skills/ondc-buyer/scripts/search.ts --query "smartphones" --city "Bangalore"
# Search by category
bun /home/workspace/Skills/ondc-buyer/scripts/search.ts --category "Grocery" --location "110001"
# Get provider details
bun /home/workspace/Skills/ondc-buyer/scripts/search.ts --provider-id "PROVIDER123"Manage Orders
# List user orders
bun /home/workspace/Skills/ondc-buyer/scripts/view-orders.ts --user-id "USER123" --limit 10
# Get order details and tracking
bun /home/workspace/Skills/ondc-buyer/scripts/view-orders.ts --order-id "ORDER456"
# Track order status
bun /home/workspace/Skills/ondc-buyer/scripts/track-order.ts --order-id "ORDER456"Handle Returns & Cancellations
# Initiate cancellation
bun /home/workspace/Skills/ondc-buyer/scripts/cancel-order.ts --order-id "ORDER789" --reason "Changed mind"
# Request return
bun /home/workspace/Skills/ondc-buyer/scripts/return-order.ts --order-id "ORDER789" --items "ITEM1,ITEM2"
# Check cancellation status
bun /home/workspace/Skills/ondc-buyer/scripts/check-cancellation.ts --order-id "ORDER789"Manage IGM Issues
# List user issues
bun /home/workspace/Skills/ondc-buyer/scripts/manage-igm.ts --action list --user-id "USER123"
# File new issue
bun /home/workspace/Skills/ondc-buyer/scripts/manage-igm.ts --action create \
--order-id "ORDER123" \
--type "PRODUCT_QUALITY" \
--description "Product damaged"
# Track issue status
bun /home/workspace/Skills/ondc-buyer/scripts/manage-igm.ts --action track --issue-id "IGM456"Environment Variables
Key environment variables required (store in Settings > Advanced):
# ONDC Registry
BAP_URL="https://buyerapp.example.com"
BAP_ID="buyerapp.example.com"
BAP_PRIVATE_KEY="signing_private_key"
BAP_PUBLIC_KEY="signing_public_key"
BAP_UNIQUE_KEY_ID="unique_key_id_from_registry"
# Firebase Auth
FIREBASE_ADMIN_SERVICE_ACCOUNT="/path/to/firebase-service-account.json"
REACT_APP_FIREBASE_API_KEY="firebase_api_key"
REACT_APP_FIREBASE_AUTH_DOMAIN="buyerapp.example.com"
# Juspay Payment Gateway
JUSPAY_SECRET_KEY_PATH="/path/to/juspay-creds.pem"
JUSPAY_BASE_URL="https://sandbox.juspay.in"
JUSPAY_MERCHANT_ID="merchant_id"
JUSPAY_API_KEY="access_key"
JUSPAY_WEBHOOK_USERNAME="webhook_user"
JUSPAY_WEBHOOK_PASSWORD="webhook_pass"
# Web App Payment Config
REACT_APP_JUSTPAY_CLIENT_AND_MERCHANT_KEY="merchant_id"
REACT_APP_MERCHANT_KEY_ID="merchant_id"
REACT_APP_PAYMENT_SDK_ENV="sandbox"
REACT_APP_PAYMENT_SERVICE_URL="https://api.juspay.in"
# Map My India
MMI_CLIENT_SECRET="mmi_secret"
MMI_CLIENT_ID="mmi_client_id"
MMI_ADVANCE_API_KEY="mmi_api_key"
# MongoDB
MONGO_DB_URL="mongodb://mongo:27017/ondc"Feature Support Matrix
The ONDC Buyer App implements ONDC Retail v1.2 specification:
| Feature | Status |
| Incremental catalog refresh | ✅ Available |
| Full catalog refresh | ✅ Available |
| Product search & discovery | ✅ Available |
| Shopping cart management | ✅ Available |
| Checkout flow (select/init/confirm) | ✅ Available |
| Payment integration (Juspay) | ✅ Available |
| Order tracking (GPS-based) | ✅ Available |
| Live order tracking | ✅ Available |
| Customization (selection) | ✅ Available |
| Variants support | ✅ Available |
| Return with liquidation | ✅ Available |
| Cancellation flows | ✅ Available |
| RTO (Return to Origin) | ✅ Available |
| IGM issue management | ✅ Available |
| Order history | ✅ Available |
| Multi-store cart | ✅ Available |
| Address management | ✅ Available |
| Customization (free text) | 📅 Future scope |
| Subscription orders | 📅 Future scope |
| Offers & discounts | 📅 Future scope |
Payment Gateway Integration
Juspay Setup
- Create account at https://dashboard.juspay.in
- Generate API credentials from console
- Download merchant certificate (.pem file)
- Configure environment variables
- Set up webhook endpoints for payment callbacks
Alternative Payment Gateways
To integrate other payment gateways (Razorpay, Paytm, etc.):
# Modify payment service integration
vim /home/workspace/ondc-buyer-app/biap-client-node-js/src/payment/Update the payment service to match your gateway's API.
Map My India Integration
MMI provides:
- Address autocomplete
- PIN code lookup
- State/city detection
- Geocoding (lat/long from address)
Required APIs:
https://outpost.mapmyindia.com/api- Authenticationhttps://atlas.mapmyindia.com/api/places/search/json- Searchhttps://explore.mappls.com- Explore placeshttps://apis.mapmyindia.com/advancedmaps/v1- Advanced mappinghttps://atlas.mappls.com/api/places/geocode- Geocoding
Bugzilla Setup (Optional)
For IGM ticket management:
- After deployment, visit
https://yourdomain.com/bugzilla/admin - Login with username
adminand passwordpassword - Configure SMTP settings for email notifications
- Generate API key from dashboard
- Add
BUGZILLA_API_KEYto environment variables - Restart bugzilla container
Note: Bugzilla is optional but recommended for full IGM functionality.
Troubleshooting
Services Not Starting
# Check logs
docker logs ondc-buyer-client
docker logs ondc-buyer-frontend
docker logs ondc-buyer-protocol
docker logs ondc-catalog-service
# Restart specific service
docker-compose restart biap-client-node-jsSearch Not Working
- Verify protocol layer is running
- Check ONDC registry connectivity
- Review
/searchrequest/response logs - Ensure catalog service is indexed
Payment Failures
- Verify Juspay credentials
- Check webhook configuration
- Review payment service logs
- Test with Juspay sandbox first
Order Tracking Issues
- Confirm seller provides tracking URLs
- Check GPS coordinate format
- Verify
/trackendpoint responses - Review order status updates
Security Notes
- Store all secrets in Zo's Settings > Advanced
- Never commit
.envfiles or credentials to version control - Use HTTPS for all endpoints
- Implement rate limiting on public APIs
- Validate payment webhook signatures
- Sanitize user inputs
- Regular security audits
Deployment Options
Local Development (with ngrok)
# Install ngrok
brew install --cask ngrok
# Start tunnel
ngrok http 5555
# Use ngrok URL in BAP_URL and PROTOCOL_BASE_URLProduction Deployment (with SSL)
# Use docker-compose with SSL
docker-compose -f docker-compose.yaml --env-file .env-prod up -d
# Initialize Let's Encrypt
./init-letsencrypt.shAnsible Deployment
cd deploying_ansible
ansible-playbook -i ansible_hosts buyer-app-install-for-ssl.yaml
ansible-playbook -i ansible_hosts buyer-app-run.yamlReferences
See the references/ folder for:
- ONDC API Contract v1.2 documentation
- Buyer app user manual
- Feature implementation guide
- Integration requirements
- Payment gateway setup guides
Support
- ONDC Documentation: https://docs.ondc.org
- Buyer App Repo: https://github.com/ONDC-Official/ondc-sdk
- ONDC Slack: https://witsinnovationlab.slack.com/archives/C0280AR5CUQ
- Registry Form: https://forms.gle/registrationform
- Juspay Docs: https://developer.juspay.in
When to Use This Skill
Use this skill when you need to:
- Deploy an ONDC-compliant buyer application
- Build a consumer-facing shopping experience on ONDC
- Integrate payment gateways with ONDC flows
- Implement product search and discovery
- Handle end-to-end order management
- Process returns and cancellations
- File and track customer issues (IGM)
- Scale buyer operations across India
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

