You have Medusa v2 running with Razorpay, and prepaid orders flow through. Then a customer asks: "Do you have cash on delivery?" In Indian ecommerce COD is not a legacy method; for many stores it is a large share of orders. Medusa v2 has no Shiprocket fulfilment module, and its only built-in option for unpaid orders is a generic manual payment provider. The community Hemann55/medusa-fulfillment-shiprocket plugin targets Medusa v1. This guide builds a COD payment provider, a Shiprocket fulfilment module that pushes orders to Shiprocket's API, and the webhook pipeline that keeps delivery status and returns in sync.
Cash on delivery creates a different order lifecycle. There is no payment at checkout; the customer promises to pay when the package arrives. You ship on trust, pay forward and return shipping when the customer refuses delivery, and wait for the collected cash to be remitted. Medusa's payment architecture assumes payment comes before fulfilment. I lead commerce and ERP work at MithTech, a team of Frappe specialists in Bengaluru, and wiring Indian logistics into Medusa stores is part of that work.
Why can't COD be an afterthought?
If you sell in India and skipped COD, you are turning away customers who would have bought. COD is not mainly about people without online payment; UPI is widely used. It is about trust. A customer buying from a brand they have never heard of, on a site they found through an Instagram ad, chooses COD to protect themselves against scams and products that don't match the photos.
The share varies a lot by category, city and how well customers know the brand, so use your own order data rather than an industry average. The cost side is just as specific: every refused parcel is forward plus return shipping on your courier's rates, plus handling. The RTO Cost Calculator below lets you model that for your volume.
How is the COD order lifecycle different from prepaid?
A prepaid order runs: customer pays, store ships, courier delivers. COD reverses it. You ship on trust, the courier collects cash, the cash comes back through Shiprocket to your bank, and only then is the payment "captured", days after the customer has the product.
Interactive
COD Order Flow Simulator
Click through each stage to see what happens on the Medusa side and the Shiprocket side — from checkout through delivery, cash collection, and the RTO path when a customer refuses.
The simulator shows the gap: after "delivered", the payment in Medusa is still awaiting. It moves to captured only when the remittance arrives, on the cycle in your Shiprocket agreement. Your reconciliation has to cover that gap: product shipped, money not yet received.
What does RTO cost?
Every COD parcel refused at the door costs forward shipping, return shipping, handling, and the stock that was tied up in transit. The calculator models it on your numbers:
Calculator
RTO Cost Calculator
Enter your monthly COD order volume, average order value, and expected RTO rate to see the financial impact of COD returns on your margins.
If returns are eating into your margin, these are the usual levers. Measure each one on your own orders before and after:
- OTP-verified COD. Send an OTP to the customer's phone before confirming a COD order, to filter out fake and careless orders.
- COD with a small advance. Collect a small amount by UPI at checkout, adjusted against the COD amount. It filters out low-intent orders.
- Pincode-level COD blocking. Track RTO rates by pincode and switch COD off where returns are high.
- Nudge to prepaid. After the order is confirmed, send a WhatsApp or SMS message with a prepaid payment link and a small discount.
How do you build the COD + Shiprocket stack?
The build has four files: the COD payment provider, the Shiprocket fulfilment module, the tracking webhook route and the registration in medusa-config.ts.
Code recipe
COD + Shiprocket Recipe
Four-tab code recipe covering the COD payment provider, Shiprocket fulfillment service, tracking webhook handler, and medusa-config.ts registration. Copy each file into your Medusa v2 project.
0 of 6 steps done
Tick a step’s number when it is done; the ticks stay on this device.
Create the COD payment provider module
Create src/modules/cod/service.ts extending AbstractPaymentProvider. The difference from a card provider: initiatePayment creates a session without collecting anything, and authorizePayment authorises because COD "authorisation" is the customer's promise to pay. capturePayment runs manually, or from a scheduled job, when the COD amount is remitted. Medusa's built-in manual provider (pp_system_default) could stand in, but it approves every payment and has no COD rules, so keep it off live regions.
Create the Shiprocket fulfilment module
Create src/modules/shiprocket/service.ts extending AbstractFulfillmentProviderService. It logs in to Shiprocket's API, creates orders with payment_method: "COD", and returns the AWB number for tracking. Store awb_code and courier_name in the fulfilment metadata.
Register both modules
Add the COD and Shiprocket modules to medusa-config.ts. The COD module takes no options; it talks to no outside service. The Shiprocket module takes the API user's email and password and your pickup_location from environment variables.
Build the tracking webhook
Create src/api/hooks/shiprocket/route.ts. Shiprocket sends shipment status updates to your webhook; map each status (shipped, out for delivery, delivered, cancelled, RTO initiated, RTO delivered) to the matching Medusa fulfilment and order state, using the status codes in Shiprocket's current API documentation. Make the tracking webhook the source of truth for delivery, rather than Medusa's order.completed event (GitHub #10611).
Handle the RTO path
When an RTO status arrives, cancel the order in Medusa, restock the inventory and log the shipping cost. The restock matters: without it, your available stock drops for good with every return. Pass location_id explicitly so stock goes back to the right place (GitHub #10658).
Test the full lifecycle
Create a test COD order and check it appears in Shiprocket with payment_method: COD. Call your webhook with a delivered status and confirm the fulfilment shows "delivered" while the payment stays "awaiting" (collected, not yet remitted). Simulate the remittance by capturing the payment by hand. Then test the RTO path with an RTO-delivered status and check the stock comes back.
What to know before you commit
Shiprocket API login uses an API user. You create an API user in Shiprocket's settings with its own email and password, separate from your panel login, and exchange them for a token. Shiprocket's help centre says the token is valid for 240 hours (10 days) (Shiprocket API helpsheet, checked 12 October 2026). The recipe fetches the token once and caches it, so add a refresh: renew before it expires, and log in again on a 401.
Draft orders and stock. If you create COD orders as draft orders first, check how your Medusa version reserves stock for them; draft-order stock handling has open issues (GitHub #14106). Stock should be reserved when the order is created, not at fulfilment.
COD amount in rupees. Shiprocket expects the order total in rupees. If your integration works with paise, convert before sending, or the COD amount the courier collects will be 100 times too high.
Courier choice matters more for COD. Shiprocket's auto-assignment can pick the cheapest courier. On a COD order a failed delivery attempt often ends as a return, so for high-value COD orders choose couriers by their delivery record on your pincodes, not by price alone.
| Payment timing | After delivery, on the remittance cycle | At checkout |
| Return exposure | Refusal at the door is common | Lower — the customer has paid |
| Shipping cost exposure | Forward + return on every RTO | Forward, plus customer returns |
| Customer trust needed | Low — pay after seeing the product | Higher — pay before shipping |
| Cash flow | Ship before you are paid | Paid before you ship |
| Reconciliation | Courier remittances against orders | Gateway settlements against orders |
COD vs prepaid: the operational trade-offs for Indian e-commerce
At a glance
| What to know | |
|---|---|
| Payment side | A COD provider on AbstractPaymentProvider: authorise at checkout, capture on remittance |
| Fulfilment side | A Shiprocket provider on AbstractFulfillmentProviderService; store AWB and courier |
| Source of truth | Shiprocket's tracking webhook, not order.completed |
| Returns | Cancel, restock with an explicit location_id, log the shipping write-off |
| Amounts | Shiprocket takes rupees; Medusa may hold paise |
| Auth | Shiprocket API user; token valid 240 hours per Shiprocket (checked 12 October 2026) |
Common questions about COD and Shiprocket
How do I add COD (cash on delivery) to Medusa v2?
Build a payment provider module extending AbstractPaymentProvider. initiatePayment creates a session without collecting payment, authorizePayment authorises, and capturePayment runs when the courier's collected cash is remitted. Register it in medusa-config.ts. Medusa's built-in manual provider can mark orders paid without a gateway, but it approves everything and has no COD rules.
How do I integrate Shiprocket with Medusa v2?
Build a fulfilment provider module extending AbstractFulfillmentProviderService. Log in with a Shiprocket API user (POST /v1/external/auth/login), create orders with POST /v1/external/orders/create/adhoc, and handle delivery status through Shiprocket's tracking webhook. The community Hemann55/medusa-fulfillment-shiprocket plugin targets Medusa v1.
What is the RTO rate for COD orders in India?
It varies widely by category, city, courier and how well customers know your brand, and published averages rarely match a given store. Measure your own: RTO orders over COD orders shipped, by pincode and by product, over the last few months. That number, not an industry average, is what goes into the RTO Cost Calculator.
How long does Shiprocket COD settlement take?
It depends on your Shiprocket plan and agreement; Shiprocket also offers faster COD remittance as a paid option. Check the remittance cycle and charges in your own Shiprocket account and agreement, and build your cash-flow plan on that.
Does Shiprocket charge for RTO shipments?
Yes. On a returned COD order you typically pay both the forward and the return leg, on the rates in your Shiprocket plan, plus packaging and handling on your side. That is why the RTO rate decides whether COD is profitable for you.
How do I reduce COD RTO rates?
The usual levers are OTP verification before confirming a COD order, a small UPI advance against the COD amount, switching COD off for high-return pincodes, and a post-order prepaid link with a small discount. Build these into your Medusa order workflow, not the payment provider, and measure each on your own orders.
Can I use Medusa's built-in fulfilment for Indian shipping?
Medusa's built-in manual fulfilment provider only marks items as shipped; it does not connect to any courier. For India you need a fulfilment module that talks to Shiprocket, Delhivery or a similar aggregator. Shiprocket is a common choice because one API covers many couriers, with order creation, tracking and COD.
What Medusa version does this guide apply to?
It was written against Medusa 2.18 (released July 2026); on 12 October 2026 the latest release on npm is 2.21.2. AbstractPaymentProvider and AbstractFulfillmentProviderService have kept the same structure across v2. Recheck webhook handling if Medusa changes how API routes parse bodies.
COD is harder to run than prepaid: the money comes after shipping, returns eat margin, and remittances need reconciling. For many Indian stores it is still worth offering. The simulator and calculator above show the lifecycle and the cost on your numbers; if they work for your margins, the recipe gives you a starting COD and Shiprocket stack for Medusa v2.
Comments & ratings
No comments yet. Start a new discussion.
Manoj · Published on 4 August 2026
Worked with us? Leave a Google review