Integration Module 2.0 for Medusa is outRead the announcement
Shiprocket logo

Shiprocket

Shiprocket India fulfillment and live rates provider for Medusa v2.

npm install @sam-ael/medusa-plugin-shiprocket
Category
Built by
Regions
Service
Version
0.2.1
Last updated
5 months ago
Monthly downloads
Loading downloads

@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


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.

MethodEndpointDescription
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

  1. Ensure your environment variables are configured with valid sandbox or live Shiprocket API credentials.
  2. In the Medusa Admin panel, create a fulfillment using the Shiprocket provider for a test order.
  3. Verify that the order appears on the Shiprocket panel, gets an AWB assigned, and displays the tracking widget on the Order Details page.
  4. Manually hit the POST endpoint to force synchronization, or simulate a webhook update by posting to with the required authorization header.