shippingservice/documentation/ekart/api_spec.md
vignesh 79554b7d62
Some checks failed
Deploy Beta (NATIVE) / deploy (push) Failing after 35s
Add Ekart API documentation and standalone ekart Django module
2026-09-30 12:09:47 +05:30

10 KiB

Ekart Logistics API Specification

  • Version: 3.8.10
  • Base URL: https://app.elite.ekartlogistics.in

1. Authentication

Get Access Token

POST /integrations/v2/auth/token/{client_id}

Use this API call to fetch an access_token valid for expires_in seconds (generally 24 hours). This API works for both v1 and v2 endpoints. It caches and returns the same token within the 24-hour window.

Path Parameters

Parameter Type Required Description
client_id string Yes Client ID provided by Ekart during onboarding

Request Body

{
  "username": "your_username",
  "password": "your_password"
}

Response (200 OK)

{
  "access_token": "abc123xyz...",
  "scope": "core:all",
  "expires_in": 86400,
  "token_type": "Bearer"
}

2. Shipments

2.1 Create Shipment

PUT /api/v1/package/create

Header

Authorization: Bearer <access_token>

Shipment Types & Operational Rules

  1. Forward Shipments (Seller \rightarrow Customer)

    • payment_mode: COD or Prepaid
    • return_reason: Not required
    • drop_location: Customer address (drop_location.name generally equals consignee_name)
    • pickup_location: Seller warehouse/pickup address
    • return_location: RTO address (defaults to pickup_location if omitted)
    • service: SURFACE or EXPRESS
    • preferred_dispatch_date: Optional YYYY-MM-DD date
    • delayed_dispatch: Boolean (true allows setting dispatch date post-creation)
  2. Reverse Shipments (Customer \rightarrow Seller)

    • payment_mode: Pickup
    • return_reason: String reason (e.g. "Wrong product sent")
    • drop_location: Customer address
    • pickup_location: Seller address
  3. Multi-package Forward Shipments (MPS)

    • mps: true
    • Top-level length, width, height, weight are ignored.
    • Specify items array and package details inside payload.
  4. Open Box Delivery (OBD)

    • obd_shipment: true
  5. Reverse Shipments with Quality Check (QC)

    • qc_details: { "qc_shipment": true, "product_name": "Product Name", ... }

