Delivar API · Reference

Logistics, built for developers.

Integrate Delivar's last-mile delivery network into your platform with a few REST calls. Create pickup addresses, check serviceability, book riders, track in real time, and cancel — all from a single, predictable API.

4

Endpoints

REST

JSON over HTTPS

v1

Stable

Base URLs

Two environments are available. Use development for testing, integration, and dry runs. Move to production only after end-to-end validation.

Base URL https://dev.api.delivar.in/api/external/v1/bookings

Tracking

Purpose

Testing & QA

Real charges

No (sandbox)

Rate limit

Relaxed

Base URL https://api.delivar.in/api/external/v1/bookings

Tracking https://delivar.in/track/{public_tracking_id}

Purpose

Live orders

Real charges

Yes

Rate limit

Enforced

i

Switching tabs above also updates the DEV / PROD environment globally — every code sample and "Try It" panel on this page reflects your selection.

Section 01

Authentication

Most endpoints are authenticated via an API key passed in the request headers. The user_id inside the external_sources object must match a valid registered user in the Delivar system.

Required Headers

Header	Value	Required
x-api-key	{EXTERNAL-SOURCE-KEY}	Yes
Content-Type	application/json	Yes
Accept	application/json	Optional

!

Never expose your x-api-key in client-side code, mobile bundles, or public repositories. Always proxy through your backend.

Endpoint 01

Create Pickup Address

Register a pickup location under your account. The address is stored against your user_id and referenced later by booking creation via pickup_address_id.

POST https://dev.api.delivar.in/api/external/v1/bookings/create-pickup-address

Required Fields

Field	Type	Description
name	string	Map name / pickup title
pickup_contact_name	string	Contact person full name
pickup_contact_number	string (10)	Contact mobile number
pickup_address	string	Full address line 1
pickup_lat	numeric	Latitude
pickup_lng	numeric	Longitude
city_name	string	City
state_name	string	State
country_name	string	Country
pincode	string	Pincode / ZIP

Optional Fields

Field	Type	Description
street_name	string	Address line 2
district_name	string	District name
email	string	Contact email (defaults to user email)

Try It

Run a request

Endpoint URL

Request Body (JSON)

→

Click Send Request to see the response

Success Response · 201

201 Created

{
  "success": true,
  "message": "Pickup address created successfully",
  "data": {
    "id": 1,
    "user_id": 45,
    "name": "Home Pickup",
    "pickup_contact_name": "Ravi Kumar",
    "pickup_contact_number": "9876543210",
    "pickup_address": "No 12, Gandhi Street",
    "pickup_lat": "12.97865",
    "pickup_lng": "77.56433",
    "street_name": "Near Bus Stand",
    "city_name": "Bengaluru",
    "district_name": "Bangalore Urban",
    "state_name": "Karnataka",
    "country_name": "India",
    "pincode": "560001"
  }
}

Error Responses

422 Validation Error

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "pickup_contact_number": [
      "The pickup contact number must be 10 digits."
    ]
  }
}

409 Duplicate

{
  "success": false,
  "message": "You have already created a pickup address with this Map Name"
}

400 Invalid User Type

{
  "success": false,
  "message": "Invalid user type"
}

500 Server Error

{
  "success": false,
  "message": "Something went wrong",
  "error": "Actual error message here"
}

Endpoint 02

Check Service Availability

Before creating a booking, verify whether a rider service is available between two coordinates and retrieve indicative pricing (sub total, platform charges, GST, total).

POST https://dev.api.delivar.in/api/external/v1/bookings/check-service-availability

i

No auth token required for this endpoint unless your middleware enforces it. All inputs are validated from the request body.

Required Fields

Field	Type	Description
pickup_lat	numeric	Pickup latitude
pickup_long	numeric	Pickup longitude
pickup_pincode	string	Pickup pincode
delivery_lat	numeric	Drop location latitude
delivery_long	numeric	Drop location longitude
delivery_pincode	string	Drop pincode
utc_offset	integer	Client timezone offset (e.g. 330 for IST)
payment_type	string	Payment mode — Online only
customer_name	string	Customer name
customer_mobile	string	Customer mobile number
weight	numeric	Weight

Try It

Run a request

Endpoint URL

Request Body (JSON)

→

Click Send Request to see the response

Success Response · 200

200 OK — Service Available

