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:

Authentication

The Shiplee API uses JSON Web Tokens (JWT) for secure authentication. Follow these steps to access protected endpoints:

  1. Obtain API Credentials: Register at app.shiplee.ai and generate an API key in the API Settings.
  2. 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.
  3. Authenticate: Send a POST request to /login with your credentials to receive a JWT token, valid for 1 hour.
  4. Use JWT Token: Include the token in the Authorization: Bearer <token> header for all subsequent requests to protected endpoints.
Ensure your IP and domain are whitelisted to avoid 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
        }
    ]
}
Set 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
orderIdstringrequiredOriginal forward order ID
awbNumberstringrequiredAWB number of the original shipment
reasonstringrequiredReason for the return / reverse pickup
warehouseIdintegerrequiredDestination warehouse for the returned parcel
paymentTypestringoptionalprepaid (default) or cod
insurancebooleanoptionalWhether to enable shipment insurance. Default: false
customerobjectrequiredCustomer pickup address block (see below)
productsarrayrequiredArray of product objects being returned
parcelobjectrequiredParcel dimensions and weight

customer Object

FieldTypeRequiredDescription
namestringrequiredCustomer full name
mobilestringrequired10-digit Indian mobile number
altMobilestringoptionalAlternate mobile number
emailstringoptionalCustomer email address
address1stringrequiredPrimary address line
address2stringoptionalSecondary address line / landmark
pincodestringrequired6-digit Indian pincode (must start with 1–9)
citystringrequiredCity name
statestringrequiredState name
addressTypestringoptionale.g., home, office

products Array Item

FieldTypeRequiredDescription
productNamestringrequiredName of the product
quantityintegerrequiredNumber of units being returned
productPricefloatrequiredPrice per unit
skustringoptionalSKU code. Auto-generated if not provided.

parcel Object

FieldTypeRequiredDescription
lengthfloatrequiredLength in cm
breadthfloatrequiredBreadth in cm
heightfloatrequiredHeight in cm
physicalWeightfloatrequiredActual weight in kg. Chargeable weight uses the higher of physical vs volumetric.
Note: The 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"
}
A minimum wallet balance of ₹500 is required to book shipments. The 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.

Functionality for this endpoint is currently in development. Please check back later for detailed documentation and examples.

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: