How to Add COD + Shiprocket Fulfillment to Medusa v2 for India

Cash on delivery creates a fundamentally different order lifecycle. There is no payment at checkout — the customer promises to pay when the package arrives. Your store ships product on trust, eats both forward and return shipping costs when the customer refuses delivery, and waits days for the courier to remit collected cash. Every Indian e-commerce operator knows this, but Medusa's payment architecture assumes payment happens before fulfillment. I am Manoj, commerce and ERP implementation lead at Mith Tech in Bengaluru, and wiring Indian fulfillment logistics into headless commerce stacks is what we do every week.

Why COD cannot be an afterthought

If you have built an Indian e-commerce store and skipped COD, your conversion rate is artificially suppressed. COD is not about customers who lack online payment access — UPI penetration is high. COD is about trust. A customer buying from a brand they have never heard of, on a website they found through Instagram ads, will choose COD to protect themselves from scams and mismatched product quality.

The industry data is consistent: COD accounts for roughly 60–65% of orders in fashion/apparel, 40–50% in electronics, and 25–35% in beauty and personal care. Tier 1 city rates are lower (25–35%) because repeat customers build trust. Tier 2 and Tier 3 rates are higher (45–65%) because brand awareness is lower.

The operational cost is also consistent: RTO rates for COD orders are 25–30% nationally, climbing to 40% in Tier 3 cities. Each RTO costs you both forward and return shipping — typically ₹60–160 per order depending on weight, zone, and courier. The RTO Cost Calculator below lets you model this for your order volume.

The COD order lifecycle — different from prepaid

A prepaid order follows a straightforward path: customer pays → store fulfils → courier delivers. COD inverts this. The store fulfils on trust, the courier collects cash, the courier remits cash to Shiprocket, and Shiprocket remits to your bank account. Your payment is "captured" days after the customer receives the product.

The simulator above shows the key divergence: after "delivered", the payment in Medusa is still awaiting. It moves to captured only after Shiprocket's settlement cycle (T+2 to T+8 depending on the courier). Your reconciliation process needs to account for this gap — you have shipped product but not received payment, and the settlement is not instantaneous.

The cost of RTO

Every COD order that gets refused at the doorstep costs you forward shipping, return shipping, product handling, and opportunity cost (inventory was locked while the order was in transit). The RTO Cost Calculator models this for your business:

If the calculator shows shipping costs eating more than 8–10% of your revenue, consider these mitigations:

1. OTP-verified COD. Send an OTP to the customer's phone before confirming a COD order. This reduces fake orders by 30–40%.
2. COD with advance. Collect ₹50–100 via UPI at checkout, refundable against the COD amount. Filters out low-intent orders.
3. Pincode-level COD blocking. Track RTO rates by pincode. Disable COD for pincodes with >40% RTO rate.
4. COD to prepaid conversion. After order confirmation, send a WhatsApp message with a prepaid payment link offering a ₹50 discount. 15–25% of customers convert.

Building the COD + Shiprocket stack

The implementation has four files: the COD payment provider module, the Shiprocket fulfillment module, the tracking webhook route, and the module registration in medusa-config.ts.

// src/modules/cod/service.ts
import {
  AbstractPaymentProvider,
  PaymentSessionStatus,
} from "@medusajs/framework/utils"

class CodPaymentProvider extends AbstractPaymentProvider {
  static identifier = "cod"

  async initiatePayment(input: {
    amount: number
    currency_code: string
    context: Record<string, unknown>
  }) {
    // COD: no payment is collected at checkout
    // Create a session with status "pending"
    return {
      id: `cod_${Date.now()}`,
      data: {
        method: "cash_on_delivery",
        amount: input.amount,
        currency: input.currency_code,
      },
    }
  }

  async getPaymentStatus(): Promise<PaymentSessionStatus> {
    // COD payments are always "pending" until
    // delivery agent collects cash
    return PaymentSessionStatus.AUTHORIZED
  }

  async authorizePayment() {
    // Auto-authorize — the "payment" is the promise to pay
    return {
      status: PaymentSessionStatus.AUTHORIZED,
      data: { authorized_at: new Date().toISOString() },
    }
  }

  async capturePayment(paymentData: Record<string, unknown>) {
    // Called when COD cash is remitted to your bank
    return {
      ...paymentData,
      captured_at: new Date().toISOString(),
    }
  }

  async refundPayment() {
    // COD refunds are manual (bank transfer to customer)
    return { status: "refunded" }
  }

  async cancelPayment() {
    return { status: "cancelled" }
  }
}

export default CodPaymentProvider

What to know before you commit

Shiprocket API authentication uses email/password. There is no OAuth or API key — you store your Shiprocket account credentials in environment variables. The token expires after 24 hours, so your fulfillment module must handle re-authentication. The code recipe handles this with a lazy token fetch.

Draft orders bypass stock checks in some configurations (GitHub #14106). If you use draft orders for COD (creating the order before the customer confirms), verify that inventory is decremented at order creation, not at fulfillment.

COD amount handling. Shiprocket needs the order total in rupees, not paise. Medusa stores amounts in the smallest currency unit (paise for INR). Divide by 100 when sending to Shiprocket, or your COD collection will be 100× too high.

Courier selection matters. Shiprocket's auto-assign picks the cheapest courier by default. For COD, reliability matters more than cost — a failed delivery attempt on a COD order is a near-certain RTO. Override the auto-selection for high-value COD orders to use premium couriers (Delhivery, Blue Dart) with better first-attempt delivery rates.

COD is operationally harder than prepaid — the payment comes after shipping, RTO eats margins, and reconciliation is a weekly chore. But in India, skipping COD means losing more than half your addressable market. The order flow simulator and RTO calculator above show the exact lifecycle and cost structure. If the numbers work for your margins, the code recipes give you a working COD + Shiprocket stack for Medusa v2 in an afternoon.