REST API · JSON · Bearer Auth

Shiplee
API Reference

Full logistics integration — authenticate, create orders, fetch rates, book shipments. https://apiv1.shiplee.app

Overview

The Shiplee API is a RESTful JSON interface for programmatic logistics management. All requests and responses use application/json unless noted.

Capabilities

JWT authentication with per-seller IP and domain whitelisting
Forward order creation with same or separate billing / shipping addresses
Reverse order creation for customer returns and exchange pickups
Live courier rate fetching with zone, weight-slab, and COD pricing
Forward and reverse shipment booking via Delhivery (Express & Surface)
Warehouse management for pickup and return destinations

All protected endpoints require Authorization: Bearer <token>. Tokens expire after 1 hour — re-authenticate via /login to refresh.

Authentication

Shiplee uses signed JWT tokens bound to your seller account. Every token encodes your user ID, email, and Shiplee ID.

Setup steps

Register at app.shiplee.ai and generate an API key in API Settings.
Whitelist your server IP address and request domain in API Settings.
POST credentials to /login — receive a JWT valid for 1 hour.
Pass Authorization: Bearer <token> on every subsequent request.

Both IP and domain must be whitelisted. Requests from unknown origins return 403 Forbidden.

Login

POST/login

Authenticates your credentials and returns a JWT token.

Request body

json

{
    "username": "you@example.com",
    "apikey":   "your-api-key"
}

Code examples

bash

curl -X POST https://apiv1.shiplee.app/login \
  -H "Content-Type: application/json" \
  -H "Origin: http://localhost" \
  -d '{"username":"you@example.com","apikey":"your-api-key"}'

powershell

$body    = @{ username = "you@example.com"; apikey = "your-api-key" } | ConvertTo-Json
$headers = @{ "Content-Type" = "application/json"; "Origin" = "http://localhost" }
Invoke-RestMethod -Uri "https://apiv1.shiplee.app/login" -Method Post -Body $body -Headers $headers

php

<?php
$ch = curl_init('https://apiv1.shiplee.app/login');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json','Origin: http://localhost'],
    CURLOPT_POSTFIELDS => json_encode(['username'=>'you@example.com','apikey'=>'your-api-key']),
]);
echo curl_exec($ch); curl_close($ch);

python

import requests
r = requests.post('https://apiv1.shiplee.app/login',
    json={'username': 'you@example.com', 'apikey': 'your-api-key'},
    headers={'Origin': 'http://localhost'})
token = r.json()['token']

javascript

const { token } = await fetch('https://apiv1.shiplee.app/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username: 'you@example.com', apikey: 'your-api-key' })
}).then(r => r.json());

Response 200

json

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
        "id":         62,
        "email":      "you@example.com",
        "shiplee_id": "d10701280b9798033c6917e9415b03c3"
    }
}

Add Order

POST/order

Creates a new forward order. Returns a numeric order_id used across all shipping endpoints.

Request body

json

{
    "pincode":             "560098",
    "city":                "Bangalore",
    "state":               "Karnataka",
    "name":                "John Doe",
    "email":               "customer@example.com",
    "mobileNumber":        "9000000001",
    "addressLine1":        "123 Sample Street, Apt 4B",
    "sameAddressCheckbox": 1,
    "orderID":             "ORD-123456",
    "paymentType":         "prepaid",
    "products": [
        { "productName": "Sample Product", "quantity": 2, "productPrice": 500.00, "sku": "SKU123" }
    ],
    "parcels": [
        { "length": 10, "breadth": 10, "height": 10, "physicalWeight": 1.5 }
    ]
}

Set sameAddressCheckbox to 0 and add billingPincode, billingName, etc. for separate billing addresses.

Response 201

json

{
    "success":  true,
    "message":  "Order added successfully",
    "order_id": 484900
}

Reverse Order

POST/reverse_order

Creates a reverse pickup order for a customer return or exchange. Links to an existing forward order and routes the parcel back to your warehouse.

