shiprocket-node

Unofficial Node.js & TypeScript SDK for the Shiprocket API — orders, shipments, tracking, NDR, returns, international shipping, and more.

• Works from plain Node.js (CommonJS or ESM) and TypeScript, with full type definitions bundled.
• Zero runtime dependencies — built on Node's native fetch, FormData, and AbortController (Node 18+).
• Handles authentication for you: pass an email/password and the client logs in and refreshes the token automatically, or supply a pre-generated token.
• Automatically retries once with a fresh token if a request comes back 401.

This is a community-maintained SDK and is not affiliated with or endorsed by Shiprocket.

Using an AI coding agent? See LLMS.md for a dense, copy-paste-accurate reference of every method and payload shape — point your agent at it instead of letting it guess.

Install

npm install shiprocket-node

Requires Node.js >= 18.

Quick start

import { Shiprocket } from "shiprocket-node";

const client = new Shiprocket({
  email: process.env.SHIPROCKET_EMAIL,
  password: process.env.SHIPROCKET_PASSWORD,
});

const order = await client.orders.createAdhoc({
  order_id: "ORDER-1001",
  order_date: "2026-07-04 10:00",
  pickup_location: "Primary",
  billing_customer_name: "Jane Doe",
  billing_address: "221B Baker Street",
  billing_city: "Mumbai",
  billing_pincode: "400001",
  billing_state: "Maharashtra",
  billing_country: "India",
  billing_email: "[email protected]",
  billing_phone: "9876543210",
  shipping_is_billing: true,
  order_items: [
    { name: "T-Shirt", sku: "TSHIRT-BLK-M", units: 1, selling_price: 499 },
  ],
  payment_method: "Prepaid",
  sub_total: 499,
  length: 10,
  breadth: 10,
  height: 2,
  weight: 0.3,
});

console.log(order.shipment_id);

CommonJS works the same way:

const { Shiprocket } = require("shiprocket-node");

const client = new Shiprocket({ token: process.env.SHIPROCKET_TOKEN });
client.tracking.byAwb("AWB123456789").then((res) => console.log(res));

Authentication

Provide either an email/password pair or a pre-generated token when constructing the client:

// Option 1: email/password — the client logs in lazily on the first request
// and re-authenticates automatically roughly every 9.5 days (tokens are valid ~10 days).
const client = new Shiprocket({ email: "[email protected]", password: "..." });

// Option 2: a token you already generated yourself (e.g. via the Shiprocket dashboard
// or another process). It is used as-is and never refreshed automatically.
const client = new Shiprocket({ token: "eyJ0eXAiOiJKV1Q..." });

If a request fails with 401 Unauthorized and you authenticated with email/password, the client automatically forces a re-login and retries the request once.

You can also manage the session manually:

await client.login();  // force a fresh login and return the new token
await client.logout(); // invalidate the session on Shiprocket's side and clear the local cache

Config options

new Shiprocket({
  email: "[email protected]",
  password: "...",
  token: "...",                 // alternative to email/password
  baseUrl: "https://apiv2.shiprocket.in/v1/external",        // override the core API base URL
  serviceabilityBaseUrl: "https://serviceability.shiprocket.in/v1/external", // used only for blocked-pincode endpoints
  timeoutMs: 30_000,             // per-request timeout
  tokenTtlMs: 9.5 * 24 * 60 * 60 * 1000, // how long a fresh token is cached before re-login
});

Error handling

All non-2xx responses throw a ShiprocketApiError (auth failures throw the more specific ShiprocketAuthError, which extends it):

import { ShiprocketApiError } from "shiprocket-node";

try {
  await client.orders.get(12345);
} catch (err) {
  if (err instanceof ShiprocketApiError) {
    console.error(err.status, err.message, err.errors);
  } else {
    throw err;
  }
}

ShiprocketApiError fields: status, code, errors, data (the full parsed response body), url, method.

API reference

Every method returns a Promise resolving to the parsed JSON response. Request/response shapes are fully typed — see the exported interfaces (e.g. CreateAdhocOrderPayload, ListOrdersParams) for details, or rely on your editor's autocomplete.

client.orders

| Method | Description | | --- | --- | | createAdhoc(payload) | Create a new order (adhoc, not tied to a channel). | | createChannelOrder(payload) | Create an order for a specific sales channel. | | updatePickupLocation(payload) | Update the pickup location for one or more orders. | | updateDeliveryAddress(payload) | Update the shipping address on an order. | | update(payload) | Update an existing adhoc order. | | cancel(ids) | Cancel one or more orders by ID. | | addInventory(payload) | Fulfill/adjust inventory for order line items. | | mapUnmappedProducts(payload) | Map unmapped order line items to a master SKU. | | importBulk(file, filename?) | Bulk-import orders from a CSV file (Blob). | | list(params?) | List orders with filtering/pagination. | | get(orderId) | Get a single order by ID. | | export(params?) | Request a CSV export of orders. |

