Shiprocket
Shiprocket India fulfillment and live rates provider for Medusa v2.
@sam-ael/medusa-plugin-shiprocket
A production-ready Shiprocket integration for Medusa v2. This plugin automates end-to-end fulfillment, providing order syncing, courier assignment, delivery estimation, manifest generation, tracking, and returns management.
Medusa Website | Medusa Repository
Features
- Admin UI Widget: Custom dashboard on the Order Details page displaying tracking timelines, download links for Manifests/Labels/Invoices, and actions to Cancel Fulfillment or Schedule/Reschedule Pickups.
- Automated Order Syncing: Pushes Medusa fulfillments to Shiprocket and automatically retrieves and assigns AWBs (tracking numbers).
- Smart Pickup Scheduling: Automatically schedules courier pickups for shipments immediately after AWB assignment.
- Dynamic Payment Mapping: Maps Medusa payment statuses to Shiprocket's COD (Cash on Delivery) or Prepaid models.
- Return Management: Automates return orders by calculating return dimensions to prevent carrier discrepancy fees.
- Delivery Estimates: Provides accurate Expected Delivery Dates (EDD) and courier serviceability at checkout.
- Real-Time Scan Syncing: Synchronizes tracking events with Medusa administration states via incoming webhooks.
Prerequisites
- Node.js v18 or greater
- A Medusa v2 backend
- An active Shiprocket merchant account with configured pickup locations
Installation
Run the following command to install the plugin in your Medusa project:
Configuration
1. Register Module & Plugin in
Add both the fulfillment provider module and the admin plugin configurations:
2. Environment Variables
Define the required parameters in your file:
Webhooks
This plugin exposes an inbound webhook endpoint to receive real-time shipment status updates from Shiprocket.
| Method | Endpoint | Description |
|---|---|---|
| Webhook receiver for Shiprocket scan and delivery events. |
Webhook Authentication
To authorize Shiprocket webhooks, you must configure a webhook on your Shiprocket dashboard pointing to:
You must set a custom header:
- Header Key:
- Header Value: Must match the string defined in on your Medusa backend.
Webhook Security & Idempotency
- Timing Protection: Employs constant-time verification against timing attacks when comparing tokens.
- Idempotency Guard: Deduplicates events based on to prevent reprocessing identical scan updates.
Test the Plugin
- Ensure your environment variables are configured with valid sandbox or live Shiprocket API credentials.
- In the Medusa Admin panel, create a fulfillment using the Shiprocket provider for a test order.
- Verify that the order appears on the Shiprocket panel, gets an AWB assigned, and displays the tracking widget on the Order Details page.
- Manually hit the POST endpoint to force synchronization, or simulate a webhook update by posting to with the required authorization header.