Critical: orderId must be the numeric integer from /order (e.g. 484900). Passing a string like "ORD-123456" causes a 400 error. The warehouseId must belong to your account.

Request body

json

{
    "orderId":     484900,
    "awbNumber":   "XB1234567890",
    "reason":      "Customer return — wrong size",
    "warehouseId": 2147483833,
    "paymentType": "prepaid",
    "insurance":   false,
    "customer": {
        "name":        "John Doe",
        "mobile":      "9000000001",
        "altMobile":   "9000000002",
        "email":       "customer@example.com",
        "address1":    "123 Sample Street, Apt 4B",
        "address2":    "Near City Mall",
        "pincode":     "560098",
        "city":        "Bangalore",
        "state":       "Karnataka",
        "addressType": "home"
    },
    "products": [
        { "productName": "Sample Product", "quantity": 1, "productPrice": 500.00, "sku": "SKU123" }
    ],
    "parcel": { "length": 10, "breadth": 10, "height": 10, "physicalWeight": 1.5 }
}

Top-level fields

Field	Type	Required	Description
`orderId`	integer	required	Numeric ID from `/order` response
`awbNumber`	string	required	AWB of the original forward shipment
`reason`	string	required	Reason for return / reverse pickup
`warehouseId`	integer	required	Return destination warehouse ID
`paymentType`	string	optional	`prepaid` (default) or `cod`
`insurance`	boolean	optional	Enable insurance. Default: `false`
`customer`	object	required	Customer pickup address block
`products`	array	required	Items being returned
`parcel`	object	required	Package dimensions and weight

customer object

Field	Type	Required	Description
`name`	string	required	Customer full name
`mobile`	string	required	10-digit Indian mobile (starts 6–9)
`address1`	string	required	Primary address line
`pincode`	string	required	6-digit pincode (starts 1–9)
`city`	string	required	City name
`state`	string	required	State name
`altMobile`	string	optional	Alternate mobile number
`email`	string	optional	Customer email
`address2`	string	optional	Landmark / secondary line
`addressType`	string	optional	`home` or `office`

products[] item

Field	Type	Required	Description
`productName`	string	required	Product name
`quantity`	integer	required	Units being returned
`productPrice`	float	required	Price per unit
`sku`	string	optional	SKU. Auto-generated if omitted.

parcel object

Field	Type	Required	Description
`length`	float	required	Length in cm
`breadth`	float	required	Breadth in cm
`height`	float	required	Height in cm
`physicalWeight`	float	required	Weight in kg. Chargeable = max(physical, volumetric).

Code examples

bash

curl -X POST https://apiv1.shiplee.app/reverse_order \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "orderId": 484900, "awbNumber": "XB1234567890",
    "reason": "Customer return", "warehouseId": 2147483833,
    "customer": { "name":"John Doe","mobile":"9000000001","address1":"123 Sample St",
                  "pincode":"560098","city":"Bangalore","state":"Karnataka" },
    "products": [{"productName":"Sample Product","quantity":1,"productPrice":500}],
    "parcel": {"length":10,"breadth":10,"height":10,"physicalWeight":1.5}
  }'

php

<?php
$payload = [
    'orderId' => 484900, 'awbNumber' => 'XB1234567890',
    'reason'  => 'Customer return', 'warehouseId' => 2147483833,
    'customer' => ['name'=>'John Doe','mobile'=>'9000000001',
        'address1'=>'123 Sample St','pincode'=>'560098',
        'city'=>'Bangalore','state'=>'Karnataka'],
    'products' => [['productName'=>'Sample Product','quantity'=>1,'productPrice'=>500]],
    'parcel'   => ['length'=>10,'breadth'=>10,'height'=>10,'physicalWeight'=>1.5],
];
$ch = curl_init('https://apiv1.shiplee.app/reverse_order');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER=>true, CURLOPT_POST=>true,
    CURLOPT_HTTPHEADER=>['Content-Type: application/json','Authorization: Bearer YOUR_JWT'],
    CURLOPT_POSTFIELDS=>json_encode($payload)]);
