README

A production-ready PHP client for the Shipway shipping API.

Requirements

• PHP 8.1+
• Composer

Installation

composer require mimicak/shipway-php-sdk

Authentication

Shipway uses HTTP Basic Auth. Your credentials are:

Quick Start

use MimicAk\ShipwayPhpSdk\Shipway;

$shipway = Shipway::create('you@example.com', 'your-license-key');

Using environment variables

SHIPWAY_USER_EMAIL=you@example.com
SHIPWAY_API_KEY=your-license-key

$shipway = Shipway::createFromEnv();

Orders

Create an order (auto-assign carrier)

use MimicAk\ShipwayPhpSdk\Models\Order;
use MimicAk\ShipwayPhpSdk\Models\Product;

$product = new Product();
$product->product          = 'Blue T-Shirt';
$product->price            = '499.00';
$product->product_quantity = '2';
$product->product_code     = 'SKU-001';

$order = new Order();
$order->order_id = 'ORD-20240501-001';
$order->products = [$product];

// Billing address
$order->billing_firstname = 'Ravi';
$order->billing_lastname  = 'Kumar';
$order->billing_address   = '12, MG Road';
$order->billing_city      = 'Bangalore';
$order->billing_state     = 'Karnataka';
$order->billing_country   = 'India';
$order->billing_zipcode   = '560001';
$order->billing_phone     = '9876543210';

// Shipping address
$order->shipping_firstname = 'Ravi';
$order->shipping_lastname  = 'Kumar';
$order->shipping_address   = '12, MG Road';
$order->shipping_city      = 'Bangalore';
$order->shipping_state     = 'Karnataka';
$order->shipping_country   = 'India';
$order->shipping_zipcode   = '560001';
$order->shipping_phone     = '9876543210';

$order->payment_type  = 'P';   // P = Prepaid, C = COD
$order->order_total   = '998.00';
$order->email         = 'ravi@example.com';

// Optional dimensions
$order->order_weight  = '0.5';  // kg
$order->box_length    = '20';   // cm
$order->box_breadth   = '15';
$order->box_height    = '10';

$response = $shipway->orders()->create($order);

if ($response->success) {
    echo 'Order created. AWB: ' . $response->getAwbNumber();
    echo 'Label URL: '          . $response->getShippingLabelUrl();
}

Create an order with specific carrier and warehouse

$order->carrier_id          = 3411;  // from courier()->list()
$order->warehouse_id        = 101;   // from warehouse dashboard
$order->return_warehouse_id = 101;

$response = $shipway->orders()->createWithLabel($order);

Fetch orders

use MimicAk\ShipwayPhpSdk\Models\Request\ShipmentBooking\GetOrdersRequest;
use MimicAk\ShipwayPhpSdk\Models\Request\ShipmentBooking\ShipmentStatus;

$request = new GetOrdersRequest();
$request->date_from       = '2024-05-01';
$request->date_to         = '2024-05-31';
$request->shipment_status = ShipmentStatus::STATUS_IN_TRANSIT;
$request->page            = 1;

$response = $shipway->orders()->getOrders($request);

foreach ($response->getOrders() as $order) {
    echo $order->order_id . ' — ' . $order->tracking_number . PHP_EOL;
}

Track a shipment

// By AWB number
$tracking = $shipway->orders()->track('1333110020164');

// By your order ID
$tracking = $shipway->orders()->trackByOrderId('ORD-20240501-001');

// With full scan history
$tracking = $shipway->orders()->track('1333110020164', trackingHistory: 1);

foreach ($tracking->shipments as $shipment) {
    echo $shipment->tracking_details->shipment_status . PHP_EOL;
    echo $shipment->tracking_details->track_url       . PHP_EOL;

    foreach ($shipment->tracking_details->shipment_details as $detail) {
        echo $detail->courier_name   . PHP_EOL;
        echo $detail->current_status . PHP_EOL;
    }
}

Create a manifest

use MimicAk\ShipwayPhpSdk\Models\Request\ShipmentBooking\ManifestRequest;

$request  = new ManifestRequest(['ORD-001', 'ORD-002', 'ORD-003']);
$response = $shipway->orders()->createManifest($request);

echo $response->manifest_ids;

Cancel orders (before booking)

$request  = new ManifestRequest(['ORD-001', 'ORD-002']);
$response = $shipway->orders()->cancelOrders($request);

echo 'Cancelled: ' . $response->success_count . PHP_EOL;
echo 'Failed: '    . $response->failure_count . PHP_EOL;

Put orders on hold

$request  = new ManifestRequest(['ORD-001']);
$response = $shipway->orders()->onHoldOrders($request);

Cancel a booked shipment

// Single AWB
$response = $shipway->orders()->cancelShipment('1333110020164');

