Skyfleet API

The Skyfleet API is a JSON REST API. All endpoints are relative to the base URL below and require authentication (except the public tracking endpoint). Use it to check rates, create and book shipments, track parcels, reconcile COD and wallet, handle NDR/returns, and receive real-time webhook events.

Base URL:  https://api.skyfleetnow.com/api/v1
Content-Type: application/json

All requests and responses are UTF-8 JSON. Timestamps are ISO-8601 (UTC). Monetary values are in INR (₹) unless a field name ends in Paise. Weights are in grams, dimensions in centimetres.

Authenticate every request with an API key. Generate one in the dashboard under Settings → Developer → API Keys. The full key (sf_live_…) is shown once at creation — store it securely; you can revoke and re-create at any time. A key is scoped to your organization.

Send it in the X-API-Key header:

curl https://api.skyfleetnow.com/api/v1/wallet \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Keep keys server-side only — never ship them in a browser, mobile app, or public repo. Rotate immediately if exposed (revoke the old key, create a new one).

What a key can reach

Everything documented on this page: shipments, rates and serviceability, tracking, sales-channel orders, COD, wallet balance and transactions, NDR, returns, webhooks, and listing or revoking keys. Account administration is dashboard-only — team members, settings, KYC, bank details, creating new keys, wallet top-ups and anything under /admin. A key that calls one of those gets 403 with "This endpoint is not available to API keys — use the dashboard".

Every response uses a consistent envelope.

Success

{ "success": true, "data": { ... }, "message": "optional" }

Paginated list

{
  "success": true,
  "data": [ ... ],
  "meta": { "total": 120, "page": 1, "limit": 20, "totalPages": 6 }
}

List endpoints accept page (default 1) and limit (default 20).

Error

{ "success": false, "message": "Human-readable reason", "errors": { "field": ["..."] } }

Error codes

Every order and booking error has the form "<Title>: <reason>. <what to do>" and a code: in data.booking.code when you create with book: true, otherwise in the code field of the error response.

• ShipmentStatus: CREATED, LABEL_GENERATED, PICKUP_SCHEDULED, PICKUP_FAILED, PICKED_UP, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, DELIVERY_FAILED, RTO_INITIATED, RTO_IN_TRANSIT, RTO_DELIVERED, CANCELLED, LOST, DAMAGED
• PaymentMode: PREPAID, COD
• ShipmentType: FORWARD, REVERSE, EXCHANGE
• NdrAction: REATTEMPT, RTO, CHANGE_ADDRESS, CONTACT_CUSTOMER

POST /shipments creates a draft (status CREATED, no AWB, no charge). Booking a draft (assigning a courier + AWB) is gated:

• Your organization's KYC must be APPROVED (else 403).
• A wallet must be configured (else 402); prepaid wallets must cover the freight.

Complete KYC and top up your wallet in the dashboard before booking via API.

curl https://api.skyfleetnow.com/api/v1/rates/calculate -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{
    "pickupPincode": "110011",
    "dropPincode": "400001",
    "weightGrams": 500,
    "paymentMode": "PREPAID",
    "lengthCm": 20, "breadthCm": 15, "heightCm": 10,
    "invoiceValue": 1499
  }'

// 200 → data: [
  {
    "courier": "Delhivery Surface", "carrierId": "delhivery-surface",
    "zone": "METRO", "chargeableWeightGrams": 500,
    "baseRate": 46.61, "codCharge": 0, "gstAmount": 12.05,
    "totalCharge": 78.95, "eddDays": 3, "isAvailable": true
  }
]

curl https://api.skyfleetnow.com/api/v1/shipments -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{
    "shipmentType": "FORWARD",
    "paymentMode": "COD",
    "orderReferenceNumber": "ORD-1042",
    "invoiceValue": 1499,
    "codAmount": 1499,
    "pickup": {
      "name": "Acme Warehouse", "phone": "9876543210",
      "address": "Plot 4, Industrial Area", "city": "New Delhi",
      "state": "Delhi", "pincode": "110011"
    },
    "drop": {
      "name": "Ravi Kumar", "phone": "9812345678",
      "address": "12 MG Road", "city": "Mumbai",
      "state": "Maharashtra", "pincode": "400001"
    },
    "packages": [{
      "weightGrams": 500, "lengthCm": 20, "breadthCm": 15, "heightCm": 10,
      "items": [{ "name": "Cotton T-Shirt", "sku": "TS-01", "quantity": 1, "unitPrice": 1499 }]
    }]
  }'

// 201 → data: { "shipment": { "id": "...", "status": "CREATED", ... } }