echo curl_exec($ch); curl_close($ch);

python

import requests
r = requests.post('https://apiv1.shiplee.app/reverse_order',
    json={
        'orderId': 484900, 'awbNumber': 'XB1234567890',
        'reason': 'Customer return', 'warehouseId': 2147483833,
        'customer': {'name':'John Doe','mobile':'9000000001','address1':'123 Sample St',
            'pincode':'560098','city':'Bangalore','state':'Karnataka'},
        'products': [{'productName':'Sample Product','quantity':1,'productPrice':500}],
        'parcel': {'length':10,'breadth':10,'height':10,'physicalWeight':1.5}
    }, headers={'Authorization': 'Bearer YOUR_JWT_TOKEN'})
print(r.json())

javascript

await fetch('https://apiv1.shiplee.app/reverse_order', {
    method: 'POST',
    headers: { 'Content-Type':'application/json', 'Authorization':'Bearer YOUR_JWT_TOKEN' },
    body: JSON.stringify({
        orderId: 484900, awbNumber: 'XB1234567890',
        reason: 'Customer return', warehouseId: 2147483833,
        customer: { name:'John Doe', mobile:'9000000001', address1:'123 Sample St',
                    pincode:'560098', city:'Bangalore', state:'Karnataka' },
        products: [{ productName:'Sample Product', quantity:1, productPrice:500 }],
        parcel: { length:10, breadth:10, height:10, physicalWeight:1.5 }
    })
}).then(r => r.json()).then(console.log);

Response 201

json

{
    "success":          true,
    "message":          "Reverse order created successfully",
    "reverse_order_id": "RO-7A685"
}

Error responses 4xx

json

{ "success": false, "message": "Missing required field: reason" }
{ "success": false, "message": "Invalid pincode: must be 6-digit starting 1-9" }
{ "success": false, "message": "Invalid or unauthorized warehouse" }
{ "success": false, "message": "Invalid JWT token" }
{ "success": false, "message": "The IP '1.2.3.4' is not whitelisted" }

Get Rates

POST/rates

Returns available Delhivery Express and Surface courier options with freight and COD charges for an existing order.

Request body

json

{
    "orderId":      484900,
    "warehouseId":  2147483833,
    "shipmentType": "forward"
}

Response 200

json

{
    "success": true,
    "message": "Rates fetched successfully",
    "data": {
        "carrier_info": [
            {
                "carrier_id":        "delhivery_e_prepaid",
                "carrier_name":      "Delhivery Express",
                "cost":              138,
                "freight_charges":   138,
                "cod_charges":       0,
                "tat":               "2-3 days"
            },
            {
                "carrier_id":        "delhivery_s_prepaid",
                "carrier_name":      "Delhivery Surface",
                "cost":              104,
                "freight_charges":   104,
                "cod_charges":       0,
                "tat":               "4-6 days"
            }
        ]
    }
}

Use the exact carrier_id and carrier_name from this response when booking a shipment. Rates include GST and your plan's markup percentage.

Create Shipment

POST/create_shipment

Books a forward shipment for an existing order using a carrier from /rates. Deducts charges from your wallet and returns the AWB number.

A minimum wallet balance of ₹500 is required. Duplicate bookings for the same orderId are rejected automatically.

Request body

json

{
    "orderId":      484900,
    "warehouseId":  2147483833,
    "action":       "book_shipment",
    "carrierId":    "delhivery_e_prepaid",
    "carrierName":  "Delhivery Express",
    "shipmentType": "forward"
}

Fields

Field	Type	Required	Description
`orderId`	integer	required	Numeric order ID from `/order`
`warehouseId`	integer	required	Pickup warehouse ID
`action`	string	required	Must be `book_shipment`
`carrierId`	string	required	`carrier_id` from `/rates` response
`carrierName`	string	required	`carrier_name` from `/rates` response
`shipmentType`	string	required	Must be `forward` for this endpoint

