Shiprocket

@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:

yarn add @sam-ael/medusa-plugin-shiprocket

Configuration

1. Register Module & Plugin in medusa-config.ts

Add both the fulfillment provider module and the admin plugin configurations:

1const modules = [
2  // ... other modules
3  {
4    resolve: "@medusajs/medusa/fulfillment",
5    options: {
6      providers: [
7        {
8          resolve: "@sam-ael/medusa-plugin-shiprocket",
9          id: "shiprocket",
10          options: {
11            email: process.env.SHIPROCKET_EMAIL,
12            password: process.env.SHIPROCKET_PASSWORD,
13            pickup_location: process.env.SHIPROCKET_PICKUP_LOCATION,
14          },
15        },
16      ],
17    },
18  },
19]
20
21const plugins = [
22  // ... other plugins
23  {
24    resolve: "@sam-ael/medusa-plugin-shiprocket",
25    options: {},
26  },
27]

2. Environment Variables

Define the required parameters in your .env file:

1SHIPROCKET_EMAIL=your_email@example.com
2SHIPROCKET_PASSWORD=your_password
3SHIPROCKET_PICKUP_LOCATION=Primary
4SHIPROCKET_WEBHOOK_TOKEN=your_webhook_token_string
5
6# Optional configurations
7SHIPROCKET_DELIVERY_PREFERENCE=FAST # 'FAST' or 'CHEAP'
8SHIPROCKET_API_TIMEOUT_MS=15000
9SHIPROCKET_WEBHOOK_PAYLOAD_RETENTION_DAYS=30

Webhooks

This plugin exposes an inbound webhook endpoint to receive real-time shipment status updates from Shiprocket.

Webhook Authentication

To authorize Shiprocket webhooks, you must configure a webhook on your Shiprocket dashboard pointing to: https://yourmedusadomain.com/hooks/fulfillment/delivery-updates

You must set a custom header:

• Header Key: x-api-key
• Header Value: Must match the string defined in SHIPROCKET_WEBHOOK_TOKEN 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 ${awb}:${current_status_id}:${current_timestamp} 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 /admin/shiprocket/tracking/:awb/sync POST endpoint to force synchronization, or simulate a webhook update by posting to /hooks/fulfillment/delivery-updates with the required authorization header.