{
  "best_rider": {
    "status": true,
    "eta": "22 mins",
    "distance": "5.2 km"
  },
  "sub_total": 65.00,
  "platform_charges": 10,
  "gst_amount": 11.7,
  "total_amount": 77
}

200 OK — No Pricing Available

{
  "best_rider": null,
  "message": "No available services with pricing"
}

Error Responses

422 Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "pickup_lat": ["The pickup lat field is required."]
  }
}

500 Server Error

{
  "status": false,
  "error": "Unexpected error: Delivery API timeout"
}

Endpoint 03

Wallet Balance

Fetch the current wallet balance for your account. Every Create Booking call deducts from this wallet, so we recommend checking the balance before placing high-value or bulk orders, and topping up via the Delivar dashboard when low.

POST https://dev.api.delivar.in/api/external/v1/bookings/wallet-balance

!

Requires header x-api-key: {EXTERNAL-SOURCE-KEY}. The auth middleware validates external_sources and maps it to a user.

Try It

Run a request

Endpoint URL

x-api-key

→

Click Send Request to see the response

Success Response · 200

200 OK

{
  "success": true,
  "wallet_balance": 1450.75,
  }
}

200 OK — Low Balance

{
  "success": true,
  "wallet_balance": 1450.75,
  }
}

Error Responses

401 Unauthorized

{
  "success": false,
  "message": "Invalid or missing x-api-key"
}

404 User Not Found

{
  "success": false,
  "message": "User not found for the provided external_sources"
}

500 Server Error

{
  "success": false,
  "message": "Something went wrong",
}

Endpoint 04

Create Booking

Create a delivery booking against a saved pickup address. The system validates wallet balance, creates the booking record, deducts the wallet amount, and stores the transaction.

POST https://dev.api.delivar.in/api/external/v1/bookings/create-booking

!

Requires header x-api-key: {EXTERNAL-SOURCE-KEY}. The auth middleware validates external_sources and maps it to a user.

Request Validation Rules

Field	Type	Required	Description
pickup_address_id	integer	Yes	Must exist in pickup_address
dropAddress	string	Yes	Drop location address
dropContactName	string	Yes	Contact person name
dropContactNumber	string	Yes	Receiver mobile number
dropCoords.lat	numeric	Yes	Drop latitude
dropCoords.lng	numeric	Yes	Drop longitude
drop_address_details.city_name	string	Yes	Destination city
drop_address_details.state_name	string	Yes	Destination state
drop_address_details.pincode	string	Yes	Pincode
productCategory	string	Yes	Category of package
packageDetails.length	numeric	Yes	In cm
packageDetails.width	numeric	Yes	In cm
packageDetails.height	numeric	Yes	In cm
packageDetails.weight	numeric	Yes	In kg
utc_offset	integer	No	Timezone offset in minutes
payment_type	string	No	COD / Online
collectible_amount	numeric	No	For COD orders

Try It

Run a request

Endpoint URL

x-api-key

Request Body (JSON)

→

Click Send Request to see the response

Success Response · 201

201 Created

{
  "success": true,
  "booking": {
    "id": 1055,
    "user_id": 12,
    "pickup_address_id": 73,
    "status": "Pending",
    "drop_name": "Ravi Kumar",
    "drop_phone": "9342798869",
    "drop_address": "No. 22, Anna Nagar, Chennai",
    "drop_city": "Chennai",
    "booking_order_id": "LMT202512090001",
    "public_tracking_id": "a837db73-3fd1-4f82-9e8f-b2a04d1b234c",
    "tracking_url": null,
    "platform_charges": 0,
    "gst_amount": 21.6,
    "order_total_price": 141.6,
    "created_at": "2025-12-09 10:55:21"
  }
}

Error Responses

422 Validation

{
  "success": false,
  "errors": {
    "pickup_address_id": [
      "The selected pickup address id is invalid."
    ]
  }
}

400 Insufficient Wallet

{
  "success": false,
  "message": "Insufficient wallet balance"
}

Provider API Failure

{
  "success": false,
  "message": "API failed to create order"
}

500 Server Error

{
  "success": false,
  "message": "Something went wrong",
  "error": "Detailed exception message"
}

i

Note: platform_charges, rider_price, and order_total_price must be numeric values (no ₹ symbol).

Endpoint 05

Track Booking

Retrieve live tracking details and the full status history for a booking using its booking_order_id. The response includes the assigned rider's details, current coordinates, and a chronological status trail.

