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: "jane@example.com",
  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: "you@example.com", 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: "you@example.com",
  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

Name		Name	Last commit message	Last commit date
src		src
test		test
.gitignore		.gitignore
LICENSE		LICENSE
LLMS.md		LLMS.md
README.md		README.md
Shiprocket API.postman_collection.json		Shiprocket API.postman_collection.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

shiprocket-node

Install

Quick start

Authentication

Config options

Error handling

API reference

`client.orders`

`client.returns`

`client.shipments`

`client.couriers`

`client.tracking`

`client.labels`

`client.wrapper`

`client.ndr`

`client.pickupLocations`

`client.products`

`client.listings`

`client.channels`

`client.inventory`

`client.countries`

`client.account`

`client.billing`

`client.imports`

`client.international`

Development

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

shiprocket-node

Install

Quick start

Authentication

Config options

Error handling

API reference

client.orders

client.returns

client.shipments

client.couriers

client.tracking

client.labels

client.wrapper

client.ndr

client.pickupLocations

client.products

client.listings

client.channels

client.inventory

client.countries

client.account

client.billing

client.imports

client.international

Development

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`client.orders`

`client.returns`

`client.shipments`

`client.couriers`

`client.tracking`

`client.labels`

`client.wrapper`

`client.ndr`

`client.pickupLocations`

`client.products`

`client.listings`

`client.channels`

`client.inventory`

`client.countries`

`client.account`

`client.billing`

`client.imports`

`client.international`