{ "openapi": "3.0.3", "info": { "title": "Hubbazzar Shipping API", "version": "1.0.0", "description": "Create, track, label, cancel and manage shipments across Delhivery, Shadowfax, Amazon Shipping and Nimbus Post." }, "servers": [ { "url": "https://hubbazzar.com/api/v1/shipping" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Login (get token)", "description": "Exchange your panel email + password for a Bearer token. Use this for server-to-server integrations that prefer revocable tokens; otherwise copy the static token from Panel \u2192 API Settings.", "operationId": "auth-login", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Login successful.", "data": { "token": "12|AbCdEf\u2026", "token_type": "Bearer", "user": { "id": 42, "name": "Acme Store", "email": "user@example.com", "wallet_balance": 1500, "wallet_credit": 0, "status": "active" } } } } } }, "401": { "description": "Invalid credentials." }, "403": { "description": "Account inactive." }, "422": { "description": "Validation failed." } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Panel login email." }, "password": { "type": "string", "description": "Panel password." }, "device_name": { "type": "string", "description": "Label for this token. Logging in again with the same name replaces the old token." } }, "required": [ "email", "password" ] }, "example": { "email": "user@example.com", "password": "secret", "device_name": "my-erp" } } } } } }, "/auth/profile": { "get": { "tags": [ "Authentication" ], "summary": "Get profile", "description": "Returns the account the token belongs to. A cheap way to verify a token works.", "operationId": "auth-profile", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "id": 42, "name": "Acme Store", "email": "user@example.com", "phone": "9811122233", "wallet_balance": 1500, "wallet_credit": 0, "status": "active", "created_at": "2026-01-10 09:00:00" } } } } } } } }, "/auth/token/rotate": { "post": { "tags": [ "Authentication" ], "summary": "Rotate token", "description": "Revokes the token used for this call and returns a new one. Store the new token immediately \u2014 the old one stops working at once.", "operationId": "auth-rotate", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Token rotated successfully.", "data": { "token": "13|XyZ\u2026", "token_type": "Bearer" } } } } } } } }, "/auth/logout": { "post": { "tags": [ "Authentication" ], "summary": "Logout (revoke token)", "description": "Revokes the token used for this call.", "operationId": "auth-logout", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Logged out successfully." } } } } } } }, "/warehouses": { "get": { "tags": [ "Warehouses (pickup addresses)" ], "summary": "List warehouses", "description": "All your pickup/return addresses. `pick_address_id` is what you pass when creating shipments.", "operationId": "wh-list", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": [ { "id": 7, "address_title": "Main Warehouse", "sender_name": "Acme Store", "full_address": "Plot 4, Industrial Area Phase 2", "phone": "9811122233", "email": "ops@acme.com", "pincode": "110020", "city": "New Delhi", "state": "Delhi", "pick_address_id": "Main Warehouse", "delhivery_synced": true, "nimbuspost_synced": false, "created_at": "2026-09-01 10:00:00" } ] } } } } } }, "post": { "tags": [ "Warehouses (pickup addresses)" ], "summary": "Create warehouse", "description": "Saves the address and registers it with Delhivery. If the courier call fails the warehouse is still saved and the response carries `warning: true` \u2014 retry with the sync endpoint.\n\n1. Create each pickup location once, then reuse its `pick_address_id`.\n2. Check `delhivery_synced` in the response (or GET /warehouses/{id}); only synced warehouses can book Delhivery shipments.\n3. For Nimbus Post, also run the two OTP steps below once per warehouse.", "operationId": "wh-create", "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Warehouse created and synced with courier.", "data": { "id": 7, "address_title": "Main Warehouse", "sender_name": "Acme Store", "full_address": "Plot 4, Industrial Area Phase 2", "phone": "9811122233", "email": "ops@acme.com", "pincode": "110020", "city": "New Delhi", "state": "Delhi", "pick_address_id": "Main Warehouse", "delhivery_synced": true, "nimbuspost_synced": false, "created_at": "2026-09-01 10:00:00" } } } } }, "422": { "description": "Validation failed." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address_title": { "type": "string", "description": "Unique name for the pickup point (max 100). Becomes `pick_address_id`." }, "sender_name": { "type": "string", "description": "Contact / seller name printed on labels (max 100)." }, "full_address": { "type": "string", "description": "Street address, without city/state/pincode." }, "phone": { "type": "string", "description": "10\u201315 digits, no spaces or +." }, "email": { "type": "string", "description": "Pickup contact email." }, "pincode": { "type": "string", "description": "6 digits." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State." } }, "required": [ "address_title", "sender_name", "full_address", "phone", "pincode", "city", "state" ] }, "example": { "address_title": "Main Warehouse", "sender_name": "Acme Store", "full_address": "Plot 4, Industrial Area Phase 2", "phone": "9811122233", "email": "ops@acme.com", "pincode": "110020", "city": "New Delhi", "state": "Delhi" } } } } } }, "/warehouses/{id}": { "get": { "tags": [ "Warehouses (pickup addresses)" ], "summary": "Get warehouse", "description": "", "operationId": "wh-show", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "id": 7, "address_title": "Main Warehouse", "sender_name": "Acme Store", "full_address": "Plot 4, Industrial Area Phase 2", "phone": "9811122233", "email": "ops@acme.com", "pincode": "110020", "city": "New Delhi", "state": "Delhi", "pick_address_id": "Main Warehouse", "delhivery_synced": true, "nimbuspost_synced": false, "created_at": "2026-09-01 10:00:00" } } } } }, "404": { "description": "Warehouse not found." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Warehouse id.", "schema": { "type": "integer" } } ] }, "put": { "tags": [ "Warehouses (pickup addresses)" ], "summary": "Update warehouse", "description": "Updates the address on our side only. Changes are not pushed to the courier automatically \u2014 call the sync endpoint afterwards.", "operationId": "wh-update", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Warehouse updated. Note: Changes are NOT automatically synced to the courier. Use the /sync endpoint if needed.", "data": { "id": 7, "address_title": "Main Warehouse", "sender_name": "Acme Store", "full_address": "Plot 4, Industrial Area Phase 2", "phone": "9811122233", "email": "ops@acme.com", "pincode": "110020", "city": "New Delhi", "state": "Delhi", "pick_address_id": "Main Warehouse", "delhivery_synced": true, "nimbuspost_synced": false, "created_at": "2026-09-01 10:00:00" } } } } }, "404": { "description": "Warehouse not found." }, "422": { "description": "Validation failed." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Warehouse id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address_title": { "type": "string", "description": "Unique name for the pickup point (max 100). Becomes `pick_address_id`." }, "sender_name": { "type": "string", "description": "Contact / seller name printed on labels (max 100)." }, "full_address": { "type": "string", "description": "Street address, without city/state/pincode." }, "phone": { "type": "string", "description": "10\u201315 digits, no spaces or +." }, "email": { "type": "string", "description": "Pickup contact email." }, "pincode": { "type": "string", "description": "6 digits." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State." } }, "required": [ "address_title", "sender_name", "full_address", "phone", "pincode", "city", "state" ] }, "example": { "address_title": "Main Warehouse", "sender_name": "Acme Store", "full_address": "Plot 4, Industrial Area Phase 2", "phone": "9811122233", "email": "ops@acme.com", "pincode": "110020", "city": "New Delhi", "state": "Delhi" } } } } }, "delete": { "tags": [ "Warehouses (pickup addresses)" ], "summary": "Delete warehouse", "description": "Removes the address from your account. Existing shipments are not affected.", "operationId": "wh-delete", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Warehouse deleted successfully." } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Warehouse id.", "schema": { "type": "integer" } } ] } }, "/warehouses/{id}/sync": { "post": { "tags": [ "Warehouses (pickup addresses)" ], "summary": "Sync warehouse with Delhivery", "description": "Re-registers the warehouse with Delhivery. Use after a failed create or after editing the address.", "operationId": "wh-sync", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Warehouse synced with courier successfully.", "data": { "id": 7, "address_title": "Main Warehouse", "sender_name": "Acme Store", "full_address": "Plot 4, Industrial Area Phase 2", "phone": "9811122233", "email": "ops@acme.com", "pincode": "110020", "city": "New Delhi", "state": "Delhi", "pick_address_id": "Main Warehouse", "delhivery_synced": true, "nimbuspost_synced": false, "created_at": "2026-09-01 10:00:00" } } } } }, "502": { "description": "Courier sync failed \u2014 message explains why." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Warehouse id.", "schema": { "type": "integer" } } ] } }, "/warehouses/{id}/nimbuspost/send-otp": { "post": { "tags": [ "Warehouses (pickup addresses)" ], "summary": "Nimbus Post \u2014 send OTP (step 1)", "description": "Nimbus Post verifies the pickup phone by OTP before accepting a warehouse. This sends the OTP to the warehouse phone.\n\n1. Needed once per warehouse, only if you ship with Nimbus Post.\n2. Call this endpoint, read the OTP from the SMS, then call step 2.", "operationId": "wh-np-otp", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "OTP sent to 9811122233." } } } }, "404": { "description": "Warehouse not found." }, "422": { "description": "Nimbus Post OTP send failed." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Warehouse id.", "schema": { "type": "integer" } } ] } }, "/warehouses/{id}/nimbuspost/sync": { "post": { "tags": [ "Warehouses (pickup addresses)" ], "summary": "Nimbus Post \u2014 verify OTP & register (step 2)", "description": "", "operationId": "wh-np-sync", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Warehouse synced with Nimbus Post." } } } }, "422": { "description": "OTP verification or registration failed." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Warehouse id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "otp": { "type": "string", "description": "OTP received on the warehouse phone." } }, "required": [ "otp" ] }, "example": { "otp": "482913" } } } } } }, "/couriers": { "get": { "tags": [ "Couriers, Rates & Serviceability" ], "summary": "List available couriers + price", "description": "The same list the panel shows on \"Create Order\". Returns every courier you can book for a given mode and weight, with the exact amount that will be debited. Use the returned `courier_code` in POST /shipments.\n\n1. Call it with the parcel's `express_type`, `weight`, `payment_mode` and `order_amount`.\n2. Show the options to your user (or pick the cheapest `total`) and keep the chosen `courier_code`.\n3. A courier only appears when your rate card has a slab for exactly that weight. Empty list = no rate card / no slab for that weight.", "operationId": "couriers", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "express_type": "surface", "weight_kg": 0.5, "couriers": [ { "courier_name": "Delhivery", "courier_code": "Delhivery", "weight_slab": "0.5 KG", "freight": 60, "cod_charge": 30, "cod_percentage": 0, "gst": 16.2, "total": 106.2 } ] }, "note": "Only couriers with an active rate-card slab for exactly this weight are listed." } } } } }, "parameters": [ { "name": "express_type", "in": "query", "required": false, "description": "`surface` (default) or `air`.", "schema": { "type": "string" } }, { "name": "weight", "in": "query", "required": false, "description": "KG, default 0.5.", "schema": { "type": "number" } }, { "name": "payment_mode", "in": "query", "required": false, "description": "`Prepaid` (default) or `COD`.", "schema": { "type": "string" } }, { "name": "order_amount", "in": "query", "required": false, "description": "Needed for COD % fee.", "schema": { "type": "number" } } ] } }, "/rate-card": { "get": { "tags": [ "Couriers, Rates & Serviceability" ], "summary": "Get rate card", "description": "Your full active rate card(s): weight slabs, zones, forward/RTO rates and COD fees, grouped by courier.", "operationId": "rate-card", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": [ { "rate_card_id": 3, "courier": "Delhivery", "name": "Delhivery", "weight_slabs": [ { "id": 1, "label": "0.5 KG", "weight": 0.5 } ], "zones": [ { "id": 1, "zone_name": "Zone A" } ], "rates": { "surface": { "forward": { "0.5 KG": { "Zone A": { "base_rate": 60, "additional_rate": 50 } } } } }, "cod_rates": { "surface": { "forward": { "All Slabs": { "cod_charge": 30, "cod_percentage": 0 } } } } } ] } } } } } } }, "/calculate-rate": { "post": { "tags": [ "Couriers, Rates & Serviceability" ], "summary": "Calculate rate", "description": "Price one courier for one parcel. Weights above the largest slab are charged per extra 0.5 KG.", "operationId": "calc-rate", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "courier": "Delhivery", "weight_kg": 0.5, "mode": "surface", "payment_mode": "COD", "slab_matched": "0.5 KG", "breakdown": { "base_freight": 60, "cod_charge": 30, "taxable": 90, "gst_18pct": 16.2, "total_charge": 106.2 }, "note": "All amounts in INR. GST @ 18% is included in the total." } } } } }, "404": { "description": "No rate card / slab / rate entry for that courier or weight." }, "422": { "description": "Validation failed." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "courier_code": { "type": "string", "description": "Courier code or name." }, "weight": { "type": "number", "description": "KG, min 0.1." }, "express_type": { "type": "string", "description": "`surface` or `air`." }, "payment_mode": { "type": "string", "description": "`Prepaid` or `COD`." }, "order_amount": { "type": "number", "description": "Required for COD." } }, "required": [ "courier_code", "weight", "express_type", "payment_mode" ] }, "example": { "courier_code": "Delhivery", "weight": 0.5, "express_type": "surface", "payment_mode": "COD", "order_amount": 1499 } } } } } }, "/pincode/{pincode}": { "get": { "tags": [ "Couriers, Rates & Serviceability" ], "summary": "Check pincode serviceability", "description": "Delhivery serviceability for a pincode (prepaid / COD / pickup / reverse). Use it as a pre-check before offering shipping at checkout.", "operationId": "pin-one", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "pincode": "122001", "success": true, "serviceable": true, "message": "Serviceable" } } } }, "422": { "description": "Invalid pincode." } }, "parameters": [ { "name": "pincode", "in": "path", "required": true, "description": "6 digits.", "schema": { "type": "string" } } ] } }, "/pincode/bulk": { "post": { "tags": [ "Couriers, Rates & Serviceability" ], "summary": "Bulk pincode check", "description": "", "operationId": "pin-bulk", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "total": 2, "serviceable": 2, "not_serviceable": 0, "results": [ { "pincode": "110001", "success": true, "serviceable": true } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pincodes": { "type": "array", "description": "1\u201350 six-digit pincodes.", "items": {} } }, "required": [ "pincodes" ] }, "example": { "pincodes": [ "110001", "400001" ] } } } } } }, "/shipments": { "post": { "tags": [ "Shipments" ], "summary": "Create shipment", "description": "Books the shipment with the courier, debits your wallet and returns the AWB. This runs the exact same logic as the panel's Create Order, so wallet/credit checks, commission and courier rules behave identically.\n\n1. Have a synced warehouse (`pick_address_id`) \u2014 see Warehouses.\n2. Call GET /couriers for this weight/mode to get a valid `courier_code` and the price.\n3. POST /shipments. On success you get `waybill` (AWB) immediately and the wallet is debited `shipping_charge.total`.\n4. Fetch the label with GET /shipments/{id}/label and give the parcel to the courier.\n5. Track with webhooks (recommended) or GET /shipments/{id}/track.\n6. No AWB from the courier means no order and no charge \u2014 the call fails with 422.\n7. Safe retries: always send your own `client_order_id`. If the first attempt actually succeeded, the retry returns 409 with the existing shipment instead of booking twice.", "operationId": "ship-create", "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Shipment created successfully.", "data": { "order_id": 1024, "client_order_id": "MY-ORD-2001", "waybill": "1234567891", "courier_code": "Delhivery", "order_status": "manifested", "shipping_charge": { "base": 60, "cod": 30, "gst": 16.2, "total": 106.2 }, "wallet_balance": 1393.8 } } } } }, "402": { "description": "Insufficient wallet balance (wallet + approved credit). `data.required_amount` / `available_amount` included." }, "403": { "description": "Account type cannot create shipments via API." }, "409": { "description": "client_order_id already exists (existing shipment returned in `data`)." }, "422": { "description": "Validation failed, unknown/inactive courier_code, unknown pickup or return address, or the courier rejected the order (message explains why)." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "consignee_name": { "type": "string", "description": "Receiver name (max 200)." }, "consignee_mobile": { "type": "string", "description": "Receiver phone, 10 digits (max 15 chars)." }, "consignee_address1": { "type": "string", "description": "Address line 1." }, "consignee_address2": { "type": "string", "description": "Address line 2 / landmark." }, "consignee_pincode": { "type": "string", "description": "Exactly 6 digits." }, "consignee_city": { "type": "string", "description": "Strongly recommended \u2014 some couriers reject blank city." }, "consignee_state": { "type": "string", "description": "Strongly recommended \u2014 some couriers reject blank state." }, "consignee_email": { "type": "string", "description": "Valid email. Recommended for Amazon Shipping." }, "payment_mode": { "type": "string", "description": "`Prepaid` or `COD` (case-sensitive)." }, "order_amount": { "type": "number", "description": "Invoice value in INR. For COD this is also the amount collected." }, "pick_address_id": { "type": "string", "description": "`pick_address_id` of one of your warehouses (GET /warehouses)." }, "return_address_id": { "type": "string", "description": "Warehouse to receive RTOs. Defaults to the pickup warehouse." }, "express_type": { "type": "string", "description": "`surface` or `air`. Must match the courier option you pick." }, "courier_code": { "type": "string", "description": "A `courier_code` from GET /couriers for this express_type and weight." }, "shipment_weight": { "type": "number", "description": "Dead weight in KG, min 0.1. Must match a slab on your rate card." }, "shipment_length": { "type": "number", "description": "cm." }, "shipment_width": { "type": "number", "description": "cm." }, "shipment_height": { "type": "number", "description": "cm." }, "client_order_id": { "type": "string", "description": "Your own order number (max 100). Must be unique among your non-cancelled shipments \u2014 a duplicate returns 409, which makes retries safe. Auto-generated (`API-XXXXXXXX`) when omitted." }, "invoice_number": { "type": "string", "description": "Printed on label/invoice (max 100)." }, "address_type": { "type": "string", "description": "`Home`, `Office` or `Other`. Default Home." }, "products": { "type": "array", "description": "Items: `product_name` (required per item), `product_quantity`, `product_price`, `sku`. A single \"Product\" line is used when omitted.", "items": {} } }, "required": [ "consignee_name", "consignee_mobile", "consignee_address1", "consignee_pincode", "payment_mode", "order_amount", "pick_address_id", "express_type", "courier_code", "shipment_weight" ] }, "example": { "client_order_id": "MY-ORD-2001", "invoice_number": "INV-2001", "consignee_name": "Rahul Sharma", "consignee_mobile": "9876543210", "consignee_email": "rahul@example.com", "consignee_address1": "Flat 12, Green Park Apartments", "consignee_address2": "Sector 15", "consignee_pincode": "122001", "consignee_city": "Gurugram", "consignee_state": "Haryana", "address_type": "Home", "payment_mode": "COD", "order_amount": 1499, "pick_address_id": "Main Warehouse", "return_address_id": "Main Warehouse", "express_type": "surface", "courier_code": "Delhivery", "shipment_weight": 0.5, "shipment_length": 20, "shipment_width": 15, "shipment_height": 10, "products": [ { "product_name": "Cotton T-Shirt", "product_quantity": 2, "product_price": 749.5, "sku": "TSH-001" } ] } } } } }, "get": { "tags": [ "Shipments" ], "summary": "List shipments", "description": "", "operationId": "ship-list", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "items": [ { "id": 1024, "client_order_id": "MY-ORD-2001", "waybill": "1234567891", "order_status": "in_transit", "payment_mode": "COD", "order_amount": 1499, "cod_amount": 1499, "shipping_charge": 70.8, "courier_code": "Delhivery", "express_type": "surface", "pick_address_id": "Main Warehouse", "created_at": "2026-10-01 11:20:05" } ], "total": 1, "per_page": 20, "current_page": 1, "last_page": 1 } } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Exact `order_status` (see Status reference).", "schema": { "type": "string" } }, { "name": "payment_mode", "in": "query", "required": false, "description": "`Prepaid` / `COD`.", "schema": { "type": "string" } }, { "name": "waybill", "in": "query", "required": false, "description": "Exact AWB.", "schema": { "type": "string" } }, { "name": "client_order_id", "in": "query", "required": false, "description": "Partial match.", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Max 100, default 20.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } } ] } }, "/shipments/bulk": { "post": { "tags": [ "Shipments" ], "summary": "Bulk create (up to 50)", "description": "Creates many shipments in one call. Each order is processed independently with the same rules as single create; one failure does not stop the rest.\n\n1. Send `orders`: an array of up to 50 objects, each with the same fields as Create shipment.\n2. Read `data.succeeded` and `data.failed` (each failure has `index` + `reason`). HTTP 201 if at least one order was created, 422 if none.\n3. Always set `client_order_id` on each order so you can match results and retry only the failed ones.", "operationId": "ship-bulk", "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "1 order(s) created, 1 failed.", "data": { "succeeded": [ { "order_id": 1024, "client_order_id": "MY-ORD-2001", "waybill": "1234567891" } ], "failed": [ { "index": 1, "client_order_id": "MY-ORD-2002", "reason": "Pickup address not found. Please use a valid pick_address_id from your warehouses." } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "description": "1\u201350 order objects (same schema as Create shipment).", "items": {} } }, "required": [ "orders" ] }, "example": { "orders": [ { "client_order_id": "MY-ORD-2001", "invoice_number": "INV-2001", "consignee_name": "Rahul Sharma", "consignee_mobile": "9876543210", "consignee_email": "rahul@example.com", "consignee_address1": "Flat 12, Green Park Apartments", "consignee_address2": "Sector 15", "consignee_pincode": "122001", "consignee_city": "Gurugram", "consignee_state": "Haryana", "address_type": "Home", "payment_mode": "COD", "order_amount": 1499, "pick_address_id": "Main Warehouse", "return_address_id": "Main Warehouse", "express_type": "surface", "courier_code": "Delhivery", "shipment_weight": 0.5, "shipment_length": 20, "shipment_width": 15, "shipment_height": 10, "products": [ { "product_name": "Cotton T-Shirt", "product_quantity": 2, "product_price": 749.5, "sku": "TSH-001" } ] } ] } } } } } }, "/shipments/{id}": { "get": { "tags": [ "Shipments" ], "summary": "Get shipment", "description": "Full details of one shipment (consignee, dimensions, products, charges, refund and delivery info). `id` is the `order_id` returned at creation.", "operationId": "ship-show", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "id": 1024, "client_order_id": "MY-ORD-2001", "waybill": "1234567891", "order_status": "in_transit", "payment_mode": "COD", "order_amount": 1499, "cod_amount": 1499, "shipping_charge": 70.8, "courier_code": "Delhivery", "express_type": "surface", "pick_address_id": "Main Warehouse", "created_at": "2026-10-01 11:20:05", "invoice_number": "INV-2001", "consignee_name": "Rahul Sharma", "consignee_mobile": "9876543210", "consignee_address1": "Flat 12, Green Park", "consignee_address2": "Sector 15", "consignee_pincode": "122001", "consignee_city": "Gurugram", "consignee_state": "Haryana", "shipment_weight": 0.5, "shipment_length": 20, "shipment_width": 15, "shipment_height": 10, "products": [ { "product_name": "Cotton T-Shirt", "product_quantity": 2 } ], "extra_charges": 30, "tax_amount": 16.2, "refunded_amount": 0, "cancel_reason": null, "cancelled_at": null, "picked_up_at": null, "delivered_at": null, "label_printed": false, "channel": "api", "updated_at": "2026-10-01 11:20:05" } } } } }, "404": { "description": "Shipment not found." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "order_id.", "schema": { "type": "integer" } } ] } }, "/shipments/{id}/track": { "get": { "tags": [ "Shipments" ], "summary": "Track shipment", "description": "Status + scan history. Works for every courier (Delhivery, Shadowfax, Amazon Shipping, Nimbus Post) and returns the same shape. Without `sync` you get cached data (refreshed by courier webhooks); with `sync=1` we fetch live from the courier first.\n\n1. Prefer webhooks (order.status_updated) for real-time updates and use this for on-demand lookups.\n2. Pass `sync=1` to force a live refresh \u2014 this also updates the order status, NDR flags and delivery date.\n3. If the live call fails you still get the last cached data plus `data.sync_warning`.\n4. Event fields `event_date`, `status_code`, `status_description`, `status_location` are present for every courier; Delhivery events carry extra scan fields.", "operationId": "ship-track", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "order_id": 1024, "waybill": "1234567891", "courier_code": "Delhivery", "order_status": "in_transit", "is_ndr": false, "tracking": { "status": true, "synced_at": "2026-10-02 10:15:00", "current_status": { "status_code": "in_transit", "scan_type": "UD", "status_description": "Shipment in transit", "status_location": "Gurugram_Hub (Haryana)", "event_date": "2026-10-02T09:40:00" }, "tracking_events": [ { "event_date": "2026-10-02T09:40:00", "status_code": "in_transit", "scan_type": "UD", "status_location": "Gurugram_Hub (Haryana)", "status_description": "Shipment in transit" }, { "event_date": "2026-10-01T18:05:00", "status_code": "manifested", "scan_type": "UD", "status_location": "Delhi_Hub (Delhi)", "status_description": "Pickup done" } ], "estimated_delivery_date": "2026-10-04" } } } } } }, "404": { "description": "Shipment not found." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "order_id.", "schema": { "type": "integer" } }, { "name": "sync", "in": "query", "required": false, "description": "`1` = fetch live from the courier first.", "schema": { "type": "boolean" } } ] } }, "/shipments/{id}/label": { "get": { "tags": [ "Shipments" ], "summary": "Download label (PDF)", "description": "Returns the shipping label as a PDF file (`Content-Type: application/pdf`). It is the same document the panel prints \u2014 Amazon Shipping's own label for Amazon orders, your configured label template for the rest. Save the response body to a file.", "operationId": "ship-label", "responses": { "200": { "description": "PDF file", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Shipment not found." }, "422": { "description": "No AWB assigned yet." }, "502": { "description": "Label could not be generated." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "order_id.", "schema": { "type": "integer" } }, { "name": "format", "in": "query", "required": false, "description": "`url` returns JSON with a panel link instead of the PDF (needs a panel login to open).", "schema": { "type": "string" } } ] } }, "/shipments/labels": { "post": { "tags": [ "Shipments" ], "summary": "Bulk labels (one merged PDF)", "description": "Up to 100 labels merged into a single PDF. Orders without an AWB are skipped; the number included is in the `X-Label-Count` header.", "operationId": "ship-labels", "responses": { "200": { "description": "PDF file", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "None of the orders were found or have an AWB." }, "422": { "description": "Validation failed." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_ids": { "type": "array", "description": "1\u2013100 order ids.", "items": {} } }, "required": [ "order_ids" ] }, "example": { "order_ids": [ 1024, 1025 ] } } } } } }, "/shipments/{id}/invoice": { "get": { "tags": [ "Shipments" ], "summary": "Download invoice (PDF)", "description": "The order invoice rendered with your invoice settings.", "operationId": "ship-invoice", "responses": { "200": { "description": "PDF file", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Shipment not found." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "order_id.", "schema": { "type": "integer" } } ] } }, "/shipments/{id}/cancel": { "post": { "tags": [ "Shipments" ], "summary": "Cancel shipment", "description": "Cancels with the courier first; only if the courier accepts is the order cancelled locally and the freight refunded to your wallet.\n\n1. Works until the courier picks the parcel up / the shipment reaches a terminal state.\n2. A courier refusal returns 422 and leaves the order untouched \u2014 nothing is refunded.\n3. On success the `order.cancelled` webhook fires.", "operationId": "ship-cancel", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Shipment cancelled successfully.", "data": { "order_id": 1024, "waybill": "1234567891", "refunded_amount": 106.2, "wallet_balance": 1500, "courier_cancel": true } } } } }, "404": { "description": "Shipment not found." }, "422": { "description": "Not cancellable, or the courier rejected the cancellation." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "order_id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Stored as the cancel reason." } }, "required": [] }, "example": { "reason": "Customer changed mind" } } } } } }, "/shipments/bulk-cancel": { "post": { "tags": [ "Shipments" ], "summary": "Bulk cancel (up to 50)", "description": "", "operationId": "ship-bulk-cancel", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "1 order(s) cancelled, 1 failed.", "data": { "succeeded": [ { "order_id": 1024, "waybill": "1234567891", "refunded_amount": 106.2 } ], "failed": [ { "order_id": 1025, "reason": "Order is not cancellable (status: delivered)" } ], "wallet_balance": 1500 } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_ids": { "type": "array", "description": "1\u201350 order ids.", "items": {} }, "reason": { "type": "string", "description": "Cancel reason." } }, "required": [ "order_ids" ] }, "example": { "order_ids": [ 1024, 1025 ], "reason": "Out of stock" } } } } } }, "/ndr": { "get": { "tags": [ "NDR (Non-Delivery Reports)" ], "summary": "List NDR shipments", "description": "Shipments whose last delivery attempt failed and are waiting for your decision.\n\n1. Poll this, or react to `order.status_updated` webhooks where `is_ndr` is true.\n2. Pick an action per shipment (re-attempt or reschedule) using the action endpoints.", "operationId": "ndr-list", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "items": [ { "id": 1030, "client_order_id": "MY-ORD-2007", "waybill": "1234567899", "courier_code": "Delhivery", "consignee_name": "Rahul Sharma", "consignee_mobile": "9876543210", "consignee_city": "Gurugram", "consignee_pincode": "122001", "order_status": "pending", "is_ndr": true, "ndr_reason": "Consignee unavailable", "nsl_code": "EOD-6", "ndr_at": "2026-10-02 12:00:00", "ndr_action_type": null, "ndr_upl_id": null, "ndr_action_at": null, "payment_mode": "COD", "order_amount": 1499 } ], "total": 1, "per_page": 20, "current_page": 1, "last_page": 1 } } } } } }, "parameters": [ { "name": "action_status", "in": "query", "required": false, "description": "`pending` (no action yet) or `actioned`.", "schema": { "type": "string" } }, { "name": "nsl_code", "in": "query", "required": false, "description": "Filter by NSL reason code.", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "NDR date from.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "NDR date to.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Max 100.", "schema": { "type": "integer" } } ] } }, "/ndr/{id}/action": { "post": { "tags": [ "NDR (Non-Delivery Reports)" ], "summary": "Submit NDR action", "description": "Tells the courier what to do. Routed automatically to the shipment's courier (Delhivery, Shadowfax, Amazon Shipping, Nimbus Post).", "operationId": "ndr-action", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "NDR action submitted successfully.", "data": { "order_id": 1030, "waybill": "1234567899", "action": "RE-ATTEMPT", "upl_id": "UPL-8891", "action_at": "2026-10-02 14:00:00" } } } } }, "404": { "description": "Order not found." }, "422": { "description": "No active NDR / no AWB / courier rejected the action." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "order_id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "`RE-ATTEMPT` (deliver again) or `PICKUP_RESCHEDULE`." }, "remark": { "type": "string", "description": "Free text (max 500)." } }, "required": [ "action" ] }, "example": { "action": "RE-ATTEMPT" } } } } } }, "/ndr/bulk-action": { "post": { "tags": [ "NDR (Non-Delivery Reports)" ], "summary": "Bulk NDR action (up to 100)", "description": "", "operationId": "ndr-bulk", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "1 action(s) submitted, 1 failed.", "data": { "succeeded": [ { "order_id": 1030, "waybill": "1234567899", "upl_id": "UPL-8891" } ], "failed": [ { "order_id": 1031, "waybill": "1234567800", "reason": "API error" } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_ids": { "type": "array", "description": "1\u2013100 order ids.", "items": {} }, "action": { "type": "string", "description": "`RE-ATTEMPT` or `PICKUP_RESCHEDULE`." } }, "required": [ "order_ids", "action" ] }, "example": { "order_ids": [ 1030, 1031 ], "action": "RE-ATTEMPT" } } } } } }, "/ndr/sync": { "post": { "tags": [ "NDR (Non-Delivery Reports)" ], "summary": "Refresh NDR status", "description": "Re-checks your open shipments with their couriers and updates NDR flags. Delhivery shipments are refreshed in bulk; for the other couriers up to 40 shipments are refreshed per call. Normally unnecessary \u2014 courier webhooks keep this current.", "operationId": "ndr-sync", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Synced 57 orders.", "data": { "synced": 57 } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Max shipments to scan (default 200, max 500)." } }, "required": [] }, "example": { "limit": 200 } } } } } }, "/ndr/nsl-codes": { "get": { "tags": [ "NDR (Non-Delivery Reports)" ], "summary": "NSL reason codes", "description": "Lookup table of every NDR reason code (also listed in the Reference section).", "operationId": "ndr-nsl", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": [ { "nsl_code": "EOD-6", "remark": "Consignee unavailable" } ], "total": 102 } } } } } } }, "/wallet": { "get": { "tags": [ "Wallet & COD" ], "summary": "Wallet balance", "description": "Balance and credit limit. Recharge the wallet from the panel (Wallet \u2192 Add Money). Check `available_total` before bulk jobs.", "operationId": "wallet", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "wallet_balance": 1500, "wallet_credit": 0, "available_total": 1500, "currency": "INR", "note": "available_total = wallet_balance + wallet_credit. Shipping charges are deducted from available_total." } } } } } } } }, "/wallet/transactions": { "get": { "tags": [ "Wallet & COD" ], "summary": "Wallet transactions", "description": "", "operationId": "wallet-txn", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "items": [ { "id": 501, "transaction_id": "SHP-123456", "type": "debit", "payment_method": "wallet", "amount": 106.2, "balance_after": 1393.8, "reference": "Shipping charge for MY-ORD-2001", "created_at": "2026-10-01 11:20:05" } ], "total": 1, "per_page": 20, "current_page": 1, "last_page": 1 } } } } } }, "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Transaction type (e.g. debit, credit, refund).", "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "description": "Payment method.", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "required": false, "description": "Partial match on reference (e.g. an order id).", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "YYYY-MM-DD.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Max 100.", "schema": { "type": "integer" } } ] } }, "/cod-remittances/summary": { "get": { "tags": [ "Wallet & COD" ], "summary": "COD summary", "description": "", "operationId": "cod-summary", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "total_remitted_inr": 25000, "total_accruing_inr": 4200, "counts": { "pending": 2, "in_progress": 1, "completed": 14 } } } } } } } } }, "/cod-remittances": { "get": { "tags": [ "Wallet & COD" ], "summary": "List COD remittances", "description": "", "operationId": "cod-list", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "summary": { "total_remitted": 25000, "total_accruing": 4200 }, "items": [ { "id": 9, "cod_date": "2026-09-28", "settle_at_date": "2026-10-01", "settlement_days": 3, "charge_percent": 1.5, "total_cod_amount": 10000, "total_charge_amount": 150, "total_net_amount": 9850, "adjusted_in_wallet": 9850, "status": "completed", "status_label": "Completed", "awb_count": 8 } ], "total": 1, "per_page": 20, "current_page": 1, "last_page": 1 } } } } } }, "parameters": [ { "name": "from", "in": "query", "required": false, "description": "cod_date from.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "cod_date to.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "pending, in_progress, completed, settled, failed.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Max 100.", "schema": { "type": "integer" } } ] } }, "/cod-remittances/{id}": { "get": { "tags": [ "Wallet & COD" ], "summary": "COD remittance detail", "description": "One remittance with the AWBs it covers and the wallet transactions that settled it.", "operationId": "cod-show", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "id": 9, "cod_date": "2026-09-28", "status": "completed", "total_net_amount": 9850, "items": [ { "awb": "1234567891", "cod_amount": 1499, "charge": 22.49, "net_amount": 1476.51 } ], "transactions": [ { "adjust_via": "wallet", "wallet_transaction_ref": "COD-9", "opening_balance": 1500, "closing_balance": 11350, "transaction_amount": 9850, "created_at": "2026-10-01 06:00:00" } ] } } } } }, "404": { "description": "COD remittance not found." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Remittance id.", "schema": { "type": "integer" } } ] } }, "/webhook": { "get": { "tags": [ "Webhook configuration" ], "summary": "View webhook config", "description": "", "operationId": "wh-cfg-show", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "data": { "webhook_url": "https://yourapp.com/hooks/shipping", "webhook_secret": "***a1b2", "has_secret": true } } } } } } }, "post": { "tags": [ "Webhook configuration" ], "summary": "Save webhook config", "description": "Sets where events are delivered. Provide a `webhook_secret` (16\u201364 chars) or `auto_secret: true` to have one generated. The plaintext secret is returned only when it is set/created \u2014 store it.", "operationId": "wh-cfg-save", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Webhook configuration saved.", "data": { "webhook_url": "https://yourapp.com/hooks/shipping", "webhook_secret": "k3J\u202648chars" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": "string", "description": "Public HTTPS URL (max 500)." }, "webhook_secret": { "type": "string", "description": "16\u201364 chars; used to sign deliveries." }, "auto_secret": { "type": "boolean", "description": "Generate a random secret when none is given." } }, "required": [ "webhook_url" ] }, "example": { "webhook_url": "https://yourapp.com/hooks/shipping", "auto_secret": true } } } } }, "delete": { "tags": [ "Webhook configuration" ], "summary": "Remove webhook", "description": "", "operationId": "wh-cfg-del", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Webhook configuration removed." } } } } } } }, "/webhook/test": { "post": { "tags": [ "Webhook configuration" ], "summary": "Send test event", "description": "Fires a signed `webhook.test` event at your URL so you can verify signature handling.", "operationId": "wh-cfg-test", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "success": true, "message": "Test webhook dispatched to https://yourapp.com/hooks/shipping" } } } }, "422": { "description": "No webhook URL configured." } } } } } }