Required: shipmentType, paymentMode, invoiceValue, pickup, drop, packages (≥1, each with weight + dimensions + items). codAmount is required for COD. orderReferenceNumber must be unique among live orders — a duplicate returns 409 unless you pass "allowDuplicate": true. You can reference a saved pickup with pickupAddressId instead of an inline pickup object.

One call instead of two: create and book together

Add "book": true to the same payload and the draft is booked in the same request — the response carries the AWB, courier and label URL. The two-step flow (create, then POST /shipments/:id/book) keeps working exactly as before. There are three ways to choose the courier:

// Option 1 — a specific courier, by carrierId from a rate quote (recommended)
// POST /rates/calculate returns one option per serviceable courier; copy its carrierId.
// It is the exact service code, so it fixes Air vs Surface as well.
{ ...order fields..., "book": true, "carrierId": "delhivery-surface" }

// Option 2 — by brand, no quote needed (serviceType optional: SURFACE | AIR)
// Brands: DELHIVERY, BLUEDART, XPRESSBEES, EKART, DTDC, ECOM_EXPRESS, SHADOWFAX,
//         SMARTR, FEDEX, PROFESSIONAL_COURIER, AMAZON_SHIPPING (those enabled on your account)
{ ...order fields..., "book": true, "carrierBrand": "XPRESSBEES", "serviceType": "AIR" }

// Option 3 — auto-allocate: cheapest serviceable courier under your allocation rules, with fail-over
{ ...order fields..., "book": true }

// Rules: send carrierId OR carrierBrand. If both are present, carrierBrand wins.
// A carrierId that matches no active courier on your account falls back to auto-allocation.

curl https://api.skyfleetnow.com/api/v1/shipments -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{ ...same fields as above..., "book": true, "carrierId": "delhivery-surface" }'

// 201 → data: { "shipment": { "id": "...", "status": "LABEL_GENERATED", "awbNumber": "77812345678",
//                             "sortCode": "DEL/OKH",   // courier sort code, null if none
//                             "labelUrl": "https://…", "courierName": "Delhivery Surface", ... },
//               "booking": { "status": "booked" } }

// If booking fails, the draft still exists — still 201:
// data: { "shipment": { "id": "...", "status": "CREATED", ... },
//         "booking": { "status": "failed", "error": "Insufficient wallet balance", "code": null, "httpStatus": 402 } }
// → fix the cause, then POST /shipments/{id}/book (with another carrierId if the courier could not serve the lane)

Pincodes must be serviceable. Both pincodes are checked when the order is created: if either is not in Skyfleet's pincode list the request is refused with 400 and a message naming the incorrect pincode, so the order never becomes a draft that fails at booking. Surrounding whitespace is stripped automatically. If a real pincode is rejected, contact support to have it added and resubmit.

curl https://api.skyfleetnow.com/api/v1/shipments/SHIP_ID/book -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{ "carrierId": "bluedart-air" }'          // exact rate code (recommended)
  // — OR —  -d '{ "carrierBrand": "DELHIVERY" }' // courier brand
  // — OR —  omit the body entirely to auto-allocate

// 200 → data: { "id": "...", "awbNumber": "...", "carrierId": "bluedart-air", "status": "LABEL_GENERATED",
//               "labelUrl": "https://api.skyfleetnow.com/api/v1/shipments/SHIP_ID/label.pdf", ... }
// labelUrl is a Skyfleet-branded label link — fetch it with your X-API-Key header (follows a redirect to the PDF).

Both fields are accepted (this resolves the earlier docs-vs-Postman ambiguity):

• carrierId — the exact rate code incl. service (e.g. bluedart-air / bluedart-surface). Recommended — take it from /rates/calculate, which preserves the Air vs Surface pick.
• carrierBrand — the courier brand (e.g. DELHIVERY, BLUEDART_AIR). Uppercase provider-account form.

Send either one. If both are present, carrierBrand selects the brand and carrierId refines the service. Omit both to auto-allocate by your allocation rules.

All carrierId values

Uppercase forms (BLUEDART_AIR, …) also work. If a carrierId isn't serviceable/priced for that lane + merchant, the booking returns a clear error rather than silently switching couriers.

status takes a single ShipmentStatus (see Enums). For broad buckets use statusGroup:

Also: hasAwb=yes|no (booked vs draft), unprocessed=yes (drafts needing action).

{
  "totalWeight": 2.5,
  "totalLength": 30,
  "totalBreadth": 20,
  "totalHeight": 15,
  "items": [
    { "itemName": "Cotton T-Shirt", "sku": "TS-001", "quantity": 1, "unitPrice": 500 }
  ]
}

