README

PHP SDK for the Shiprocket External API (v1).

Requirements

PHP 8.0 – 8.x (^8.0)
ext-json
Guzzle 7

composer require tims/shiprocket-php-sdk

Authentication

Create an API user in the Shiprocket panel: Settings → API → Configure → Create an API User (not your panel login).

Authenticate with email and password to receive a JWT (valid for 10 days / 240 hours). Send it as Authorization: Bearer {token} on subsequent requests.

use Tims\Shiprocket\ShiprocketClient;

$shiprocket = ShiprocketClient::fromCredentials(
    getenv('SHIPROCKET_EMAIL'),
    getenv('SHIPROCKET_PASSWORD'),
);

Or manage the token yourself:

use Tims\Shiprocket\AccessTokenGenerator;
use Tims\Shiprocket\ApiClient;
use Tims\Shiprocket\ShiprocketClient;

$token = (new AccessTokenGenerator())
    ->credentials($email, $password)
    ->getAccessToken();

$api = new ApiClient();
$api->setAccessToken($token);

$shiprocket = new ShiprocketClient($api);

Quick start

use Tims\Shiprocket\ShiprocketClient;

$sr = ShiprocketClient::fromCredentials($email, $password);

$rates = $sr->couriers()->serviceability([
    'pickup_postcode' => '110030',
    'delivery_postcode' => '122001',
    'weight' => 0.5,
    'cod' => 0,
]);

$order = $sr->orders()->createAdhoc([
    'order_id' => 'ORD-1001',
    'order_date' => date('Y-m-d'),
    'pickup_location' => 'Primary',
    'billing_customer_name' => 'Jane',
    'billing_last_name' => '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' => '9999999999',
    'shipping_is_billing' => true,
    'payment_method' => 'Prepaid',
    'sub_total' => 499,
    'length' => 10,
    'breadth' => 10,
    'height' => 10,
    'weight' => 0.5,
    'order_items' => [
        [
            'name' => 'Widget',
            'sku' => 'W-1',
            'units' => 1,
            'selling_price' => 499,
        ],
    ],
]);

$awb = $sr->couriers()->assignAwb([
    'shipment_id' => $order['shipment_id'],
]);
$sr->couriers()->generatePickup(['shipment_id' => [$order['shipment_id']]]);
$tracking = $sr->couriers()->trackByAwb($awb['response']['data']['awb_code'] ?? '');

Successful responses are decoded JSON arrays. Failed HTTP responses throw Tims\Shiprocket\ApiException.

API groups

Base URL: https://apiv2.shiprocket.in/v1/external

Method	Coverage
`$sr->auth()`	Logout
`$sr->orders()`	Create / update / cancel / address / fulfill / mapping / import / export / invoice / returns
`$sr->couriers()`	Serviceability, courier list, AWB, pickup, label, manifest, track (AWB / shipment / order / bulk)
`$sr->shipments()`	List / show / create forward & return
`$sr->pickup()`	List / add pickup locations
`$sr->products()`	Catalogue + bulk import / sample
`$sr->inventory()`	List / update
`$sr->listings()`	Channel catalog mappings (list / link / import / export)
`$sr->channels()`	Channels, countries, zones, postcode details
`$sr->account()`	Wallet balance, statement, billing discrepancy
`$sr->ndr()`	NDR list / details / action
`$sr->imports()`	Bulk import error / status check
`$sr->international()`	International orders, couriers, manifest, KYC, bank details
`$sr->warehouse()`	Warehouse SRF serviceability (`/v1/warehouse`, not under `/v1/external`)

This mirrors the External API surface on apidocs.shiprocket.in, plus warehouse SRF.

Low-level escape hatch for any path (relative to /v1/external, or host-absolute like /v1/warehouse/...):

$sr->apiClient()->invoke('GET', 'orders', ['page' => 1]);
$sr->apiClient()->invoke('GET', '/v1/warehouse/srf-serviceability', ['postcode' => '110030']);

Webhooks

Tracking webhooks are inbound (Shiprocket POSTs to your URL). Configure them in the panel under Settings → API → Webhooks. This SDK does not register webhook routes; handle the POST in your app (optional x-api-key header). Sense APIs are a separate product and are not part of this client.

Error handling

use Tims\Shiprocket\ApiException;

try {
    $sr->orders()->show(123);
} catch (ApiException $e) {
    $e->getStatusCode();
    $e->getResponseBody();
    $e->getResponseHeaders();
}

Configuration

Constructor / option	Default	Purpose
`ApiClient` `$basePath`	`https://apiv2.shiprocket.in/v1/external`	Override API base
`ApiClient` `$httpClient`	new Guzzle client	Inject custom client (tests, middleware)
`ApiClient` `$guzzleOptions`	`[]`	Extra Guzzle options
`AccessTokenGenerator` `$baseUrl`	`https://apiv2.shiprocket.in`	Override auth host

Laravel

For config, JWT caching, retries, and a facade, use tims/laravel-shiprocket.

License

MIT

tims / shiprocket-php-sdk

Maintainers

Package info

Statistics

Security