Overview
Welcome to the Shiplee API, a robust platform for integrating logistics and order management. This API enables sellers to authenticate securely, create orders with flexible billing options, manage warehouses, and handle shipments efficiently.
Base URL: https://apiv1.shiplee.app
Key Features:
- JWT-based authentication with IP and domain whitelisting.
- Order creation supporting same or different billing and shipping addresses.
- Reverse order creation for returns and exchange pickups.
- Warehouse management for adding and retrieving pickup locations.
- Shipment booking with courier rate fetching and tracking.
Authentication
The Shiplee API uses JSON Web Tokens (JWT) for secure authentication. Follow these steps to access protected endpoints:
- Obtain API Credentials: Register at app.shiplee.ai and generate an API key in the API Settings.
- Whitelist IP and Domain: Add your server's IP (e.g.,
106.51.205.161) and domain (e.g.,localhost) in the API Settings for security. - Authenticate: Send a POST request to
/loginwith your credentials to receive a JWT token, valid for 1 hour. - Use JWT Token: Include the token in the
Authorization: Bearer <token>header for all subsequent requests to protected endpoints.
403 Forbidden errors.
Login Endpoint
POST /login
Authenticates a user and returns a JWT token for accessing protected endpoints.
Request Body
{
"username": "demo@shiplee.in",
"apikey": "your-api-key"
}
Examples
curl -X POST https://apiv1.shiplee.app/login \
-H "Content-Type: application/json" \
-H "Origin: http://localhost" \
-H "X-Forwarded-For: 106.51.205.161" \
-d '{"username": "demo@shiplee.in", "apikey": "your-api-key"}'
$body = @{
username = "demo@shiplee.in"
apikey = "your-api-key"
} | ConvertTo-Json
$headers = @{
"Content-Type" = "application/json"
"Origin" = "http://localhost"
"X-Forwarded-For" = "106.51.205.161"
}
Invoke-RestMethod -Uri "https://apiv1.shiplee.app/login" -Method Post -Body $body -Headers $headers
<?php
$ch = curl_init('https://apiv1.shiplee.app/login');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Origin: http://localhost',
'X-Forwarded-For: 106.51.205.161'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'username' => 'demo@shiplee.in',
'apikey' => 'your-api-key'
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
import requests
url = 'https://apiv1.shiplee.app/login'
headers = {
'Content-Type': 'application/json',
'Origin': 'http://localhost',
'X-Forwarded-For': '106.51.205.161'
}
data = {
'username': 'demo@shiplee.in',
'apikey': 'your-api-key'
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
fetch('https://apiv1.shiplee.app/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
username: 'demo@shiplee.in',
apikey: 'your-api-key'
})
})
.then(r => r.json())
.then(data => console.log('Token:', data.token));
Success Response (200)
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 62,
"email": "demo@shiplee.in",
"shiplee_id": "d10701280b9798033c6917e9415b03c3"
}
}
Add Order Endpoint
POST /order
Creates a new forward order with customer, billing, product, and parcel details. Supports both same and different billing/shipping addresses.
Request Body
{
"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": 50.00,
"sku": "SKU123"
}
],
"parcels": [
{
"length": 10,
"breadth": 10,
"height": 10,
"physicalWeight": 1.5
}
]
}
sameAddressCheckbox to 0 and provide additional billing* fields (e.g., billingPincode, billingName) for orders with different billing and shipping addresses.
Success Response (201)
{
"success": true,
"message": "Order added successfully",
"order_id": 484900
}
Reverse Order Endpoint
POST /reverse_order
Creates a reverse pickup order for returns or exchanges. Requires the original order ID and AWB number, along with customer pickup address, product details, and parcel dimensions.
Request Body
{
"orderId": "ORD-123456",
"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": 50.00,
"sku": "SKU123"
}
],
"parcel": {
"length": 10,
"breadth": 10,
"height": 10,
"physicalWeight": 1.5
}
}
Field Reference
| Field | Type | Required | Description |
|---|---|---|---|
orderId | string | required | Original forward order ID |
awbNumber | string | required | AWB number of the original shipment |
reason | string | required | Reason for the return / reverse pickup |
warehouseId | integer | required | Destination warehouse for the returned parcel |
paymentType | string | optional | prepaid (default) or cod |
insurance | boolean | optional | Whether to enable shipment insurance. Default: false |
customer | object | required | Customer pickup address block (see below) |
products | array | required | Array of product objects being returned |
parcel | object | required | Parcel dimensions and weight |
customer Object
| Field | Type | Required | Description |
|---|---|---|---|
name | string | required | Customer full name |
mobile | string | required | 10-digit Indian mobile number |
altMobile | string | optional | Alternate mobile number |
email | string | optional | Customer email address |
address1 | string | required | Primary address line |
address2 | string | optional | Secondary address line / landmark |
pincode | string | required | 6-digit Indian pincode (must start with 1–9) |
city | string | required | City name |
state | string | required | State name |
addressType | string | optional | e.g., home, office |
products Array Item
| Field | Type | Required | Description |
|---|---|---|---|
productName | string | required | Name of the product |
quantity | integer | required | Number of units being returned |
productPrice | float | required | Price per unit |
sku | string | optional | SKU code. Auto-generated if not provided. |
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 | Actual weight in kg. Chargeable weight uses the higher of physical vs volumetric. |
warehouseId must belong to your account. The warehouse acts as the return destination — parcels will be routed back to it.
Examples
curl -X POST https://apiv1.shiplee.app/reverse_order \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Origin: http://localhost" \
-d '{
"orderId": "ORD-123456",
"awbNumber": "XB1234567890",
"reason": "Customer return - wrong size",
"warehouseId": 2147483833,
"paymentType": "prepaid",
"insurance": false,
"customer": {
"name": "John Doe",
"mobile": "9000000001",
"address1": "123 Sample Street, Apt 4B",
"pincode": "560098",
"city": "Bangalore",
"state": "Karnataka"
},
"products": [
{ "productName": "Sample Product", "quantity": 1, "productPrice": 50.00, "sku": "SKU123" }
],
"parcel": { "length": 10, "breadth": 10, "height": 10, "physicalWeight": 1.5 }
}'
<?php
$payload = [
'orderId' => 'ORD-123456',
'awbNumber' => 'XB1234567890',
'reason' => 'Customer return - wrong size',
'warehouseId' => 2147483833,
'paymentType' => 'prepaid',
'insurance' => false,
'customer' => [
'name' => 'John Doe',
'mobile' => '9000000001',
'address1' => '123 Sample Street, Apt 4B',
'pincode' => '560098',
'city' => 'Bangalore',
'state' => 'Karnataka',
],
'products' => [
['productName' => 'Sample Product', 'quantity' => 1, 'productPrice' => 50.00, 'sku' => 'SKU123']
],
'parcel' => ['length' => 10, 'breadth' => 10, 'height' => 10, 'physicalWeight' => 1.5],
];
$ch = curl_init('https://apiv1.shiplee.app/reverse_order');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer YOUR_JWT_TOKEN',
'Origin: http://localhost',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
import requests
url = 'https://apiv1.shiplee.app/reverse_order'
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_JWT_TOKEN',
'Origin': 'http://localhost'
}
data = {
'orderId': 'ORD-123456',
'awbNumber': 'XB1234567890',
'reason': 'Customer return - wrong size',
'warehouseId': 2147483833,
'paymentType': 'prepaid',
'insurance': False,
'customer': {
'name': 'John Doe',
'mobile': '9000000001',
'address1': '123 Sample Street, Apt 4B',
'pincode': '560098',
'city': 'Bangalore',
'state': 'Karnataka'
},
'products': [
{'productName': 'Sample Product', 'quantity': 1, 'productPrice': 50.00, 'sku': 'SKU123'}
],
'parcel': {'length': 10, 'breadth': 10, 'height': 10, 'physicalWeight': 1.5}
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
fetch('https://apiv1.shiplee.app/reverse_order', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_JWT_TOKEN'
},
body: JSON.stringify({
orderId: 'ORD-123456',
awbNumber: 'XB1234567890',
reason: 'Customer return - wrong size',
warehouseId: 2147483833,
paymentType: 'prepaid',
insurance: false,
customer: {
name: 'John Doe',
mobile: '9000000001',
address1: '123 Sample Street, Apt 4B',
pincode: '560098',
city: 'Bangalore',
state: 'Karnataka'
},
products: [
{ productName: 'Sample Product', quantity: 1, productPrice: 50.00, sku: 'SKU123' }
],
parcel: { length: 10, breadth: 10, height: 10, physicalWeight: 1.5 }
})
})
.then(r => r.json())
.then(data => console.log(data));
Success Response (201)
{
"success": true,
"message": "Reverse order created successfully",
"reverse_order_id": "RO-1A2B3C"
}
Error Responses
// 400 – Missing required field
{ "success": false, "message": "Missing required field: reason" }
// 400 – Invalid pincode
{ "success": false, "message": "Invalid pincode: must be a 6-digit number starting with 1-9" }
// 400 – Invalid warehouse
{ "success": false, "message": "Invalid or unauthorized warehouse" }
// 401 – JWT invalid / expired
{ "success": false, "message": "Invalid JWT token" }
// 403 – IP not whitelisted
{ "success": false, "message": "The IP '1.2.3.4' is not whitelisted" }
Create Shipment Endpoint
POST /create_shipment
Books a shipment for an existing order by assigning a courier. Requires a valid orderId, warehouseId, and courier details obtained from the rates endpoint.
Request Body
{
"orderId": 484900,
"warehouseId": 2147483833,
"action": "book_shipment",
"carrierId": "12298",
"carrierName": "Xpressbees 1 K.G",
"shipmentType": "forward"
}
carrierId and carrierName must match a valid rate returned by the /rates endpoint.
Success Response (201)
{
"success": true,
"message": "Shipment booked",
"awb_number": "XB1234567890",
"shipment_id": "SHPL-54321"
}
Reverse Shipment Endpoint Coming Soon
This endpoint will be used to book a reverse shipment for an existing reverse order, assigning a courier for the pickup.
Rates Endpoint
POST /rates
Fetches available courier rates for an existing order based on its weight, dimensions, and delivery location.
Request Body
{
"orderId": 484900,
"warehouseId": 2147483833,
"shipmentType": "forward"
}
Success Response (200)
{
"success": true,
"message": "Rates fetched successfully",
"data": {
"carrier_info": [
{
"carrier_id": "12298",
"carrier_name": "Xpressbees 1 K.G",
"cost": 138,
"freight_charges": 138,
"cod_charges": 0
},
{
"carrier_id": "279",
"carrier_name": "Bluedart- Surface",
"cost": 190,
"freight_charges": 190,
"cod_charges": 0
}
]
}
}
Warehouse Management
Manage your pickup locations for shipments. You can add new warehouses or retrieve a list of existing ones.
Add Warehouse
POST /add_warehouse
Adds a new warehouse, which serves as a pickup address for your shipments.
{
"nickname": "Main Warehouse",
"mobileNumber": "9000000001",
"address1": "123 Logistics Road",
"pincode": "123456",
"state": "Sample State",
"city": "Sample City",
"addressType": "primary"
}
Get Warehouses
GET /get_warehouses
Retrieves a list of all non-deleted warehouses for the authenticated seller.
{
"success": true,
"message": "Warehouses retrieved successfully",
"data": [
{
"id": 2147483833,
"nickname": "Main Warehouse",
"address1": "123 Logistics Road",
"pincode": "123456",
"city": "Sample City",
"state": "Sample State",
"addressType": "primary"
}
]
}
Support
For technical assistance or questions about the API, please contact our support team:
- Email: support@shiplee.app
- WhatsApp: +91 8645322815