Orders synced from a connected store (Shopify, Amazon, WooCommerce, etc.) are a separate resource from shipments. They live under /channels/orders. A channel order only appears under /shipments after it's imported — so if you're looking for freshly-synced store orders, use the endpoints here, not /shipments.

curl "https://api.skyfleetnow.com/api/v1/channels/orders?status=NEW" -H "X-API-Key: sf_live_…"

// 200 → data: [
  {
    "id": "co_abc", "externalOrderId": "5521", "externalOrderNumber": "#1042",
    "customerName": "Ravi Kumar", "destinationCity": "Mumbai", "destinationPincode": "400001",
    "paymentMode": "COD", "totalValue": 1499, "status": "NEW",
    "integration": { "name": "My Shopify Store", "type": "SHOPIFY" },
    "shipmentId": null, "shipmentStatus": null, "shipmentAwb": null
  }
], "meta": { "total": 12, "page": 1, "limit": 20, "totalPages": 1 }

status values: NEW (synced, not yet imported), IMPORTED, SKIPPED, FAILED, CANCELLED_ON_CHANNEL.

curl "https://api.skyfleetnow.com/api/v1/channels/orders/co_abc/book" -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{ "carrierId": "bluedart-air" }'   // optional; omit to auto-allocate

// 200 → data: { "channelOrderId":"co_abc", "shipmentId":"ship_x", "awbNumber":"77812345678", "shipment": { ... } }

Typical flow: pull store orders → ship

GET  /channels/orders?status=NEW          → un-imported synced orders
POST /channels/orders/{id}/import         → creates a draft shipment (returns shipmentId)
POST /shipments/{id}/book                 → book it (returns AWB)

// One-shot alternative:
POST /channels/orders/bulk-import   { "orderIds": ["co_abc"], "mode": "book" }

Orders sync but don't auto-import? Turn on auto-create

By default, synced orders sit as NEW in the channel-order feed until you import them. To have Skyfleet auto-create a draft shipment for every incoming order, enable autoCreateShipments on the integration (and set a default pickup, since a shipment needs one):

curl "https://api.skyfleetnow.com/api/v1/channels/INTEGRATION_ID" -X PATCH \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{
    "autoCreateShipments": true,
    "defaultPickupAddressId": "addr_123",   // required for auto-create
    "defaultPaymentMode": "COD",            // optional fallback
    "defaultWeightGrams": 500,              // optional fallback
    "initialSyncDays": 30
  }'

Get integration IDs from GET /channels, and pickup-address IDs from GET /shipments/pickup-addresses. With autoCreateShipments off, orders stay in the feed and you import them yourself (above). Either way, auto-create produces drafts — call /shipments/:id/book to book, or use bulk-import with mode:"book".

curl https://api.skyfleetnow.com/api/v1/public/track/DL1234567890

// 200 → data: {
  "awbNumber": "DL1234567890", "status": "OUT_FOR_DELIVERY",
  "courier": "Delhivery", "customerName": "Ravi K.",
  "timeline": { "orderedAt": "...", "pickedUpAt": "...", "deliveredAt": null, "expectedDeliveryDate": "..." },
  "events": [ { "status": "OUT_FOR_DELIVERY", "description": "...", "location": "Mumbai", "eventTime": "..." } ]
}

For most integrations, prefer webhooks over polling — you get pushed a status event the moment it changes.

Filters: status, reason, page, limit, plus awb and orderReferenceNumber(substring match) to fetch the NDR event(s) for a specific shipment — e.g. /ndr?orderReferenceNumber=ORD-1042 or /ndr?awb=DL1234567890.

Where ndrEventId comes from: Skyfleet creates one NDR event per failed delivery attempt. Call GET https://api.skyfleetnow.com/api/v1/ndr?awb=<AWB> and use the id of the newest event that is still open (PENDING, ACTION_TAKEN or REATTEMPT_SCHEDULED). It is not the AWB, shipment id or order reference. A typical flow: the shipment.delivery_failed webhook arrives, you fetch the NDR for that AWB, then act on it.

curl "https://api.skyfleetnow.com/api/v1/ndr?awb=50845018205256" -H "X-API-Key: sf_live_…"

// 200 → { "success": true, "data": [ {
//   "id": "cmw1ndr8x0012ab34cd56ef78",     // ← this is the ndrEventId
//   "awbNumber": "50845018205256", "attemptNumber": 1,
//   "ndrReason": "CUSTOMER_NOT_AVAILABLE", "status": "PENDING", "location": "Mumbai_Andheri_DC", ...
// } ], "meta": { "total": 1, "page": 1, "limit": 20 } }

