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:

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

Configuration

1. Register Module & Plugin in Copy to clipboardmedusa-config.ts

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

1234567891011121314151617181920
const modules = [
  // ... other modules
  {
    resolve: "@medusajs/medusa/fulfillment",
    options: {
      providers: [
        {
          resolve: "@sam-ael/medusa-plugin-shiprocket",
          id: "shiprocket",
          options: {
            email: process.env.SHIPROCKET_EMAIL,
            password: process.env.SHIPROCKET_PASSWORD,
            pickup_location: process.env.SHIPROCKET_PICKUP_LOCATION,
          },
        },
      ],
    },
  },
]

2. Environment Variables

Define the required parameters in your Copy to clipboard.env file:

123456789
SHIPROCKET_EMAIL=your_email@example.com
SHIPROCKET_PASSWORD=your_password
SHIPROCKET_PICKUP_LOCATION=Primary
SHIPROCKET_WEBHOOK_TOKEN=your_webhook_token_string

# Optional configurations
SHIPROCKET_DELIVERY_PREFERENCE=FAST # 'FAST' or 'CHEAP'
SHIPROCKET_API_TIMEOUT_MS=15000
SHIPROCKET_WEBHOOK_PAYLOAD_RETENTION_DAYS=30

Webhooks

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

Method Endpoint Description Copy to clipboardPOST Copy to clipboard/hooks/fulfillment/delivery-updates 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: Copy to clipboardhttps://yourmedusadomain.com/hooks/fulfillment/delivery-updates

You must set a custom header:

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