client.returns

| Method | Description | | --- | --- | | create(payload) | Create a return order. | | createExchange(payload) | Create an exchange order. | | update(payload) | Update a return order (e.g. approve/reject/schedule pickup). | | list(params?) | List return orders. |

client.shipments

| Method | Description | | --- | --- | | list(params?) | List shipments with filtering/pagination. | | get(shipmentId) | Get a single shipment by ID. | | cancelByAwbs(awbs) | Cancel one or more shipments by AWB code. |

client.couriers

| Method | Description | | --- | --- | | assignAwb(payload) | Assign an AWB/courier to a shipment. | | list(params?) | List available courier companies for the account. | | checkServiceability(params) | Check courier serviceability & rates between pincodes. | | generatePickup(payload) | Request a courier pickup. | | uploadBlockedPincodes(payload) | Upload a list of pincodes to block for a courier. | | getBlockedPincodes(params?) | List currently blocked pincodes. |

client.tracking

| Method | Description | | --- | --- | | byAwb(awbCode) | Track a shipment by AWB code. | | byAwbs(awbs) | Track multiple shipments by AWB codes at once. | | byShipmentId(shipmentId) | Track a shipment by its Shiprocket shipment ID. | | byOrderId(params) | Track a shipment by order ID. |

client.labels

| Method | Description | | --- | --- | | generateManifest(shipmentIds) | Generate a manifest for shipments. | | printManifest(orderIds) | Print a previously generated manifest. | | generateLabel(shipmentIds) | Generate shipping labels. | | generateInvoice(orderIds) | Generate invoices. |

client.wrapper

Combined create + assign courier + generate label/manifest in a single call.

| Method | Description | | --- | --- | | forward(payload) | Create and ship a forward order in one call. | | return(payload) | Create and ship a return order in one call. |

client.ndr

| Method | Description | | --- | --- | | list(params?) | List shipments with NDR (non-delivery report) status. | | get(awb) | Get NDR details for a shipment by AWB. | | action(awb, payload) | Take an action on an NDR shipment (re-attempt, return to origin, etc.). |

client.pickupLocations

| Method | Description | | --- | --- | | list() | List all pickup locations on the account. | | add(payload) | Add a new pickup location. |

client.products

| Method | Description | | --- | --- | | list(params?) | List products in the catalog. | | get(productId) | Get a single product. | | add(payload) | Add a new product. | | convertToQcProduct(productId, payload) | Convert a product for quality-check (QC) enabled returns. | | importBulk(file, filename?) | Bulk-import products from a CSV file. | | getSampleCsvUrl() | Get the sample CSV template URL for bulk import. |

client.listings

| Method | Description | | --- | --- | | list(params?) | List channel product listings. | | map(payload) | Map a channel listing to a catalog product. | | importCatalogMappings(file, filename?) | Bulk-import catalog mappings from a CSV file. | | exportMapped() | Export mapped listings. | | exportUnmapped() | Export unmapped listings. | | getSampleCsvUrl() | Get the sample CSV template URL. |

client.channels

| Method | Description | | --- | --- | | list() | List sales channels connected to the account. | | create(payload) | Create a custom channel. |

client.inventory

| Method | Description | | --- | --- | | list(params?) | List inventory levels. | | update(productId, payload) | Update inventory for a product. |

client.countries

| Method | Description | | --- | --- | | list() | List countries and their codes. | | getZones(countryId) | Get zones/states for a country. | | getLocalityDetails(params) | Look up locality details (city/state) for a pincode. |

client.account

| Method | Description | | --- | --- | | getWalletBalance() | Get the current wallet balance. | | getStatement(params?) | Get a wallet transaction statement. |

client.billing

| Method | Description | | --- | --- | | getDiscrepancyData() | Get weight/billing discrepancy data. |

client.imports

| Method | Description | | --- | --- | | checkResult(importId) | Check the result/status of a bulk import job. |

client.international

| Method | Description | | --- | --- | | submitKyc(payload) | Submit KYC documents for international shipping. | | addBankDetails(payload) | Add bank details for international payouts. | | createOrder(payload) | Create an international order. | | updateOrder(payload) | Update an international order. | | track(params) | Track an international shipment. | | checkServiceability(params) | Check international courier serviceability. | | assignAwb(payload) | Assign an AWB/courier to an international shipment. | | generateManifest(payload) | Generate a manifest for international shipments. | | forwardShipment(payload) | Create and ship an international forward shipment in one call. |

Development

npm install
npm run build      # compile to dist/ (ESM + CJS + type declarations)
npm run typecheck   # tsc --noEmit
npm test             # run the test suite (node:test + tsx)

License

MIT