Quickstart: your first delivery from code in 10 minutes

This guide takes you from a key to a delivery that is assigned to one of your own riders. Every step is one curl call. Details of each call are in the guides linked at the end.

Before you start#

• An API login email and key. See Get your API credentials.

• At least one rider online. See Add and manage your riders from your system.

• Use the practice server first. See Test safely in the sandbox.

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

1. 1

   Step 1: Log in

   Send your login email and key. The token is valid for 90 days and goes in the Authorization header of every later call.

   TerminalCopy code to clipboard

   curl -X POST "$BASE_URL/auth/api/login" \  -H "Content-Type: application/json" \  -d '{ "email": "you@yourshop.in", "api_key": "YOUR_API_KEY" }'

   JSONCopy code to clipboard

   {  "success": true,  "data": {    "access_token": "eyJhbGciOi...",    "expires_at": "2024-04-15T10:30:00.000Z"  }}

2. 2

   Step 2: Check the distance (optional)

   Send the drop location. The pickup location is your outlet.

   TerminalCopy code to clipboard

   curl -X POST "$BASE_URL/api/estimate" \  -H "Authorization: Bearer $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{ "drop_lat": 12.9352, "drop_lng": 77.6245 }'

   The response data has distance_km and estimated_delivery_charge.

3. 3

   Step 3: Create an order for your own riders

   Set delivery_mode to OUTLET. Without it the default is MINIDROP.

   TerminalCopy code to clipboard

   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"  }'

   JSONCopy code to clipboard

   {  "success": true,  "data": {    "id": "550e8400-e29b-41d4-a716-446655440000",    "order_number": "ORD-A3B7K9",    "trip_id": null,    "pickup_otp": "4821",    "reference_order_id": "POS-12345",    "status": "CREATED",    "completed_at": null  },  "message": "Order created successfully"}

   The response is shortened. The full shape is in Create, read and cancel orders.

4. 4

   Step 4: Plan and assign the trips

   This optimises the queued OUTLET orders across your online riders. Idempotency-Key makes a retry safe.

   TerminalCopy code to clipboard

   curl -X POST "$BASE_URL/api/trips" \  -H "Authorization: Bearer $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: dispatch-2026-10-20-1" \  -d '{}'

   With the default body the trips are approved at once: each trip has status ASSIGNED and its rider is notified. See Plan and approve trips for your own riders.

5. 5

   Step 5: Receive the updates

   Set your webhook URL on the Developers page of the outlet portal. MiniDrop then sends order.updated to it when the order changes: ASSIGNED, PICKED_UP, DELIVERED and so on. Or poll GET /api/orders/:id.

   TerminalCopy code to clipboard

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

   See Receive order updates with webhooks.

Where to go next#

• Create, read and cancel orders

• Errors, rate limits and best practices

More in this category#