API Documentation - DFC Express

1 Overview & Architecture

The DFCExpress Developer API allows you to programmatically manage domestic and international logistics workflows across India’s leading 500+ carriers — including DTDC, Delhivery, Ekart, Xpressbees, Shree Maruti, Velocity, DHL, FedEx, UPS, ICL, Aramex, and DPall.

All API endpoints are RESTful, consume and produce application/json payloads, and use standard HTTP response codes for status reporting.

Single Unified Schema

One single API contract connects you to all 12+ carriers without individual courier integrations.

Smart Carrier Routing

Pass carrier_mode: "best_rate" or "fastest" and our algorithm auto-allocates the optimal courier.

Real-Time Webhooks

Receive asynchronous delivery, in-transit, out-for-delivery, and NDR updates automatically.

2 Authentication & Headers

Authenticate all HTTP requests using an API Bearer Token passed in the Authorization request header. API tokens can be generated from your DFCExpress Merchant Dashboard under Settings › API & Webhooks.

Standard Request Headers

Authorization: Bearer dfc_live_sec_994a38bf472910abc
Content-Type: application/json
Accept: application/json
x-dfc-version: 2026-09

Keep Your Secret Keys Secure

Never expose production API keys in client-side code, public GitHub repositories, or browser scripts. Use sandbox keys for local testing.

3 Environments & Base URLs

DFCExpress provides dedicated sandbox and production environments:

Environment	Base URL	Purpose
Production	`https://api.dfcexpress.in/api/v2`	Live orders, actual courier dispatch & billing
Sandbox / Test	`https://sandbox-api.dfcexpress.in/api/v2`	Simulated bookings, test AWBs, mock tracking

4 Check Courier Serviceability & Live Rates

Check whether a destination PIN code is serviceable, compare real-time freight charges across all 12+ carriers, check Cash on Delivery (COD) availability, and estimate delivery timelines before creating an order.

POST /couriers/serviceability

Request Payload (JSON)

{
  "pickup_pincode": "110001",
  "delivery_pincode": "400001",
  "weight_grams": 750,
  "dimensions": {
    "length_cm": 20,
    "width_cm": 15,
    "height_cm": 10
  },
  "is_cod": true,
  "declared_value": 1499.00
}

Success Response (200 OK)

{
  "status": "success",
  "serviceable": true,
  "data": {
    "recommended_courier": "delhivery_surface",
    "rates": [
      {
        "courier_code": "delhivery_surface",
        "courier_name": "Delhivery Express Surface",
        "freight_charge": 48.50,
        "cod_fee": 25.00,
        "total_amount": 73.50,
        "estimated_delivery_days": "2-3 Days",
        "service_type": "Surface"
      },
      {
        "courier_code": "dtdc_air",
        "courier_name": "DTDC Express Air",
        "freight_charge": 65.00,
        "cod_fee": 25.00,
        "total_amount": 90.00,
        "estimated_delivery_days": "1-2 Days",
        "service_type": "Air Priority"
      },
      {
        "courier_code": "ekart_standard",
        "courier_name": "Ekart Logistics",
        "freight_charge": 52.00,
        "cod_fee": 25.00,
        "total_amount": 77.00,
        "estimated_delivery_days": "2-3 Days",
        "service_type": "Surface"
      },
      {
        "courier_code": "xpressbees_express",
        "courier_name": "Xpressbees",
        "freight_charge": 49.00,
        "cod_fee": 25.00,
        "total_amount": 74.00,
        "estimated_delivery_days": "2-3 Days",
        "service_type": "Surface"
      }
    ]
  }
}

5 Create Order & Generate AWB

Book a shipment directly with your chosen carrier (or let the AI Auto-Optimizer assign the cheapest carrier). The response returns an instant Air Waybill (AWB) number and manifests the order with the carrier.

POST /orders/create

Request Payload (cURL)

curl -X POST "https://api.dfcexpress.in/api/v2/orders/create" \
  -H "Authorization: Bearer dfc_live_sec_994a38bf472910abc" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-2026-98214",
    "order_date": "2026-09-02T12:00:00Z",
    "preferred_courier": "auto",
    "payment_method": "COD",
    "collectible_amount": 1499.00,
    "pickup_address": {
      "name": "DFC Warehouse Gurugram",
      "phone": "9932797473",
      "address_line1": "Plot 123, Sector 18",
      "city": "Gurugram",
      "state": "Haryana",
      "pincode": "122015"
    },
    "delivery_address": {
      "name": "Rahul Verma",
      "phone": "9876543210",
      "address_line1": "Flat 402, Sunshine Heights, Andheri West",
      "city": "Mumbai",
      "state": "Maharashtra",
      "pincode": "400053"
    },
    "order_items": [
      {
        "sku": "TSHIRT-BLK-M",
        "name": "Cotton Crewneck T-Shirt (Black)",
        "quantity": 2,
        "price": 749.50
      }
    ],
    "package_details": {
      "weight_grams": 500,
      "length_cm": 25,
      "width_cm": 15,
      "height_cm": 5
    }
  }'

Response Payload (201 Created)

{
  "status": "success",
  "message": "Order created & AWB manifested successfully",
  "data": {
    "shipment_id": "DFC-SHP-849201",
    "order_id": "ORD-2026-98214",
    "awb_number": "874209152341",
    "carrier_assigned": "Delhivery Express",
    "service_type": "Surface",
    "routing_code": "DEL/BOM/AND",
    "shipping_charge": 48.50,
    "cod_fee": 25.00,
    "label_url": "https://api.dfcexpress.in/labels/DFC-SHP-849201.pdf",
    "tracking_url": "https://dfcexpress.in/track?awb=874209152341",
    "pickup_scheduled_at": "2026-09-02T16:00:00+05:30"
  }
}