// Multiple AWBs
$response = $shipway->orders()->cancelShipment(['1333110020164', '1333110020165']);

echo $response->shipment_success_tracking_numbers;
echo $response->shipment_failed_tracking_numbers;

Couriers

List available couriers

$response = $shipway->courier()->list();

foreach ($response->carriers as $carrier) {
    echo $carrier->id    . ' — ' . $carrier->carrier_title . PHP_EOL;
    echo 'Supports RTO: ' . ($carrier->reverse_status ? 'yes' : 'no') . PHP_EOL;
}

Check pincode serviceability

// All payment types
$response = $shipway->courier()->getPincodeAvailability('560001');

// COD only
$response = $shipway->courier()->getPincodeAvailability('560001', 'C');

foreach ($response->carriers as $carrier) {
    echo $carrier->name . ' (' . $carrier->payment_type . ')' . PHP_EOL;
}

Get carrier rate cards

use MimicAk\ShipwayPhpSdk\Models\Request\Carriers\GetCarrierRates;

$rateRequest = new GetCarrierRates();
$rateRequest->fromPincode      = 110001;
$rateRequest->toPincode        = 560001;
$rateRequest->paymentType      = 'prepaid';
$rateRequest->weight           = 0.5;   // kg
$rateRequest->length           = 20;    // cm
$rateRequest->breadth          = 15;
$rateRequest->height           = 10;
$rateRequest->cummulativePrice = 999;   // required for COD

$response = $shipway->courier()->getCarrierRates($rateRequest);

foreach ($response->carriers as $carrier) {
    echo $carrier->carrier_title  . PHP_EOL;
    echo 'Delivery: Rs. '         . $carrier->delivery_charge . PHP_EOL;
    echo 'RTO: Rs. '              . $carrier->rto_charge      . PHP_EOL;
    echo 'Zone: '                 . $carrier->zone            . PHP_EOL;
}

Warehouses

Create a warehouse / pickup address

use MimicAk\ShipwayPhpSdk\Models\Request\Warehouses\CreateWarehouse;

$warehouse          = new CreateWarehouse();
$warehouse->name    = 'Main Fulfilment Centre';
$warehouse->phone   = '9876543210';
$warehouse->address = '15, Industrial Area, Phase 1';
$warehouse->city    = 'Delhi';
$warehouse->state   = 'Delhi';
$warehouse->country = 'India';
$warehouse->pincode = '110020';
$warehouse->email   = 'warehouse@example.com';
$warehouse->gstin   = '07AAACB2894L1ZX';

$response = $shipway->warehouse()->create($warehouse);

echo 'Warehouse ID: ' . $response->warehouseId;

Error handling

All SDK methods throw typed exceptions. Catch the most specific type you need:

use MimicAk\ShipwayPhpSdk\Exceptions\ValidationException;
use MimicAk\ShipwayPhpSdk\Exceptions\AuthenticationException;
use MimicAk\ShipwayPhpSdk\Exceptions\RateLimitException;
use MimicAk\ShipwayPhpSdk\Exceptions\ApiException;
use MimicAk\ShipwayPhpSdk\Exceptions\ShipwayException;

try {
    $response = $shipway->orders()->create($order);
} catch (ValidationException $e) {
    // Missing/invalid request fields (HTTP 422)
    foreach ($e->getErrors() as $field => $message) {
        echo "{$field}: {$message}" . PHP_EOL;
    }
} catch (AuthenticationException $e) {
    // Bad credentials (HTTP 401/403)
    echo $e->getSuggestedAction();
} catch (RateLimitException $e) {
    // Throttled (HTTP 429)
    sleep($e->getRetryAfter() ?? 60);
} catch (ApiException $e) {
    // Any other HTTP error
    echo 'HTTP ' . $e->getStatusCode() . ': ' . $e->getMessage();
} catch (ShipwayException $e) {
    // Network/config errors
    echo $e->getMessage();
}

Exception hierarchy

ShipwayException
└── ApiException
    ├── AuthenticationException  (401, 403)
    ├── ValidationException      (422)
    ├── RateLimitException       (429)
    ├── ResourceException        (404, 409)
    └── NetworkException         (connection errors)

Configuration reference

$shipway = Shipway::create('email', 'key', [
    'base_url'       => 'https://app.shipway.com/', // default
    'timeout'        => 30,     // seconds, default 30
    'retry_attempts' => 3,      // default 3 (exponential back-off)
    'debug'          => false,  // default false; true enables Guzzle debug output
    'partner_code'   => null,   // optional X-Partner-Code header
    'webhook_secret' => null,   // for webhook signature verification
]);

Order status codes

Shipment status codes

Running tests

composer test

Coverage report:

composer test-coverage

License

MIT