Code examples

bash

curl -X POST https://apiv1.shiplee.app/create_shipment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "orderId": 484900,
    "warehouseId": 2147483833,
    "action": "book_shipment",
    "carrierId": "delhivery_e_prepaid",
    "carrierName": "Delhivery Express",
    "shipmentType": "forward"
  }'

php

<?php
$ch = curl_init('https://apiv1.shiplee.app/create_shipment');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER=>true, CURLOPT_POST=>true,
    CURLOPT_HTTPHEADER=>['Content-Type: application/json','Authorization: Bearer YOUR_JWT'],
    CURLOPT_POSTFIELDS=>json_encode([
        'orderId'=>484900, 'warehouseId'=>2147483833,
        'action'=>'book_shipment', 'carrierId'=>'delhivery_e_prepaid',
        'carrierName'=>'Delhivery Express', 'shipmentType'=>'forward'
    ])]);
echo curl_exec($ch); curl_close($ch);

python

import requests
r = requests.post('https://apiv1.shiplee.app/create_shipment',
    json={
        'orderId': 484900, 'warehouseId': 2147483833,
        'action': 'book_shipment', 'carrierId': 'delhivery_e_prepaid',
        'carrierName': 'Delhivery Express', 'shipmentType': 'forward'
    }, headers={'Authorization': 'Bearer YOUR_JWT_TOKEN'})
print(r.json())

javascript

await fetch('https://apiv1.shiplee.app/create_shipment', {
    method: 'POST',
    headers: { 'Content-Type':'application/json', 'Authorization':'Bearer YOUR_JWT_TOKEN' },
    body: JSON.stringify({
        orderId: 484900, warehouseId: 2147483833,
        action: 'book_shipment', carrierId: 'delhivery_e_prepaid',
        carrierName: 'Delhivery Express', shipmentType: 'forward'
    })
}).then(r => r.json()).then(console.log);

Response 201

json

{
    "success":     true,
    "message":     "Shipment booked",
    "awb_number":  "XB1234567890",
    "shipment_id": "SHPL-54321"
}

Error responses 4xx

json

{ "success": false, "message": "Insufficient balance (< ₹500)" }
{ "success": false, "message": "Missing required parameters" }
{ "success": false, "message": "Order already booked with AWB: XB9999999" }
{ "success": false, "message": "Unsupported courier for carrierName: XYZ" }
{ "success": false, "message": "Order or warehouse not found" }

Reverse Shipment

POST/reverse_create_shipment

Books a Delhivery pickup for an existing reverse order. Registers your warehouse with Delhivery if not already done, generates an AWB, deducts charges, and updates the reverse order status.

First create a reverse order via /reverse_order — you'll receive a numeric id (the reverse_order_id in the DB, not the RO-XXXX string). Use that numeric ID as order_id here.

Minimum wallet balance of ₹500 required. Request body is sent as application/x-www-form-urlencoded, not JSON.

Request body — form-urlencoded

form-urlencoded

order_id=1042&warehouse_id=2147483833&carrierId=delhivery_e_prepaid&carrierName=Delhivery+Express

Fields

Field	Type	Required	Description
`order_id`	integer	required	Numeric DB ID of the reverse order (not the RO-XXXX string)
`warehouse_id`	integer	required	Return destination warehouse — must belong to your account
`carrierId`	string	required	`carrier_id` from `/rates` — e.g. `delhivery_e_prepaid` or `delhivery_s_prepaid`
`carrierName`	string	required	URL-encoded carrier name — e.g. `Delhivery+Express` or `Delhivery+Surface`

Available carriers

carrierId	carrierName	Transit
`delhivery_e_prepaid`	`Delhivery Express`	2–3 days
`delhivery_s_prepaid`	`Delhivery Surface`	4–6 days

Code examples

bash

