Merchant API

Create and track parcels from your own store. Generate an API key in Merchant → API & Webhooks and send it as a bearer token. All responses use { "success": true, "data": … }; errors return { "success": false, "status", "message", "errors?" }. Amounts are integer BDT.

Authentication

curl https://dourdesh.com/api/developer/v1/areas \
  -H "Authorization: Bearer dd_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Endpoints

Method	Path	Purpose
GET	`/areas`	Active delivery areas (use `id` as `destination_area_id`)
POST	`/parcels/price-calculation`	Quote a delivery
POST	`/parcels`	Create a parcel (cash on delivery)
GET	`/parcels/:tracking_id`	Parcel details
GET	`/parcels/:tracking_id/track`	Status timeline
POST	`/parcels/:tracking_id/cancel`	Cancel (immediate before pickup, otherwise a cancellation request)

Create a parcel

Pickup details come from your default pickup address in the dashboard.

POST https://dourdesh.com/api/developer/v1/parcels
{
  "customer_name": "Karim Ahmed",
  "customer_phone": "01811111111",
  "customer_address": "House 9, Road 3, Banani",
  "destination_area_id": "<id from /areas>",
  "cash_to_collect": 1200,
  "weight": 1.5,
  "service_type": "REGULAR",
  "merchant_order_id": "SO-1001",
  "instruction": "Call before delivery"
}

→ 201
{
  "success": true,
  "data": {
    "tracking_id": "DD-20260823-48213",
    "merchant_order_id": "SO-1001",
    "status": "PENDING",
    "payment_status": "PENDING",
    "delivery_charge": 70,
    "total_charge": 70,
    "cash_to_collect": 1200,
    "created_at": "2026-08-23T10:00:00.000Z"
  }
}

Webhooks

Set a URL under API & Webhooks. On every status change we POST:

POST https://yourstore.com/webhooks/dourdesh
X-DourDesh-Signature: <hex HMAC-SHA256 of the raw body, keyed with your secret>
X-DourDesh-Delivery: <unique delivery id — use it to de-duplicate retries>

{
  "event": "parcel.status_updated",
  "tracking_id": "DD-20260823-48213",
  "merchant_order_id": "SO-1001",
  "status": "OUT_FOR_DELIVERY",
  "cash_collected": 1200,
  "timestamp": "2026-08-23T12:34:56.000Z"
}

Respond with any 2xx within 10 seconds. Non-2xx responses and timeouts are retried with exponential backoff (8 attempts over ~2 hours); you can watch each attempt in the dashboard and send a webhook.test event at any time. Statuses: PENDING, PICKUP_REQUESTED, PICKED_UP, HUB_RECEIVED, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, DELIVERY_FAILED, RETURNED, CANCELLED.

Verify a signature (Node.js)

import { createHmac, timingSafeEqual } from 'node:crypto';

const expected = createHmac('sha256', process.env.DOURDESH_WEBHOOK_SECRET).update(rawBody).digest('hex');
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-dourdesh-signature'] ?? ''));