Introduction
Welcome to the MilkRun API! You can use our API to access MilkRun API endpoints, which can get information on orders in our database.
Authentication
API Key
MilkRun uses API keys to allow access to the API. You can login by merchant account and get API key at our developer portal.
Test environment: https://cms-develop.milkrun.info/merchants/sign_in
Production enviroment: https://milkrun.info/merchants/sign_in.
MilkRun expects for the API key to be included in all API requests to the server in a header that looks like the following:
X-Api-Key: meowmeowmeow
Environment
Test environment: https://cms-develop.milkrun.info
Production enviroment: https://milkrun.info
Change-logs
Update on Aug 15, 2024
Add otp code for order destination Create an Order API
Update on May 17, 2024
Add tipping an order api for merchant Tipping an order API
Update on March 27, 2024
Merchant can send brand name when create an outlet dispatch order: Added brand_name field for Submit a pending order API
Update on Dec 15, 2023
Merchant can input delivery time window (hour). Only allow value from 1 to 6. Delivery time window will be split based on each drop-off distance for Submit a pending order API
Update on Nov 01, 2023
Merchants can receive the tracking link via webhook event: Added tracking_url field to Webhook Events
Merchants can receive the pick-up proofs via webhook event: Added tracking_url field to Webhook Events
Update on Oct 12, 2023
Merchants can send recipient name for each order destinations: Added recipient_name field for Create an Order API
Update on Sep 21, 2023
Merchants have to send to MilkRun the postal codes of pick-up address: Added pick_up_postal_code fied for Create an Order API
Merchants have to send to MilkRun the postal codes of each delivery address in order destination object: Added delivery_postal_code fied for Create an Order API
Merchants can send their price to MilkRun: Added merchant_optional_price field for Create an Order API
Change Test environment endpoint to cms-develop.milkrun.info
Update on Apr 26, 2022
Merchants can opt-in bundling orders. Added an additional field bundling_allowed for Update merchant account API
Update on Mar 14, 2022
Merchants can choose damage coverage when they create an order: Added 2 additioanl fields damage_covered and damage_covered_fee for Create an Order API
In addition, merchant can request covered when they choose damage coverage order: Added Merchant Claim Request API
Update on Sep 17, 2021
Added Retrieve merchant account API and Update merchant account API.
Update on Aug 07, 2021
Change Test environment endpoint to uat.milkrun.info
Update on Jul 26, 2021
Added car_only field for Create an Order API.
Update on Jul 22, 2021
Merchants can send the name and phone number that they want to display to riders: Added 2 additional fields customized_merchant_name and customized_merchant_phone_number for Create an Order API
Orders
The order object
{
"uuid": "RO0493",
"status": "accepted",
"pick_up_address": "1 Robin Rd, Singapore 258176",
"pick_up_lat": "1.3188848",
"pick_up_lng": "103.8263779",
"pick_up_postal_code": "258176",
"pick_up_address_details": "#01-10",
"car_only": false,
"scheduled_time": null,
"eta": "22 min",
"merchant": "Happy Juice",
"cancellation_fee": null,
"order_time": 1621393485,
"driver_lat": "1.2598942473420844",
"driver_lng": "103.82480964709131",
"driver_name": "Driver 001",
"driver_phone_number": "+6511111621",
"driver_vehicle": "bicycle",
"delivery_fee": 20.34,
"damage_covered": true,
"damage_covered_fee": 1.0,
"sms_customer": true,
"sms_fee": 3.0,
"pick_up_proofs": [],
"order_destinations": [
{
"uuid": "RO0493-1",
"status": "wait_for_delivery",
"delivery_address": "21 Amber Rd, Singapore 439870",
"delivery_lat": "1.3000094",
"delivery_lng": "103.8984388",
"delivery_postal_code": "439870",
"delivery_address_details": "#02-30",
"recipient_name": "Bob",
"customer_phone_number": "+6500000001",
"note": "Call before delivery",
"distance": "13.17 km",
"duration": "17.4 min",
"delivery_proof": null,
"delivery_proofs": []
},
{
"uuid": "RO0493-2",
"status": "wait_for_delivery",
"delivery_address": "839 Mountbatten Rd, Singapore 437830",
"delivery_lat": "1.302996",
"delivery_lng": "103.8976717",
"delivery_postal_code": "437830",
"delivery_address_details": "#01-100",
"recipient_name": "Anna",
"customer_phone_number": "+6500000002",
"note": "Call before delivery",
"distance": "1.0 km",
"duration": "5.4 min",
"delivery_proof": null,
"delivery_proofs": [
"/uploads/development/order_destinations/delivery_proofs/1207/1207_3410e7d7e1b67424802e.png"
]
}
]
}
uuid string
Unique identifier for order.
status string
Order's delivery status.
Available values: pending submitted accepted in_progress delivered cancelled driver_not_found scheduled admin_cancelled
pickup_address string
Order pick-up address.
pickup_address_lat string
Order pick-up address latitude.
pickup_address_lng string
Order pick-up address longtitude.
pick_up_postal_code string
Order pick-up address postal code
pickup_address_details string
Order pick-up address details.
car_only boolean
Whether the order is only for car.
scheduled_time string
Epoch Unix Timestamp when the order will being submitted for pre-scheduled orders only.
eta string
ETA to pick-up for accepted order.
ETA to deliver for in_progress order.
This field is only returned when requesting retrieve an order endpoint.
merchant string
Merchant's businsess name.
cancellation_fee float
Cancellation fee.
order_time integer
Epoch Unix Timestamp when the order was submitted or will being submitted.
driver_name string
Driver's name.
This field is only returned when requesting retrieve an order endpoint and for ongoing orders.
driver_phone_number string
Driver's phone number.
This field is only returned when requesting retrieve an order endpoint and for ongoing orders.
driver_lat string
Driver's current latitude.
This field is only returned when requesting retrieve an order endpoint and for ongoing orders.
driver_lng string
Driver's current longtitude.
This field is only returned when requesting retrieve an order endpoint and for ongoing orders.
driver_vehicle string
Driver's vehicle type.
Available values: car, motocycle, bike, on_foot
This field is only returned when requesting retrieve an order endpoint and for ongoing orders.
delivery_fee float
Delivery fee paid by merchant.
sms_customer boolean
Whether the customer can receive the delivery tracking via SMS.
damage_covered boolean
Milkrun can cover
damage_covered_fee float
Fee for damage coverage order
order_destinations array of hashes
List of order drop-off points
Details about each object:
order_destinations.uuid string
Unique identifier for order destination.
order_destinations.status string
Status of order destination.
Available statuses: wait_for_delivery in_progress delivered
order_destinations.delivery_address string
Drop-off point address.
order_destinations.delivery_lat string
Drop-off point address latitude.
order_destinations.delivery_lng string
Drop-off point address longtitude.
order_destinations.delivery_postal_code string
Drop-off point address postal code
order_destinations.delivery_address_details string
Drop-off point address details.
order_destinations.recipient_name string
Recipient name at drop-off point.
order_destinations.customer_phone string
Customer's phone number at drop-off point.
order_destinations.note string
Customer's note at drop-off point.
order_destinations.distance string
order_destinations.duration string
order_destinations.delivery_proof string
Proof of delivery URL.
order_destinations.otp_code string
OTP verification code at drop-off point.
List all orders
The JSON structured return like this:
{
"data": [
{
"uuid": "TR3D8FFA",
"status": "delivered",
"pick_up_address": "Bras Basah Complex, 231 Bain St, Singapore 180231, Singapore",
"pick_up_lat": "1.29682",
"pick_up_lng": "103.85362",
"pick_up_postal_code": "180231",
"pick_up_address_details": "3213",
"car_only": false,
"scheduled_time": null,
"cancellation_fee": null,
"merchant": "Happy Juice",
"merchant_phone_number": "+6523232323",
"order_time": 1695191283,
"delivery_fee": 0.0,
"damage_covered": false,
"damage_covered_fee": 0.0,
"sms_customer": false,
"order_destinations": [
{
"uuid": "RO0493-1",
"status": "wait_for_delivery",
"delivery_address": "21 Amber Rd, Singapore 439870",
"delivery_lat": "1.3000094",
"delivery_lng": "103.8984388",
"delivery_postal_code": "439870",
"delivery_address_details": "#02-30",
"recipient_name": "Bob",
"customer_phone_number": "+6500000001",
"note": "Call before delivery",
"distance": "13.17 km",
"duration": "17.4 min",
"delivery_proof": null,
"delivery_proofs": []
},
{
"uuid": "RO0493-2",
"status": "wait_for_delivery",
"delivery_address": "839 Mountbatten Rd, Singapore 437830",
"delivery_lat": "1.302996",
"delivery_lng": "103.8976717",
"delivery_postal_code": "437830",
"delivery_address_details": "#01-100",
"recipient_name": "Anna",
"customer_phone_number": "+6500000002",
"note": "Call before delivery",
"distance": "1.0 km",
"duration": "5.4 min",
"delivery_proof": null,
"delivery_proofs": [
"/uploads/development/order_destinations/delivery_proofs/1207/1207_3410e7d7e1b67424802e.png"
]
}
]
},
{
"uuid": "TR123231",
"status": "delivered",
"pick_up_address": "882 Tampines Street 84 Tampines Spring, 521882",
"pick_up_lat": "1.3263612",
"pick_up_lng": "103.8613574",
"pick_up_postal_code": "521882",
"pick_up_address_details": "#01-01",
"car_only": false,
"scheduled_time": null,
"cancellation_fee": null,
"merchant": "Happy Juice",
"merchant_phone_number": "+6523232323",
"order_time": 1695182042,
"delivery_fee": 15.73,
"damage_covered": false,
"damage_covered_fee": 0.0,
"sms_customer": true,
"order_destinations": [
{
"uuid": "RO0493-1",
"status": "wait_for_delivery",
"delivery_address": "21 Amber Rd, Singapore 439870",
"delivery_lat": "1.3000094",
"delivery_lng": "103.8984388",
"delivery_postal_code": "439870",
"delivery_address_details": "#02-30",
"recipient_name": "Bob",
"customer_phone_number": "+6500000001",
"note": "Call before delivery",
"distance": "13.17 km",
"duration": "17.4 min",
"delivery_proof": null
},
{
"uuid": "RO0493-2",
"status": "wait_for_delivery",
"delivery_address": "839 Mountbatten Rd, Singapore 437830",
"delivery_lat": "1.302996",
"delivery_lng": "103.8976717",
"delivery_postal_code": "437830",
"delivery_address_details": "#01-100",
"recipient_name": "Anna",
"customer_phone_number": "+6500000002",
"note": "Call before delivery",
"distance": "1.0 km",
"duration": "5.4 min",
"delivery_proof": null
}
]
}
],
"page": 1,
"per_page": 10,
"total_count": 2,
"total_pages": 1
}
This endpoint retrieves all orders of merchant.
HTTP Request
GET MILKRUN_HOST/api/integration/merchants/orders
Query Parameters
| Parameter | Default | Description |
|---|---|---|
| page | 1 | Page number |
| per_page | 10 | Number of order items per page |
| order_by | order_time | Available values: order_time, delivery_fee |
| order | desc | Available values: desc, asc |
Retrieve an order
The JSON structured return like this:
{
"uuid": "TR6F040B",
"status": "driver_not_found",
"pick_up_address": "Bras Basah Complex, 231 Bain St, Singapore 180231, Singapore",
"pick_up_lat": "1.29682",
"pick_up_lng": "103.85362",
"pick_up_postal_code": "180231",
"pick_up_address_details": "3213",
"car_only": false,
"scheduled_time": null,
"eta": null,
"merchant": "Happy Juice",
"merchant_phone_number": "+6523232323",
"cancellation_fee": null,
"order_time": 1695022530,
"driver_lat": null,
"driver_lng": null,
"driver_name": null,
"driver_phone_number": null,
"driver_vehicle": null,
"delivery_fee": 0.0,
"damage_covered": false,
"damage_covered_fee": 0.0,
"sms_customer": false,
"sms_fee": 0.0,
"pick_up_proofs": [],
"order_destinations": [
{
"uuid": "RO0493-1",
"status": "wait_for_delivery",
"delivery_address": "21 Amber Rd, Singapore 439870",
"delivery_lat": "1.3000094",
"delivery_lng": "103.8984388",
"delivery_postal_code": "439870",
"delivery_address_details": "#02-30",
"customer_phone_number": "+6500000001",
"recipient_name": "Bob",
"note": "Call before delivery",
"distance": "13.17 km",
"duration": "17.4 min",
"delivery_proof": null,
"delivery_proofs": []
},
{
"uuid": "RO0493-2",
"status": "wait_for_delivery",
"delivery_address": "839 Mountbatten Rd, Singapore 437830",
"delivery_lat": "1.302996",
"delivery_lng": "103.8976717",
"delivery_postal_code": "437830",
"delivery_address_details": "#01-100",
"recipient_name": "Bob",
"customer_phone_number": "+6500000002",
"note": "Call before delivery",
"distance": "1.0 km",
"duration": "5.4 min",
"delivery_proof": null,
"delivery_proofs": [
"/uploads/development/order_destinations/delivery_proofs/1207/1207_3410e7d7e1b67424802e.png"
]
}
]
}
This endpoint retrieves a specific order of merchant.
HTTP Request
GET MILKRUN_HOST/api/integration/merchants/orders/<uuid>
URL Parameters
| Parameter | Description |
|---|---|
| uuid | The UUID of the order to retrieve |
Create an order
The JSON structured return like this:
{
"uuid": "TRAD7C6D",
"status": "pending",
"pick_up_address": "Bras Basah Complex, 231 Bain St, Singapore 180231, Singapore",
"pick_up_lat": "1.3263612",
"pick_up_lng": "103.8613574",
"pick_up_postal_code": "180231",
"pick_up_address_details": "#01-01",
"car_only": true,
"scheduled_time": null,
"eta": null,
"merchant": "Happy Juice",
"merchant_phone_number": "+6523232323",
"cancellation_fee": null,
"order_time": null,
"driver_lat": null,
"driver_lng": null,
"driver_name": null,
"driver_phone_number": null,
"driver_vehicle": null,
"delivery_fee": 2222.0,
"damage_covered": false,
"damage_covered_fee": 0.0,
"sms_customer": false,
"sms_fee": 0.0,
"pick_up_proofs": [],
"order_destinations": [
{
"uuid": "RO0493-1",
"status": "wait_for_delivery",
"delivery_address": "21 Amber Rd, Singapore 439870",
"delivery_lat": "1.3000094",
"delivery_lng": "103.8984388",
"delivery_postal_code": "439870",
"delivery_address_details": "#02-30",
"recipient_name": "Bob",
"customer_phone_number": "+6500000001",
"note": "Call before delivery",
"distance": "13.17 km",
"duration": "17.4 min",
"delivery_proof": null,
"delivery_proofs": [],
"otp_code": "123456"
},
{
"uuid": "RO0493-2",
"status": "wait_for_delivery",
"delivery_address": "839 Mountbatten Rd, Singapore 437830",
"delivery_lat": "1.302996",
"delivery_lng": "103.8976717",
"delivery_postal_code": "437830",
"delivery_address_details": "#01-100",
"recipient_name": "Bob",
"customer_phone_number": "+6500000002",
"note": "Call before delivery",
"distance": "1.0 km",
"duration": "5.4 min",
"delivery_proof": null,
"delivery_proofs": [
"/uploads/development/order_destinations/delivery_proofs/1207/1207_3410e7d7e1b67424802e.png"
],
"otp_code": "123456"
}
]
}
This endpoint creates an order of merchant. The created order will not active until it is submitted.
HTTP Request
POST MILKRUN_HOST/api/integration/merchants/orders
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| uuid | No | String | The UUID of order. If UUID is not provided, it will be generated automatically |
| pick_up_address | Yes | String | Order's pick up address |
| pick_up_lat | Yes | String | Order's pick up address latitude |
| pick_up_lng | Yes | String | Order's pick up address longtitude |
| pick_up_postal_code | Yes | String | Merchant can provide the postal code for address if the latitude, longitude of pick-up address is not correctly value. Eg: 238622 |
| pick_up_address_details | No | String | Order's pick up address details |
| order_destinations | Yes | Array of hashes | List of drop-off points |
| customized_merchant_name | No | String | Merchant name shown to riders |
| customized_merchant_phone_number | No | String | Merchant phone number shown to riders |
| car_only | No | Boolean | If true, the order will be only visible to car riders. Otherwise, the order will be visible to all riders. |
| sms_customer | No | Boolean | If true, we'll send the tracking URL to customers by SMS. Please note that a $0.15 additional charge is applicable for each drop-off location. |
| scheduled_time | No | String | Eg: 2021-04-21T09:00:00+08:00. The order will be sent to drivers immediately if scheduled_time is not provided. Otherwise if scheduled_time is provided, the order will be submitted as a scheduled order. |
| damage_covered | No | Boolean | If the order is damaged due to the fault of the rider, MilkRun will cover up to an amount, once verified upon investigation. |
| merchant_optional_price | No | Float | Merchant can provide the optional price. If your merchant is accepted for merchant optional price by admin, MilkRun will use this value as the total price |
Details of each order destination object
| Parameter | Required | Type | Description |
|---|---|---|---|
| recipient_name | No | String | Recipient name at drop-off point. Eg: Anna, Bob |
| customer_phone_number | Yes | String | Customer phone number at drop-off point. Format: +65 and 8 or 9 digits. Eg: +6512345678, +65123456789 |
| delivery_address | Yes | String | Drop-off point address |
| delivery_lat | Yes | String | Drop-off point address latitude |
| delivery_lng | Yes | String | Drop-off point address longtitude |
| delivery_postal_code | Yes | String | Merchant can provide the postal code for address if the latitude, longitude of pick-up address is not correctly value. Eg: 238622 |
| delivery_address_details | No | String | Drop-off point address details |
| note | No | String | Customer note at drop-off point |
| otp_code | No | String | OTP verification code at drop-off point |
Create an outlet dispatch order
The JSON structured return like this:
{
"uuid": "TR22BA89",
"status": "pending",
"car_only": true,
"scheduled_time": null,
"eta": null,
"merchant": "Trâu Đồng Quê 2",
"merchant_phone_number": "+6512345678",
"cancellation_fee": null,
"order_time": null,
"driver_lat": null,
"driver_lng": null,
"driver_name": null,
"driver_phone_number": null,
"driver_vehicle": null,
"delivery_fee": 13.62,
"damage_covered": false,
"damage_covered_fee": 0.0,
"sms_customer": false,
"sms_fee": 0.0,
"pick_up_proofs": [],
"order_destinations": [
{
"uuid": "TR22BA89-1",
"status": "wait_for_delivery",
"delivery_address": "11 Pasir Ris Street 52 Elias Park Primary School",
"delivery_lat": "1.37503303189652",
"delivery_lng": "103.94535776820999",
"delivery_postal_code": "518866",
"delivery_address_details": "123 Nam Sa Cho detail",
"recipient_name": "hawng",
"customer_phone_number": "+6568686868",
"note": "123",
"distance": "9km",
"duration": "11.2 min",
"delivery_proof": null,
"delivery_proofs": [],
}
]
}
This endpoint create a outlet dispatch order.
HTTP Request
POST MILKRUN_HOST/api/integration/merchants/orders/outlet_dispatch_order
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| uuid | No | String | The UUID of order. If UUID is not provided, it will be generated automatically |
| customized_merchant_name | No | String | Merchant name shown to riders |
| car_only | No | Boolean | If true, the order will be only visible to car riders. Otherwise, the order will be visible to all riders. |
| sms_customer | No | Boolean | If true, we'll send the tracking URL to customers by SMS. Please note that a $0.15 additional charge is applicable for each drop-off location. |
| damage_covered | No | Boolean | If the order is damaged due to the fault of the rider, MilkRun will cover up to an amount, once verified upon investigation. |
| merchant_optional_price | No | Float | Merchant can provide the optional price. If your merchant is accepted for merchant optional price by admin, MilkRun will use this value as the total price |
| recipient_name | No | String | Recipient name at drop-off point. Eg: Anna, Bob |
| customer_phone_number | Yes | String | Customer phone number at drop-off point. Format: +65 and 8 or 9 digits. Eg: +6512345678, +65123456789 |
| delivery_address | Yes | String | Drop-off point address |
| delivery_lat | Yes | String | Drop-off point address latitude |
| delivery_lng | Yes | String | Drop-off point address longtitude |
| delivery_postal_code | No | String | Merchant can provide the postal code for address if the latitude, longitude of pick-up address is not correctly value. Eg: 238622 |
| delivery_address_details | No | String | Drop-off point address details |
| note | No | String | Customer note at drop-off point |
| number_of_items | No | Integer | Number of items in order. If the number of items to deliver exceed the capacity for one car, we return the order to the merchant without creating the order |
| brand_name | No | String | Merchant can provide brand name of outlet |
Submit a pending order
The JSON structured return like this:
{
"uuid": "RO0493",
"status": "submitted",
"pick_up_address": "1 Robin Rd, Singapore 258176",
"pick_up_lat": "1.3188848",
"pick_up_lng": "103.8263779",
"pick_up_postal_code": "258176",
"pick_up_address_details": "#01-10",
"car_only": false,
"scheduled_time": null,
"eta": null,
"merchant": "Happy Juice",
"merchant_phone_number": "+6523232323",
"cancellation_fee": null,
"order_time": null,
"driver_lat": null,
"driver_lng": null,
"driver_name": null,
"driver_phone_number": null,
"driver_vehicle": null,
"delivery_fee": 20.34,
"damage_covered": true,
"damage_covered_fee": 1.0,
"sms_customer": true,
"sms_fee": 3.0,
"pick_up_proofs": [],
"order_destinations": [
{
"uuid": "RO0493-1",
"status": "wait_for_delivery",
"delivery_address": "21 Amber Rd, Singapore 439870",
"delivery_lat": "1.3000094",
"delivery_lng": "103.8984388",
"delivery_postal_code": "439870",
"delivery_address_details": "#02-30",
"recipient_name": "Bob",
"customer_phone_number": "+6500000001",
"note": "Call before delivery",
"distance": "13.17 km",
"duration": "17.4 min",
"delivery_proof": null,
"delivery_proofs": []
},
{
"uuid": "RO0493-2",
"status": "wait_for_delivery",
"delivery_address": "839 Mountbatten Rd, Singapore 437830",
"delivery_lat": "1.302996",
"delivery_lng": "103.8976717",
"delivery_postal_code": "437830",
"delivery_address_details": "#01-100",
"recipient_name": "Bob",
"customer_phone_number": "+6500000002",
"note": "Call before delivery",
"distance": "1.0 km",
"duration": "5.4 min",
"delivery_proof": null,
"delivery_proofs": [
"/uploads/development/order_destinations/delivery_proofs/1207/1207_3410e7d7e1b67424802e.png"
]
}
]
}
This endpoint submits a pending order. The order will be sent to drivers immediately if scheduled_time is not provided. Otherwise if scheduled_time is provided, the order will be submitted as a scheduled order.
HTTP Request
POST MILKRUN_HOST/api/integration/merchants/orders/<uuid>/submit
URL Parameters
| Parameter | Description |
|---|---|
| uuid | The UUID of the order to submit |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| scheduled_time | No | String | Eg: 2021-04-21T09:00:00+08:00 |
| delivery_time_window | No | Float | Merchant can input delivery time window (hour). Only allow value from 1 to 6. Delivery time window will be split based on each drop-off distance |
Tipping an order
The JSON structured return like this:
{
"uuid": "TRE27B87",
"status": "submitted",
"pick_up_address": "11 Bidadari Park Drive The Woodleigh Mall, 367803",
"pick_up_lat": "1.33869261143024",
"pick_up_lng": "103.872035411169",
"pick_up_address_details": "Location: #B1-K14, Manager: Mei Yun",
"car_only": true,
"scheduled_time": null,
"eta": null,
"merchant": "Trâu Đồng Quê 2",
"merchant_phone_number": "+6569080300",
"cancellation_fee": null,
"order_time": 1715757783,
"driver_lat": null,
"driver_lng": null,
"driver_name": null,
"driver_phone_number": null,
"driver_vehicle": null,
"delivery_fee": 17.5,
"damage_covered": false,
"damage_covered_fee": 0.0,
"sms_customer": false,
"sms_fee": 0.0,
"pick_up_proofs": [],
"order_destinations": [
{
"uuid": "TRE27B87-1",
"status": "wait_for_delivery",
"delivery_address": "56 Kallang Pudding Road Hh @ Kallang",
"delivery_lat": "1.32803011629205",
"delivery_lng": "103.878919874466",
"delivery_postal_code": "349328",
"delivery_address_details": "123 Nam Sa Cho detail",
"recipient_name": "hawng",
"customer_phone_number": "+6568686868",
"note": "123",
"distance": "3km",
"duration": "4.8 min",
"delivery_proof": null,
"delivery_proofs": []
}
]
}
This endpoint add tipping for an order.
HTTP Request
PUT MILKRUN_HOST/api/integration/merchants/orders/<uuid>/tipping
URL Parameters
| Parameter | Description |
|---|---|
| uuid | The UUID of the order to submit |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| tips | Yes | Integer | Tipping amount E.g: 10 |
Cancel an order
The JSON structured return like this:
{
"uuid": "RO0493",
"status": "cancelled",
"pick_up_address": "1 Robin Rd, Singapore 258176",
"pick_up_lat": "1.3188848",
"pick_up_lng": "103.8263779",
"pick_up_postal_code": "258176",
"pick_up_address_details": "#01-10",
"car_only": false,
"scheduled_time": null,
"eta": null,
"merchant": "Happy Juice",
"merchant_phone_number": "+6523232323",
"cancellation_fee": null,
"order_time": null,
"driver_lat": null,
"driver_lng": null,
"driver_name": null,
"driver_phone_number": null,
"driver_vehicle": null,
"delivery_fee": 20.34,
"damage_covered": true,
"damage_covered_fee": 1.0,
"sms_customer": true,
"sms_fee": 3.0,
"pick_up_proofs": [],
"order_destinations": [
{
"uuid": "RO0493-1",
"status": "wait_for_delivery",
"delivery_address": "21 Amber Rd, Singapore 439870",
"delivery_lat": "1.3000094",
"delivery_lng": "103.8984388",
"delivery_postal_code": "439870",
"delivery_address_details": "#02-30",
"recipient_name": "Bob",
"customer_phone_number": "+6500000001",
"note": "Call before delivery",
"distance": "13.17 km",
"duration": "17.4 min",
"delivery_proof": null,
"delivery_proofs": []
},
{
"uuid": "RO0493-2",
"status": "wait_for_delivery",
"delivery_address": "839 Mountbatten Rd, Singapore 437830",
"delivery_lat": "1.302996",
"delivery_lng": "103.8976717",
"delivery_postal_code": "437830",
"delivery_address_details": "#01-100",
"recipient_name": "Bob",
"customer_phone_number": "+6500000002",
"note": "Call before delivery",
"distance": "1.0 km",
"duration": "5.4 min",
"delivery_proof": null,
"delivery_proofs": [
"/uploads/development/order_destinations/delivery_proofs/1207/1207_3410e7d7e1b67424802e.png"
]
}
]
}
This endpoint cancels an order. Only able to cancel the order with status: submitted accepted scheduled driver_not_found.
HTTP Request
DELETE MILKRUN_HOST/api/integration/merchants/orders/<uuid>
URL Parameters
| Parameter | Description |
|---|---|
| uuid | The UUID of the order to cancel |
Account
The account object
{
"id": 1,
"email": "merchant@milkrunsg.com",
"phone_number": "+6500000001",
"outlet_name": "MilkRun",
"outlet_address": "20 Jalan Afifi #07-01, Certis Cisco Centre, Singapore 409179",
"outletlat": "1.3224149",
"outletlng": "103.8833272",
"address_details": "#07-01",
"carbon_friendly_allowed": true,
"bundling_allowed": true,
"account_balance": 10000.0
}
id integer
Merchant ID.
id string
Merchant email address.
phone_number string
Merchant phone number.
outlet_name string
Outlet name
outlet_address string
Outlet address
outletlat string
Outlet latitude
outletlng string
Outlet longtitude
address_details string
Outlet address details
carbon_friendly_allowed boolean
Whether allow carbon-friendly vehicle (bicycle/walking)
bundling_allowed boolean
Whether merchant opted-in bundling orders.
account_balance float
Merchant account balance
Retrieve merchant account
The JSON structured return like this:
{
"id": 1,
"email": "merchant@milkrunsg.com",
"phone_number": "+6500000001",
"outlet_name": "MilkRun",
"outlet_address": "20 Jalan Afifi #07-01, Certis Cisco Centre, Singapore 409179",
"outletlat": "1.3224149",
"outletlng": "103.8833272",
"address_details": "#07-01",
"carbon_friendly_allowed": true,
"bundling_allowed": true,
"account_balance": 10000.0
}
This endpoint retrieves the merchant account.
HTTP Request
GET MILKRUN_HOST/api/integration/merchants/account
Update merchant account
The JSON structured return like this:
{
"id": 1,
"email": "merchant@milkrunsg.com",
"phone_number": "+6500000001",
"outlet_name": "MilkRun",
"outlet_address": "20 Jalan Afifi #07-01, Certis Cisco Centre, Singapore 409179",
"outletlat": "1.3224149",
"outletlng": "103.8833272",
"address_details": "#07-01",
"carbon_friendly_allowed": true,
"bundling_allowed": true,
"account_balance": 10000.0
}
This endpoint updates the merchant account.
HTTP Request
PUT MILKRUN_HOST/api/integration/merchants/account
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| carbon_friendly_allowed | No | Boolean | If true, your orders will be visible to all riders. Otherwise the orders are only visible to car, motorbike and van riders. |
| bundling_allowed | No | Boolean | If true, your orders with same pick-up location will come into our bundling system. |
Webhook Events
Introduce
Receive event notifications via webhooks
MilkRun uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a driver accepts an order, an order is completed.
Begin using webhooks:
1. Register your webhook URL
Sign into the merchant portal and add your endpoint.
- Test environment: Merchant Portal
- Production environment: Merchant Portal
After the webhook URL is added, we will provide you with an APP TOKEN. This token is used to identify our requests to your server.
The token will be included in all our requests to your server in a header that looks like the following:
X-Api-Key: meowmeowmeow
2. Build a webhook
Create webhook endpoint on your server to receive webhook notifications.
For each event occurrence, MilkRun POSTs the webhook data to your endpoint in JSON format. The full event details are included and can be used directly after parsing the JSON into an Event object.
The event object
{
"type": "order.completed",
"order_id": "RO0489",
"status": "delivered",
"destination_id": null,
"object": {
"uuid": "RO0489",
"status": "delivered",
"pick_up_address": "1 Robin Rd, Singapore 258176",
"pick_up_lat": "1.3188848",
"pick_up_lng": "103.8263779",
"pick_up_address_details": "#01-10",
"car_only": false,
"scheduled_time": null,
"merchant": "Happy Juice",
"cancellation_fee": null,
"order_time": 1621350233,
"driver_lat": "1.2598942473420844",
"driver_lng": "103.82480964709131",
"driver_name": "Driver 001",
"driver_phone_number": "+6511111621",
"driver_vehicle": "bicycle",
"delivery_fee": 20.34,
"tracking_url": "https://milkrun.info/orders/4491/tracking",
"pick_up_proofs": "https://milkrun-dev.s3.amazonaws.com/uploads/order_destination/pick_up_proofs/4491/proof.jpg",
"order_destinations": [
{
"uuid": "RO0489-1",
"status": "delivered",
"delivery_address": "21 Amber Rd, Singapore 439870",
"delivery_lat": "1.3000094",
"delivery_lng": "103.8984388",
"delivery_address_details": "#02-30",
"customer_phone_number": "+6500000001",
"note": "Call before delivery",
"distance": "13.17 km",
"duration": "17.4 min",
"delivery_proof": "https://milkrun-dev.s3.amazonaws.com/uploads/order_destination/delivery_proof/4491/proof.jpg"
},
{
"uuid": "RO0489-2",
"status": "delivered",
"delivery_address": "839 Mountbatten Rd, Singapore 437830",
"delivery_lat": "1.302996",
"delivery_lng": "103.8976717",
"delivery_address_details": "#01-100",
"customer_phone_number": "+6500000002",
"note": "Call before delivery",
"distance": "1.0 km",
"duration": "5.4 min",
"delivery_proof": "https://milkrun-dev.s3.amazonaws.com/uploads/order_destination/delivery_proof/4492/proof.jpg"
}
]
}
}
type string
Description of event.
Available values: order.submitted, order.accepted, order.driver_arrived, order.picked_up, order.order_destination.completed, order.merchant_cancelled, order.driver_cancelled, order.admin_cancelled, order.driver_not_found, order.completed
object hash
Object containing the order resource relevant to the event.
note
Tracking link will be displayed when order is accepted by any driver.
Merchant Claim Requests
This endpoint creates an claim request for the damage coverage. Only order with damage_covered = true can be requested for.
id integer
Unique identifier for request
order_uuid string
UUID of the order for request
status string
Merchant claim request status
Default value is pending when the request success
amount float
Amount covered
Default value 0.0 until checked and updated by Admins
created_at string
Request creation time
The JSON structured return like this:
{
"id": 1,
"order_uuid": "FADB0625",
"status": "pending",
"amount": 0.0,
"created_at": "2022-03-14T13:18:10.823+07:00"
}
HTTP Requests
POST MILKRUN_HOST/api/integeration/merchants/orders/<uuid>/merchant_claim_requests
URL Claim Requests Parameters
| Parameter | Description |
|---|---|
| uuid | The UUID of the order for request |
Errors
The MilkRun API uses the following error codes:
HTTP Errors
| HTTP Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The order requested is hidden for administrators only. |
| 404 | Not Found -- The specified order could not be found. |
| 405 | Method Not Allowed -- You tried to access a order with an invalid method. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 410 | Gone -- The order requested has been removed from our servers. |
| 429 | Too Many Requests -- You're requesting too many orders! Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Errors
1001 error code
{
"code": 1001,
"error": "Merchant Unauthenticated!"
}
3003 error code
{
"code": 3003,
"error": "Order is unavailable!"
}
| Error Code | Meaning |
|---|---|
| 1001 | Unauthenticated! -- Missing or wrong API key |
| 3003 | Order is unavailable -- The specified order could not be found |