curl -X POST https://apiv1.shiplee.app/reverse_create_shipment \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  --data-urlencode "order_id=1042" \
  --data-urlencode "warehouse_id=2147483833" \
  --data-urlencode "carrierId=delhivery_e_prepaid" \
  --data-urlencode "carrierName=Delhivery Express"

php

<?php
$ch = curl_init('https://apiv1.shiplee.app/reverse_create_shipment');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER=>true, CURLOPT_POST=>true,
    CURLOPT_HTTPHEADER=>['Authorization: Bearer YOUR_JWT_TOKEN'],
    CURLOPT_POSTFIELDS=>http_build_query([
        'order_id'    => 1042,
        'warehouse_id'=> 2147483833,
        'carrierId'   => 'delhivery_e_prepaid',
        'carrierName' => 'Delhivery Express',
    ])]);
echo curl_exec($ch); curl_close($ch);

python

import requests
r = requests.post('https://apiv1.shiplee.app/reverse_create_shipment',
    data={
        'order_id':     1042,
        'warehouse_id': 2147483833,
        'carrierId':    'delhivery_e_prepaid',
        'carrierName':  'Delhivery Express',
    },
    headers={'Authorization': 'Bearer YOUR_JWT_TOKEN'})
print(r.json())

javascript

const body = new URLSearchParams({
    order_id:     1042,
    warehouse_id: 2147483833,
    carrierId:    'delhivery_e_prepaid',
    carrierName:  'Delhivery Express',
});
await fetch('https://apiv1.shiplee.app/reverse_create_shipment', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN' },
    body
}).then(r => r.json()).then(console.log);

What happens internally

Balance check — rejects if wallet < ₹500
Fetches reverse order details and warehouse data
Registers warehouse with Delhivery if not already done (stores delhivery_warehouse_name)
Fetches live rates for Express / Surface modes
Books pickup via Delhivery API, generates AWB
Updates reverse_orders status, inserts into orders, logs RechargeLogs and ShippingCharges

Response 200 Success

json

{
    "success":     true,
    "message":     "Reverse shipment booked",
    "awb_number":  "1234567890123",
    "shipment_id": "UPLOAD_WBN_ABC"
}

Error responses 4xx / 200 with success:false

json

{ "success": false, "message": "Insufficient balance (< ₹500)" }
{ "success": false, "message": "Missing required parameters" }
{ "success": false, "message": "Order or warehouse not found" }
{ "success": false, "message": "Failed to register warehouse with Delhivery" }
{ "success": false, "message": "Booking failed: [Delhivery remark here]" }
{ "success": false, "message": "Booking failed: Missing or invalid AWB number" }
{ "success": false, "message": "Selected carrier ID 'xyz' not found in rates" }

Warehouse Management

Warehouses are your pickup and return destinations. Register new locations or list existing ones.

POST/add_warehouse

json

{
    "nickname":     "Main Warehouse",
    "mobileNumber": "9000000001",
    "address1":     "123 Logistics Road",
    "pincode":      "110076",
    "city":         "New Delhi",
    "state":        "Delhi",
    "addressType":  "primary"
}

GET/get_warehouses

Returns all active warehouses for the authenticated seller.

json — 200

{
    "success": true,
    "message": "Warehouses retrieved successfully",
    "data": [
        {
            "id":          2147483833,
            "nickname":    "Main Warehouse",
            "address1":    "123 Logistics Road",
            "pincode":     "110076",
            "city":        "New Delhi",
            "state":       "Delhi",
            "addressType": "primary"
        }
    ]
}

Support

Reach the Shiplee technical team through any of these channels:

Channel	Contact
Email	support@shiplee.app
WhatsApp	+91 86453 22815
Dashboard	app.shiplee.ai

ShipleeAPI Reference

Overview

Authentication

Login

Add Order

Reverse Order

Get Rates

Create Shipment

Reverse Shipment

Warehouse Management

Support

Shiplee
API Reference