POST https://dev.api.delivar.in/api/external/v1/bookings/track-booking

!

Requires header x-api-key: {EXTERNAL-SOURCE-KEY}. The auth middleware validates external_sources and maps it to a user.

Body Parameters

Field	Type	Required	Description
booking_order_id	string	Yes	Unique booking order ID returned by Create Booking

Try It

Run a request

Endpoint URL

x-api-key

Request Body (JSON)

→

Click Send Request to see the response

Success Response · 200

200 OK — Active Order

{
  "success": true,
  "tracking": {
    "booking_order_id": "LMT202512090001",
    "status_label": "Out For Delivery",
    "delivery_boy": "Suresh M",
    "delivery_phone": "9876501234",
    "current_location": {
      "lat": 13.082341,
      "long": 80.270231
    }
  },
  "status_history": [
    {
      "status": "Pending",
      "changed_at": "2026-06-09 14:19:53"
    },
    {
      "status": "Assigned",
      "changed_at": "2026-06-09 14:25:21"
    },
    {
      "status": "Arrived at Pickup",
      "changed_at": "2026-06-09 14:28:03"
    },
    {
      "status": "Picked Up",
      "changed_at": "2026-06-09 14:28:25"
    },
    {
      "status": "Out For Delivery",
      "changed_at": "2026-06-09 14:28:40"
    }
  ]
}

200 OK — Delivered

{
  "success": true,
  "tracking": {
    "booking_order_id": "LMT202512090001",
    "status_label": "Delivered",
    "delivery_boy": "Suresh M",
    "delivery_phone": "9876501234",
    "current_location": {
      "lat": null,
      "long": null
    }
  },
  "status_history": [
    {
      "status": "Pending",
      "changed_at": "2026-06-09 14:19:53"
    },
    {
      "status": "Assigned",
      "changed_at": "2026-06-09 14:25:21"
    },
    {
      "status": "Arrived at Pickup",
      "changed_at": "2026-06-09 14:28:03"
    },
    {
      "status": "Picked Up",
      "changed_at": "2026-06-09 14:28:25"
    },
    {
      "status": "Out For Delivery",
      "changed_at": "2026-06-09 14:28:40"
    },
    {
      "status": "Delivered",
      "changed_at": "2026-06-09 14:28:56"
    }
  ]
}

Response Fields

Field	Type	Description
tracking.booking_order_id	string	The booking order ID that was queried
tracking.status_label	string	Current status of the order
tracking.delivery_boy	string \| null	Assigned rider's name; null if not yet assigned or cancelled
tracking.delivery_phone	string \| null	Rider's contact number; null if not applicable
tracking.current_location.lat	numeric \| null	Rider's current latitude; null when inactive
tracking.current_location.long	numeric \| null	Rider's current longitude; null when inactive
status_history	array	Chronological list of all status transitions with timestamps
status_history[].status	string	Status name at that point in time
status_history[].changed_at	datetime	Timestamp of the status change (IST, `YYYY-MM-DD HH:MM:SS`)

Status labels

Pending Booking placed, awaiting rider

Assigned Rider accepted the order

Arrived at Pickup Rider reached pickup point

Picked Up Package collected by rider

Out For Delivery En route to drop location

Delivered Package handed to recipient

Cancelled Order cancelled

Error Responses

422 Validation Error

{
    "success": false,
    "message": "Failed to fetch tracking details",
    "error": "The booking order id field is required."
}
}

404 Not Found

{
  "success": false,
  "message": "Booking not found for the provided booking_order_id"
}

401 Unauthorized

{
  "success": false,
  "message": "Invalid or missing x-api-key"
}

500 Server Error

{
  "success": false,
  "message": "Something went wrong",
  "error": "Detailed exception message"
}

Integration · Push events

Webhooks

Webhooks let Delivar push order status updates to your server in real time, instead of you polling our API every few seconds. The moment a rider accepts, picks up, or delivers a package, your endpoint receives a signed JSON payload — making your dashboards, customer notifications, and reconciliation flows near-instant.

Why you need webhooks

Real-time updates

Status changes reach you within seconds, not minutes. No cron jobs, no polling delays, no missed events.

Lower API load

Stop hammering our endpoints with status checks. Webhooks reduce your outbound calls by 90%+ for active orders.

Better customer UX

Trigger SMS, email, or push notifications the instant something happens — "Rider assigned", "Out for delivery", "Delivered".

Reliable reconciliation