Request Body (#/components/schemas/shipment)

{
  "seller_name": "Seller Brand Name",
  "seller_address": "Seller Billing Address",
  "seller_gst_tin": "29ABCDE1234F1Z5",
  "seller_gst_amount": 18.0,
  "consignee_name": "Customer Name",
  "consignee_alternate_phone": "9876543210",
  "consignee_gst_amount": 0.0,
  "order_number": "ORD-2026-001",
  "invoice_number": "INV-2026-001",
  "invoice_date": "2026-01-30",
  "products_desc": "Men T-Shirt",
  "category_of_goods": "Apparel",
  "payment_mode": "Prepaid",
  "total_amount": 500.0,
  "taxable_amount": 423.72,
  "tax_value": 76.28,
  "commodity_value": "423.72",
  "cod_amount": 0.0,
  "quantity": 1,
  "weight": 500,
  "length": 15,
  "width": 10,
  "height": 5,
  "service": "SURFACE",
  "return_reason": "",
  "drop_location": {
    "name": "Customer Name",
    "phone": 9876543210,
    "address": "123 Main Street, Sector 5",
    "city": "Bengaluru",
    "state": "Karnataka",
    "country": "India",
    "pin": 560001
  },
  "pickup_location": {
    "name": "Warehouse_Alias_1",
    "phone": 9123456789,
    "address": "Plot 42, Industrial Area",
    "city": "Bengaluru",
    "state": "Karnataka",
    "country": "India",
    "pin": 560067
  },
  "return_location": {
    "name": "Warehouse_Alias_1",
    "phone": 9123456789,
    "address": "Plot 42, Industrial Area",
    "city": "Bengaluru",
    "state": "Karnataka",
    "country": "India",
    "pin": 560067
  }
}

Response (200 OK)

{
  "status": true,
  "remark": "Successfully created shipment",
  "tracking_id": "500999A3408005",
  "vendor": "EKART",
  "barcodes": {
    "wbn": "vendor_waybill_plain_text",
    "order": "ORD-2026-001",
    "cod": ""
  }
}

2.2 Cancel Shipment

DELETE /api/v1/package/cancel?tracking_id={tracking_id}

Query Parameters

  • tracking_id (string, required): The shipment ID to cancel.

Response (200 OK)

{
  "data": [
    {
      "status": true,
      "remark": "Shipment cancelled successfully",
      "tracking_id": "500999A3408005"
    }
  ]
}

2.3 Set Preferred Dispatch Date

POST /data/shipment/dispatch-date

Used when delayed_dispatch was set to true during shipment creation.

Request Body

{
  "ids": ["500999A3408005"],
  "dispatchDate": "2026-02-15"
}

2.4 Update E-Way Bill (EWBN)

POST /data/shipment/ewbn

Request Body

{
  "id": "500999A3408005",
  "ewbn": "412345678901"
}

3. Label & Manifest Downloads

3.1 Download Packing Label

POST /api/v1/package/label?json_only={true|false}

Query Parameters

  • json_only (boolean, optional): If true, returns JSON data instead of PDF binary stream.

Request Body

{
  "ids": [
    "500999AT876841",
    "500999AT876842"
  ]
}

(Max 100 tracking IDs per call)

Response

  • application/octet-stream (PDF binary stream)

3.2 Download Manifest (V2)

POST /data/v2/generate/manifest

Request Body

{
  "ids": [
    "500999AT876841",
    "500999AT876842"
  ]
}

Response (200 OK)

{
  "ctime": 1770000000000,
  "manifestNumber": 987654321,
  "manifestDownloadUrl": "https://storage.googleapis.com/.../manifest.pdf"
}

4. Tracking APIs

4.1 Standard Tracking API

GET /api/v1/track/{id}

Open API - No Bearer Token Required

Path Parameters

  • id (string, required): Tracking / Shipment ID.

Response Example

{
  "_id": "500999A3408005",
  "order_number": "ORD-2026-001",
  "edd": 1770200000000,
  "track": {
    "status": "In Transit",
    "ctime": 1770000000000,
    "desc": "Shipment in transit to destination hub",
    "location": "Bengaluru Hub",
    "attempts": 0,
    "details": [
      {
        "status": "Picked Up",
        "ctime": 1769900000000,
        "desc": "Picked up from seller warehouse",
        "location": "Bengaluru"
      }
    ]
  }
}

Standard Tracking Statuses (swift_status)

  • Order Placed, In Transit, Out for Delivery, Delivered, Cancelled, Seller Cancelled
  • RTO Requested, RTO In Transit, RTO Delivered, RTO Out for Delivery, RTO Failed
  • Picked Up, Pickup Cancelled, Pickup Pending, Pickup Scheduled, Out for Pickup
  • Lost, Damaged, Shipment Delayed, Not Serviceable, Not Picked, Undelivered

4.2 Raw Ekart Tracking API

GET /data/v1/elite/track/{wbn}

Returns raw tracking data for non-large or large shipments including complete hub movement history, customer info, receiver info, sender info, and slot details.


5. Serviceability APIs

5.1 Serviceability V2

GET /api/v2/serviceability/{pincode}

Response (200 OK)

{
  "status": true,
  "pincode": 560008,
  "remark": "Pincode is serviceable",
  "details": {
    "cod": true,
    "max_cod_amount": 25000,
    "forward_pickup": true,
    "forward_drop": true,
    "reverse_pickup": true,
    "reverse_drop": true,
    "city": "Bengaluru",
    "state": "KA"
  }
}

5.2 Serviceability V3

POST /data/v3/serviceability

Check available courier partners, TAT, and estimated charges for pickup/drop pairs.

Request Body

{
  "pickupPincode": "560067",
  "dropPincode": "400001",
  "length": "10",
  "width": "10",
  "height": "10",
  "weight": "500",
  "paymentType": "Prepaid",
  "serviceType": "SURFACE",
  "invoiceAmount": "1000"
}

Response (200 OK)

[
  {
    "courierGroup": "EKART",
    "tat": {
      "min": 2,
      "max": 4
    },
    "forwardDeliveredCharges": {
      "forwardFreight": "45.00",
      "forwardFuelSurcharge": "5.00",
      "codCharges": "0.00",
      "deliveredTotalTax": "9.00",
      "totalForwardDeliveredEstimate": "59.00"
    },
    "rtoDeliveredCharges": {
      "forwardFreight": "45.00",
      "rtoFreight": "35.00",
      "forwardFuelSurcharge": "5.00",
      "rtoFuelSurcharge": "4.00",
      "rtoDeliveredTotalTax": "16.02",
      "totalRTODeliveredEstimate": "105.02"
    }
  }
]

5.3 Bulk Serviceability

GET /data/serviceability/bulk/{type}?format={JSON|EXCEL}

  • type: NON_LARGE or LARGE
  • format: JSON (default) or EXCEL

6. Address Management (V2)

6.1 Register Address / Warehouse

POST /api/v2/address

Request Body

{
  "alias": "WH_BLR_01",
  "phone": 9876543210,
  "address_line1": "Plot 123, KIADB Industrial Area",
  "address_line2": "Phase 2, Whitefield",
  "pincode": 560067,
  "city": "Bengaluru",
  "state": "Karnataka",
  "country": "India",
  "geo": {
    "lat": 12.9716,
    "lon": 77.5946
  }
}

6.2 Get All Saved Addresses

GET /api/v2/addresses


7. Webhooks (V2)

Supported Webhook Topics

  1. track_updated: Fired on tracking status changes.
  2. shipment_created: Fired when a shipment is manifested.
  3. shipment_recreated: Fired when a shipment is re-shipped.

7.1 Register Webhook

POST /api/v2/webhook

Request Body

{
  "url": "https://yourdomain.com/webhooks/ekart",
  "secret": "my_secret_key_123",
  "topics": ["track_updated", "shipment_created"],
  "active": true
}

7.2 Get Webhooks

GET /api/v2/webhook


7.3 Update Webhook

PUT /api/v2/webhook/{webhook_id}


8. Non-Delivery Actions (NDR V2)

POST /api/v2/package/ndr

Take action on non-delivered shipments.

Actions (ndr_action_enum_v2)

  • Re-Attempt: Require date (millisecond timestamp within 7 days).
  • RTO: Initiate Return to Origin.

Request Body

{
  "wbn": "500999A3408005",
  "action": "Re-Attempt",
  "date": 1770100000000,
  "phone": "9876543210",
  "address": "Updated delivery address",
  "instructions": "Customer asked to re-attempt tomorrow after 2 PM"
}

9. Shipping Rate Estimates (V1)

POST /data/pricing/estimate

Request Body

{
  "pickupPincode": 560067,
  "dropPincode": 400001,
  "invoiceAmount": 1500.0,
  "weight": 750,
  "length": 20,
  "width": 15,
  "height": 10,
  "serviceType": "SURFACE",
  "codAmount": 0.0
}