curl https://api.skyfleetnow.com/api/v1/ndr/action -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{
    "ndrEventId": "NDR_ID",
    "action": "REATTEMPT",          // or RTO | CHANGE_ADDRESS | CONTACT_CUSTOMER
    "preferredDate": "2026-07-12",
    "notes": "Customer will be home after 5pm"
  }'

For action: "CHANGE_ADDRESS", also send the corrected consignee details:

  -d '{
    "ndrEventId": "NDR_ID",
    "action": "CHANGE_ADDRESS",
    "newAddress": "12 MG Road, Indiranagar",   // REQUIRED
    "newPincode": "560038",                     // REQUIRED (6-digit)
    "newCity": "Bengaluru",                     // optional
    "newState": "Karnataka",                    // optional
    "newPhone": "9876543210"                    // optional — corrected contact
  }'
// To change ONLY the phone: resend the current address in newAddress/newPincode with the new newPhone.

curl https://api.skyfleetnow.com/api/v1/rvp/from-forward -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{
    "forwardAwb": "DL1234567890",              // or "forwardShipmentId"
    "orderReferenceNumber": "RET-1042",        // optional — YOUR ref, echoed in webhooks
    "isQcRequired": false,                       // default (defaults to "<forward-ref>-RVP")
    "reasonForReturn": "Size mismatch"
  }'

// → returns a REVERSE shipment draft; book it to schedule the pickup.

The addresses are swapped automatically (customer → pickup, your warehouse → drop). Pass orderReferenceNumber to set your own reference — it's echoed back on every webhook for the reverse shipment, exactly like forward orders.

curl https://api.skyfleetnow.com/api/v1/rvp/create -X POST \
  -H "X-API-Key: sf_live_…" -H "Content-Type: application/json" \
  -d '{
    "orderReferenceNumber": "RET-9001",         // optional — YOUR ref, echoed in webhooks
    "pickup": {                                  // where the courier collects (the customer)
      "name": "Asha R", "phone": "9876543210",
      "address": "12 MG Road", "city": "Bengaluru", "state": "Karnataka", "pincode": "560038"
    },
    "drop": {                                    // where it returns to (your warehouse)
      "name": "Acme Returns", "phone": "9000000000",
      "address": "Plot 4, Sector 8", "city": "Gurugram", "state": "Haryana", "pincode": "122001"
    },
    "items": [{ "itemName": "Blue Kurta", "sku": "KUR-BLU-M", "quantity": 1, "unitPrice": 899 }],
    "isQcRequired": false,
    "weightKg": 0.5                              // optional (default 0.5); dimensionsCm optional
  }'

// → returns a REVERSE shipment draft; book it with POST /shipments/:id/book.

Doorstep QC (quality check)

Set isQcRequired: true on either create call to have the pickup agent inspect the item at the doorstep before accepting it. To give the agent something to check against, pass each item's imageUrl — it's forwarded to the courier as the reference photo:

"items": [
  {
    "itemName": "Blue Kurta", "sku": "KUR-BLU-M",
    "quantity": 1, "unitPrice": 899,
    "imageUrl": "https://cdn.yourstore.com/kur-blu-m.jpg",   // QC reference photo
    "color": "Blue", "brand": "Acme", "hsnCode": "6104"      // all optional
  }
]

When the item fails QC, the reverse shipment carries the result — readable on GET /shipments/:id and pushed on shipment.delivery_failed:

{
  "qcStatus": "fail",                       // "passed" | "fail" | "fail_hub" | null
  "qcRemarks": "Brand tag missing; colour mismatch",
  "qcImages": ["https://…/qc-1.jpg", "https://…/qc-2.jpg"],   // photos taken at the door
  "qcCheckedAt": "2026-08-18T10:22:05.000Z"
}

Booking a reverse shipment (POST /shipments/:id/book) rate-shops only the reverse (RVP) courier lane — forward couriers are never offered for a return.

Instead of polling, subscribe to events and Skyfleet will POST them to your URL the moment they happen. Create and manage endpoints in the dashboard under Settings → Webhooks (set a URL, pick events, get a signing secret).

Events

shipment.created            shipment.out_for_delivery
shipment.label_generated    shipment.delivered
shipment.pickup_scheduled   shipment.delivery_failed
shipment.pickup_failed      shipment.rto_initiated
shipment.picked_up          shipment.rto_in_transit
shipment.in_transit         shipment.rto_delivered
shipment.cancelled          shipment.lost
shipment.damaged