6 Download & Print Shipping Labels

Fetch standard 4x6 inch thermal barcode shipping labels in PDF or thermal ZPL format. Labels comply with all carrier scan standards (Code 128 / QR Code).

GET /orders/label/{awb_or_shipment_id}?format=pdf&size=4x6

Response Payload (200 OK)

{
  "status": "success",
  "data": {
    "awb_number": "874209152341",
    "format": "pdf",
    "label_download_url": "https://cdn.dfcexpress.in/labels/874209152341.pdf",
    "expires_at": "2026-09-09T12:00:00Z"
  }
}

7 Real-Time Shipment Tracking

Query live milestone telemetry across any of our 12+ courier partners using the unified AWB or Merchant Order ID.

GET /shipments/track/{awb_number}

Response Payload (200 OK)

{
  "status": "success",
  "data": {
    "awb_number": "874209152341",
    "current_status": "OUT_FOR_DELIVERY",
    "carrier": "Delhivery",
    "origin": "Delhi, DL",
    "destination": "Mumbai, MH",
    "expected_delivery": "2026-09-04T18:00:00+05:30",
    "scans": [
      {
        "status": "OUT_FOR_DELIVERY",
        "location": "Andheri West Delivery Hub, Mumbai",
        "timestamp": "2026-09-04T08:30:00+05:30",
        "activity": "Shipment out for delivery with rider (Phone: 9811223344)"
      },
      {
        "status": "IN_TRANSIT",
        "location": "Bhiwandi Sorting Facility, Mumbai",
        "timestamp": "2026-09-03T23:15:00+05:30",
        "activity": "Arrived at destination processing hub"
      },
      {
        "status": "PICKED_UP",
        "location": "Gurugram Logistics Center, HR",
        "timestamp": "2026-09-02T16:45:00+05:30",
        "activity": "Package received from merchant warehouse"
      }
    ]
  }
}

8 Webhooks & Real-Time Event Stream

Instead of polling tracking endpoints, register an HTTPS webhook URL in your dashboard to receive real-time push events when parcel states change.

Event Name	Trigger Condition
`shipment.manifested`	Order booked & AWB generated successfully
`shipment.picked_up`	Courier rider has picked up parcel from merchant
`shipment.in_transit`	Consignment reached intermediate sorting center
`shipment.out_for_delivery`	Parcel is out for final doorstep delivery
`shipment.delivered`	Successful delivery recorded & POD generated
`shipment.ndr_raised`	Delivery attempted but failed (Customer unavailable / Wrong address)
`shipment.rto_initiated`	Return to Origin triggered after failed delivery attempts

9 NDR & RTO Automated Workflows

When a courier fails to deliver a parcel (Non-Delivery Report), submit corrective actions programmatically to schedule re-attempts or update buyer contact information.

POST /ndr/action

Request Payload (JSON)

{
  "awb_number": "874209152341",
  "action": "REATTEMPT",
  "reschedule_date": "2026-09-05",
  "updated_phone": "9876543219",
  "delivery_remarks": "Customer was out of station. Requested delivery on Saturday morning."
}

10 Cancel Consignment

Cancel an order before courier pickup to release carrier allocation and obtain an immediate freight refund back to your merchant shipping wallet.

POST /orders/cancel

Request Payload (JSON)

{
  "awb_number": "874209152341",
  "cancellation_reason": "Buyer requested order cancellation before dispatch"
}

11 HTTP Status & Error Codes

DFCExpress REST APIs use conventional HTTP response codes to indicate success or failure:

HTTP Code	Status	Description
`200 OK`	Success	Request processed successfully
`201 Created`	Created	Order / AWB booked successfully
`400 Bad Request`	Client Error	Missing mandatory fields or invalid PIN code format
`401 Unauthorized`	Auth Failed	Invalid, expired, or missing Bearer API token
`402 Payment Required`	Low Balance	Insufficient merchant wallet credit balance
`429 Too Many Requests`	Rate Limit	API rate limit exceeded (120 requests/minute standard)
`500 Server Error`	Server Error	Internal gateway error; carrier downstream timeout

12 SDKs, Plugins & Developer Support

We offer official plugins and pre-built software development kits for seamless integration:

Shopify App

1-Click Order Sync & Auto-Fulfillment

WooCommerce

Automated AWB Printing & Live Rates

Node.js SDK

npm install @dfcexpress/sdk

Python SDK

pip install dfcexpress

DFCExpress Developer Support Team

API Inquiries: api@dfcexpress.in

Technical Support: Contact@dfcexpress.in

+91 9932797473 / +91 6294209274

API Documentation & Integration Guide

1 Overview & Architecture

Single Unified Schema

Smart Carrier Routing

Real-Time Webhooks

2 Authentication & Headers

3 Environments & Base URLs

4 Check Courier Serviceability & Live Rates

5 Create Order & Generate AWB

6 Download & Print Shipping Labels

7 Real-Time Shipment Tracking

8 Webhooks & Real-Time Event Stream

9 NDR & RTO Automated Workflows

10 Cancel Consignment

11 HTTP Status & Error Codes

12 SDKs, Plugins & Developer Support

Shopify App

WooCommerce

Node.js SDK

Python SDK

DFCExpress Developer Support Team

Company

Services

Support

Legal