Every event carries a signed payload and event ID. Build idempotent handlers and never lose a status update.

How it works

01 Register your webhook URL

Share your HTTPS endpoint with the Delivar team during onboarding, or configure it from the dashboard once available. We'll store the URL and generate a unique webhook secret for your account.

02 Receive event payloads

Every status change on any of your bookings triggers a POST request to your URL with a JSON body and a X-Delivar-Signature header.

03 Verify the signature

Compute an HMAC-SHA256 of the raw request body using your webhook secret. Compare it against the signature header — reject the request if they don't match.

04 Respond fast with 2xx

Acknowledge with HTTP 200 OK within 5 seconds. Queue heavy work (DB writes, notifications) to a background job — don't block the response.

05 Handle retries idempotently

If we don't receive a 2xx, we retry up to 5 times with exponential backoff (1m, 5m, 15m, 1h, 6h). Use the event_id to deduplicate.

Event types

booking.created New booking placed

rider.assigned A rider accepted the order

rider.arrived_pickup Rider at pickup point

order.picked_up Package collected

order.in_transit On the way to drop

rider.arrived_drop Rider at drop location

order.delivered Successful delivery

order.cancelled Cancelled by user or system

order.failed Delivery attempt failed

order.refunded Wallet refund processed

Example payload

POST → your-server/webhooks/delivar

{
  "booking_id": "0000000259",
  "new_status": "Delivered",
  "old_status": "Picked Up",
  "changed_at": "2026-06-22 17:26:42",
  "order_source_id": 14,
  "public_tracking_id": "c886083d-f675-4092-bf53-e0cfdbc6ecd7",
  "status_history": [
    {
      "status": "Pending",
      "changed_at": "2026-06-22 16:50:44"
    },
    {
      "status": "Assigned",
      "changed_at": "2026-06-22 16:51:27"
    },
    {
      "status": "Pending",
      "changed_at": "2026-06-22 17:02:01"
    },
    {
      "status": "Assigned",
      "changed_at": "2026-06-22 17:03:12",
      "alert_sent": true
    },
    {
      "status": "Picked Up",
      "changed_at": "2026-06-22 17:14:47"
    },
    {
      "status": "Delivered",
      "changed_at": "2026-06-22 17:26:42"
    }
  ]
}

Required request headers

Header	Description
secret-key	xxxxxxxxxxxx

Help · Section 02

Support

Stuck on an integration? Our team replies during business hours and prioritises production-blocking issues. Pick whichever channel suits you.

Office Hours

9:30 AM – 6:30 PM IST
Monday – Saturday

Office Address

5A, Sippai Nagar, Kumananchavadi Signal,
Chennai, Tamil Nadu 600056

What to include when you reach out

A complete report lets us help you on the first reply. Please share:

Your user_id or registered company name
Environment — Development or Production
Endpoint being called (e.g. /create-booking)
Full request payload (redact PII if needed)
Full response body including status code
Timestamp of the request in IST
Booking order ID or tracking ID if applicable
Steps to reproduce the issue

Get in touch · Section 03

Contact Us

Let's build something together.

Interested in onboarding Delivar for your business, exploring volume pricing, or discussing a custom integration? Talk to our team — we typically respond within one business day.

Visit Us

5A, Sippai Nagar, Kumananchavadi Signal,
Chennai, Tamil Nadu 600056

i

For technical integration support, head to the Support section above and follow the checklist for the fastest possible response.

Logistics, built for developers.

Base URLs

Authentication

Required Headers

Create Pickup Address

Required Fields

Optional Fields

Try It

Success Response · 201

Error Responses

Check Service Availability

Required Fields

Try It

Success Response · 200

Error Responses

Wallet Balance

Try It

Success Response · 200

Error Responses

Create Booking

Request Validation Rules

Try It

Success Response · 201

Error Responses

Track Booking

Body Parameters

Try It

Success Response · 200

Response Fields

Status labels

Error Responses

Webhooks

Why you need webhooks

Real-time updates

Lower API load

Better customer UX

Reliable reconciliation

How it works

01 Register your webhook URL

02 Receive event payloads

03 Verify the signature

04 Respond fast with 2xx

05 Handle retries idempotently

Event types

Example payload

Required request headers

Support

Email

Phone

WhatsApp

Office Hours

Office Address

What to include when you reach out

Contact Us

Let's build something together.

Business Enquiries

Call Sales

WhatsApp

Visit Us