One event per shipment status. Every payload echoes your orderReferenceNumber (and awbNumber), so you can reconcile against your own order — including reverse shipments. Note: shipment.created is subscribable but not currently emitted (a shipment first surfaces on shipment.label_generated, i.e. once it's booked). shipment.pickup_failed fires when the courier attempts and fails a pickup; the courier re-attempts it.

Replay a real shipment (testing)

POST https://api.skyfleetnow.com/api/v1/webhooks/replay with { "awbNumber": "..." } re-sends that shipment's current status to every active subscription, as a normal signed webhook with the full data.tracking history. awbNumber also accepts the shipment number or your order reference. Earlier statuses arrive inside data.tracking.events, not as separate webhooks. To check your endpoint is reachable first, use POST https://api.skyfleetnow.com/api/v1/webhooks/:id/test (a test.ping).

curl -X POST https://api.skyfleetnow.com/api/v1/webhooks/replay \
  -H "X-API-Key: sf_live_..." -H "Content-Type: application/json" \
  -d '{ "awbNumber": "50845018127954" }'

// 200 → { "success": true, "data": { "awbNumber": "50845018127954", "status": "PICKUP_FAILED" } }

Payload

POST <your-url>
Headers:
  X-Skyfleet-Event: shipment.delivered
  X-Skyfleet-Signature: <hmac-sha256 hex of the raw body>
  X-Skyfleet-Delivery-Attempt: 1

Body:
{
  "success": true,
  "event": "shipment.delivered",
  "timestamp": "2026-07-08T09:15:00.000Z",
  "data": {
    "shipment": {                          // fields are nested under data.shipment
      "id": "ckv…",
      "shipmentNumber": "SKY100234",
      "awbNumber": "DL1234567890",
      "sortCode": "DEL/OKH",                // courier sort code, null if none
      "orderReferenceNumber": "ORD-1042",
      "shipmentType": "FORWARD",
      "status": "DELIVERED",
      "paymentMode": "COD",
      "courier": "Delhivery",
      "codAmount": 1499,
      "deliveredAt": "2026-07-08T09:14:55.000Z",
      "lastStatusUpdate": "2026-07-08T09:14:55.000Z",
      "expectedDeliveryDate": "2026-07-09T00:00:00.000Z",
      "revisedDeliveryDate": null,
      "chargedWeight": 0.5,                // kg, at booking
      "billedWeight": null,                // kg, after courier re-weigh
      "..." : "..."
    },
    "tracking": {                          // same shape as GET /shipments/{awb}/track
      "awb_number": "DL1234567890",
      "courier": "Delhivery",
      "current_status": "DELIVERED",
      "events": [                          // oldest first
        {
          "status": "PICKED_UP",            // Skyfleet status
          "status_code": "60",
          "description": "Shipment picked up",
          "remarks": "Shipment picked up",   // same text as description
          "location": "Faridabad_MathuraRoad_GW (Haryana)",
          "timestamp": "2026-07-06T11:02:10.000Z",
          "raw_status": "Picked Up",        // courier's own wording
          "raw_status_code": "60"
        },
        { "status": "DELIVERED", "status_code": "100", "description": "Delivered to consignee", "...": "..." }
      ]
    }
  }
}

data.tracking is the shipment's full recorded history at the time the webhook is sent, so you don't need a follow-up call to the tracking API. Each event carries a Skyfleet status plus the courier's raw_status / raw_status_code, description (also sent as remarks), location and timestamp. A webhook fires once per status change, not on every courier scan, so scans between two status changes arrive in the next webhook's history. data.tracking is null only if the history couldn't be read; the status webhook is still sent.

Verify the signature

Compute an HMAC-SHA256 of the raw request body using your endpoint's secret and compare (constant-time) to the X-Skyfleet-Signature header. Reject if they differ.

// Node.js (Express)
import crypto from "crypto";

app.post("/skyfleet-webhook", express.raw({ type: "*/*" }), (req, res) => {
  const expected = crypto.createHmac("sha256", process.env.SKYFLEET_WEBHOOK_SECRET)
    .update(req.body)                    // raw Buffer, not parsed JSON
    .digest("hex");
  const got = req.headers["x-skyfleet-signature"];
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(String(got)))) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body.toString());
  // ... handle event.event / event.data ...
  res.sendStatus(200);                   // 2xx = acknowledged
});

Respond 2xx to acknowledge. Non-2xx, timeouts, and network errors are retried with backoff (4xx is treated as a caller bug and not retried). Every attempt is logged in Settings → Webhooks → Deliveries, where you can inspect and manually retry.