Skip to content
MiniDropDocs
Developers & API

Create, read and cancel orders

Create orders for your own riders, read their status and tracking link, and cancel an order before pickup.

3 min readUpdated Developers

On this page

Orders are created for your outlet. The pickup location is your outlet’s location, taken from your token. All calls need Authorization: Bearer <access_token>.

Set BASE_URL to the API address you were given. The examples below use $BASE_URL and $ACCESS_TOKEN.

Create an order#

POST /api/orders

Terminal
curl -X POST "$BASE_URL/api/orders" \  -H "Authorization: Bearer $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "drop_latitude": 12.9352,    "drop_longitude": 77.6245,    "customer_name": "John Doe",    "customer_phone": "+1234567890",    "address": "123 Main Street, City, State 12345",    "reference_order_id": "POS-12345",    "delivery_mode": "OUTLET"  }'

Field

Details

drop_latitude

number, required, -90 to 90

drop_longitude

number, required, -180 to 180

customer_name

string, required, 1 to 200 characters

customer_phone

string, required, 1 to 20 characters

address

string, optional, 1 to 500 characters

reference_order_id

string, optional, max 100 characters. Your own or POS order ID, stored for your tracking and display

delivery_mode

string, optional: MINIDROP or OUTLET. Defaults to MINIDROP

Response 201 Created (shortened):

JSON
{  "success": true,  "data": {    "id": "550e8400-e29b-41d4-a716-446655440000",    "order_number": "ORD-A3B7K9",    "outlet_id": "550e8400-e29b-41d4-a716-446655440001",    "outlet_name": "Main Outlet",    "trip_id": null,    "drop_latitude": 12.9352,    "drop_longitude": 77.6245,    "distance_km": 5.5,    "customer_name": "John Doe",    "customer_phone": "+1234567890",    "pickup_otp": "4821",    "address": "123 Main Street, City, State 12345",    "reference_order_id": "POS-12345",    "status": "CREATED",    "created_at": "2024-01-15T10:30:00.000Z",    "completed_at": null  },  "message": "Order created successfully"}

The response also has delivery_charge. order_number is the human-readable number to show to support and customers. pickup_otp is a 4-digit code to share with the rider for pickup verification. distance_km and delivery_charge are frozen at creation.

Errors: 400 invalid coordinates or validation, 401 missing or invalid token, 403 not an API user, 404 outlet not found. A 422 ROUTE_NOT_FOUND means there is no road route to the drop point: correct the coordinates, retrying will not help.

Estimate before you create (optional)#

POST /api/estimate with drop_lat and drop_lng returns distance_km and estimated_delivery_charge. The pickup location is your outlet.

Read an order#

GET /api/orders/:id returns one order of your outlet.

Terminal
curl "$BASE_URL/api/orders/550e8400-e29b-41d4-a716-446655440000" \  -H "Authorization: Bearer $ACCESS_TOKEN"
JSON
{  "success": true,  "data": {    "id": "550e8400-e29b-41d4-a716-446655440000",    "order_number": "ORD-A3B7K9",    "trip_id": "550e8400-e29b-41d4-a716-446655440002",    "pickup_otp": "4821",    "status": "ASSIGNED",    "reference_order_id": "POS-12345",    "created_at": "2024-01-15T10:30:00.000Z",    "completed_at": null,    "track_url": "https://minidrop.in/t/Qm3k9x_2LrT7vH1aBn0pWg"  }}

track_url is the customer tracking link. It is null until a rider is assigned. See Receive order updates with webhooks. Errors: 401, 403 (not an API user, or the order is not your outlet’s), 404.

Order statuses#

Status

Meaning

CREATED

Placed. For OUTLET orders, waiting in the dispatch queue

ASSIGNED

A rider is assigned and heading to pick up

PICKED_UP

The rider has picked up the order

ON_HOLD

Picked up; the rider paused the delivery with a reason. Ends as DELIVERED or UNDELIVERED

DELIVERED

Delivered to the customer

UNDELIVERED

Final: the delivery was attempted but not completed

CANCELLED

Cancelled by the outlet or integrator

Cancel an order#

DELETE /api/orders/:id

Terminal
curl -X DELETE "$BASE_URL/api/orders/550e8400-e29b-41d4-a716-446655440000" \  -H "Authorization: Bearer $ACCESS_TOKEN"

  • CREATED orders can be cancelled free of charge.

  • ASSIGNED orders (not yet picked up) can be cancelled. OUTLET orders have no fee.

  • Orders that are PICKED_UP, ON_HOLD, DELIVERED, UNDELIVERED or already CANCELLED cannot be cancelled: the call answers 400.

A successful call returns 200 with the order and "message": "Order cancelled successfully".

Where do I get the order ID?

In data.id of the create response. Your own number goes in reference_order_id; it is returned on read and in webhooks.

When does the order get a tracking link?

When a rider is assigned. Until then track_url is null.

Related guidePlan and approve trips for your own ridersTurn queued OUTLET orders into trips for your online riders, approve them in one call or in the portal, and read the trips back.

Was this page helpful?

Related guides

Test safely in the sandbox

Use the practice server to test orders, trips and webhooks without real riders: how the simulation runs and which scenarios exist.

3 min readDevelopers

Plan and approve trips for your own riders

Turn queued OUTLET orders into trips for your online riders, approve them in one call or in the portal, and read the trips back.

3 min readDevelopers

Receive order updates with webhooks

Set your webhook URL, check the X-API-SECRET header, read the order.updated payload and handle retries.

4 min readDevelopers

Add and manage your riders from your system

Create, list, update and remove your own riders with the delivery-executives endpoints, and what the rider does next.

4 min readDevelopers

Type to search all guides.