NAV Navbar
Sandbox Production

Introduction

Base URL

https://rest.lalamove.com

https://rest.sandbox.lalamove.com

Lalamove API allows you to integrate our delivery services into your business workflow.

Lalamove provides a collection of essential, lightweight and flexible endpoints allowing you to automate your fulfilment logistics workflow quickly and easily.

It normally takes a developer a week or two to complete an integration ready for our Go-Live Process.

Jump right in by registering in Partner Portal and get started right now :

Change Log












Authentication

Lalamove API makes use of HMAC (SHA256) as the authentication mechanism.

You will be provided an api KEY, and a SECRET for generating a HMAC hash (also known as a SIGNATURE).

Sandbox & Production API keys

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Signature

Example in JavaScript

const SECRET = 'MCwCAQACBQDDym2lAgMBAAECBDHB';
const time = new Date().getTime().toString(); // => `1545880607433`

const method = 'POST';
const path = '/v2/quotations';
const body = JSON.stringify({...}); // => the whole body for '/v2/quotations'

const rawSignature = `${time}\r\n${method}\r\n${path}\r\n\r\n${body}`;
// => '1546222219293\r\nPOST\r\n/v2/quotations\r\n\r\n{\n \"scheduleAt\": \"2018-12-31T14:30:00.00Z\",\n \"serviceType\": \"MOTORCYCLE\",\n \"requesterContact\": { \"name\": \"Peter Pan\", \"phone\": \"232\" },\n \"stops\": [\n {\n \"location\": { \"lat\": \"-6.255431000000001\", \"lng\": \"106.60114290000001\" },\n \"addresses\": {\n \"en_ID\": {\n \"displayString\":\n \"Jl. Perum Dasana Indah No.SD 3/ 17-18, RT.3/RW.1, Bojong Nangka, Klp. Dua, Tangerang, Banten 15810, Indonesia\",\n \"market\": \"ID\"\n }\n }\n },\n {\n \"location\": { \"lat\": \"-6.404722800000001\", \"lng\": \"106.81902130000003\" },\n \"addresses\": {\n \"en_ID\": {\n \"displayString\": \"Jl. Kartini, Ruko No. 1E, Depok, Pancoran MAS, Kota Depok, Jawa Barat 16431, Indonesia\",\n \"market\": \"ID\"\n }\n }\n }\n ],\n \"deliveries\": [\n {\n \"toStop\": 1,\n \"toContact\": {\n \"name\": \"mm\",\n \"phone\": \"9999999\"\n }\n }\n ]\n}\n'

const SIGNATURE = CryptoJS.HmacSHA256(rawSignature, SECRET).toString();
// => '5133946c6a0ba25932cc18fa3aa1b5c3dfa2c7f99de0f8599b28c2da88ed9d42'

SIGNATURE = HmacSHA256ToHex(<TIMESTAMP>\r\n<HTTP_VERB>\r\n<PATH>\r\n\r\n<BODY>, <SECRET>)

SIGNATURE is in lowercase hex (base 16) encoding.

SECRET Your API secret
TIMESTAMP Unix timestamp in milliseconds eg. 1545880607433
HTTP_VERB HTTP verb (GET, POST, PUT, DELETE) of the specific API call
PATH The pathname of the specific API call including version. eg. /v2/quotations
BODY The request body in JSON string

Useful links

Headers

Example in JavaScript (cont.)

const API_KEY = "914c9e52e6414d9494e299708d176a41";
const TOKEN = `${API_KEY}:${time}:${SIGNATURE}`;
// => '914c9e52e6414d9494e299708d176a41:1545880607433:5133946c6a0ba25932cc18fa3aa1b5c3dfa2c7f99de0f8599b28c2da88ed9d42'
Authorization: hmac <TOKEN>
X-LLM-Market: <YOUR_MARKET>
X-Request-ID: <NONCE>

Example

Authorization: hmac 914c9e52e6414d9494e299708d176a41:1545880607433:5133946c6a0ba25932cc18fa3aa1b5c3dfa2c7f99de0f8599b28c2da88ed9d42
X-LLM-Market: TH_BKK
X-Request-ID: 211b9d85-a2cc-476f-8675-b61ec923cc27

Authorization

TOKEN = <KEY>:<TIMESTAMP>:<SIGNATURE>

KEY Your API key
TIMESTAMP MUST be identical to TIMESTAMP in SIGNATURE
SIGNATURE As described in Signature in lowercase hex (base 16)

X-LLM-Market

Please specify the city you are placing orders in UN/LOCODE format. For example, Jakarta wil be listed as ID_JKT. See Available Markets for details.

X-Request-ID

Provide a Nonce to be used as an unique Request ID. It helps us with preventing replay attacks.

Sample Code

(Revised in June, 2021)

To help you kick start your developement work easily, we have prepared sample code in the following languages:

Please visit Lalamove REST API Examples (Link) for more information.

Order Flow

Click the below diagram to enlarge.

order-flow

Order Status

Dotted lines in the following diagram indicates possible status transition.

status

ASSIGNING_DRIVER Trying to match shipment with a driver.
ON_GOING A driver has accepted the order.
PICKED_UP The driver has picked up the order.
COMPLETED The order has been delivered sucessfully and transaction has concluded.
CANCELED User has canceled the order.
REJECTED The order was matched and rejected twice by two drivers in a row, see Order Flow.
EXPIRED The order expired as no drivers accepted the order.

Immediate vs Scheduled

Immediate Order

{
  //"scheduleAt": "2020-09-01T14:30:00.00Z",
  "serviceType": "MOTORCYCLE",
  "stops": [<Waypoint>],
  "deliveries": [<DeliveryInfo>],
  "requesterContact": <Contact>,
  "specialRequests": ["COD", "HELP_BUY", "LALABAG"]
}

Scheduled Order

{
  "scheduleAt": "2020-09-01T14:30:00.00Z",
  "serviceType": "MOTORCYCLE",
  "stops": [<Waypoint>],
  "deliveries": [<DeliveryInfo>],
  "requesterContact": <Contact>,
  "specialRequests": ["COD", "HELP_BUY", "LALABAG"]
}

Depending on your delivery needs, you can place an immediate order or a schedule order.

User Cancellation

An order can only be cancelled either:

  1. An order with the status ASSIGNING_DRIVER; or
  2. An order is matched less than 5 minutes - order status changed from ASSIGNING_DRIVER to ON_GOING less than 5 minutes ago. This holds regardless of the actual scheduleAt.

Driver Rejection

Orders can be rejected after they are matched to a driver. When this happens, the order status will revert from ON_GOING/ PICKED_UP to ASSIGNING_DRIVER. Lalamove system will try to match it again with a different driver. If an order has been rejected for the second time, the order status will be revised as REJECTED. Lalamove system will no longer broadcast this order to the driver pool - the system will stop matching a driver for this order.

Expired Orders

An order will be expired if it is not accepted by the driver. Depending the order type (immediate vs scheuduled) order expiry time varies.

Available Markets

Lalamove API is currently available for the following markets.

Markets ISO 3166-1 alpha-2 With UN/LOCODE Locale Keys
Brasil BR BR_SAO,BR_RIO, BR_BHZ, BR_POA en_BR,pt_BR
Hong Kong, China HK HK_HKG en_HK, zh_HK
Indonesia ID ID_BDO,ID_JKT, ID_SUB en_ID, id_ID
Malaysia MY MY_JHB,MY_KUL,MY_NTL en_MY, ms_MY
Mexico MX MX_MEX en_MX, es_MX
Philippines PH PH_CEB,PH_MNL,PH_PAM en_PH
Singapore SG SG_SIN en_SG
Taiwan, China TW TW_KHH,TW_TNN,TW_TPE,TW_TXG zh_TW
Thailand TH TH_BKK, TH_PYX th_TH, `en_T
Vietnam VN VN_HAN, VN_SGN en_VN, vi_VN

Phone Validation

The following table shows how phone numbers are validated for each market.

Markets Sample Regex
Brasil 11912345678 /^[0-9]{2}[9]{1}[0-9]{8}$/
Hong Kong, China 37013701 /^((?!999)([2-9][0-9]{7}))$/
Indonesia 0212145678 /^0(8\\d{8,11}|21\\d{7,8})$/
Malaysia 0376886555 /^0(1[1,5]?\\d{8}|[4-7,9]\\d{7}|8[2-9]\\d{6}|3\\d{8})$/
Mexico 7178277017 /^([+]+52?)?(\d{3}?){2}\d{4}$/
Philippines 09051234567 /^09[0-9]{9}$|^0?2[0-9]{7}$|^0?32[0-9]{7}$/
Singapore 81234567 /^[3689]{1}[0-9]{7}$/
Taiwan, China 0912345678 /^0([1-8]{1}[0-9]{7,8}|9[0-9]{8})$/
Thailand 0812345678 /^(0[0-9]{8,9}|[0-9]{4})$/
Vietnam 912345678 /^0?(2|[35789])[0-9]{8}$|^02[48][0-9]{8}$/

Service Types

Lalamove provides a range of vehicles to cater different needs at different cities.

Brasil

City Code UTC offset Pricing / Preços
Belo Horizonte BR_BHZ UTC -3 https://www.lalamove.com/pt-br/detalhes/sao-paulo?&city=belo-horizonte (Portugese)
Rio de Janeiro BR_RIO UTC -3 https://www.lalamove.com/pt-br/detalhes/sao-paulo?&city=rio-de-janeiro
São Paulo BR_SAO UTC -3 https://www.lalamove.com/pt-br/detalhes/sao-paulo?&city=sao-paulo
Porto Alegre BR_POA UTC -3 https://www.lalamove.com/pt-br/detalhes/sao-paulo?&city=porto-alegre

Service Types

Key Description Shipment restrictions BR_BHZ BR_RIO BR_SAO BR_POA
LALAGO LALAGO 35 × 40 × 30 cm, 20kg
LALAPRO LALAPRO 40 × 40 × 35 cm, 20kg
MPV MPV/SUV 125 × 80 × 60 cm, 200kg
UV_FIORINO UV / Utilitário 188 × 133 × 108 cm, 500kg
TRUCK330 Truck / Carreto 300 × 180 × 200 cm, 1,500kg (1.5Ton)
CAR Sedan 120 x 80 x 60 cm, 200kg

Special Requests

Description LALAGO LALAPRO MPV UV_FIORINO TRUCK330 CAR
INSULATED_BAG Insulated Bag
HELPER (Only for POA)
HELPER_2
(Only for POA)
HELPER_3
(Only for POA)

Hong Kong, China

City Code UTC offset Pricing
Hong Kong, China HK_HKG UTC +8 https://www.lalamove.com/en-hk/all-vehicle-pricing-detail

Service Types

Key Description Shipment restrictions
WALKER Walker 40 × 40 × 40 cm, 10 kg
MOTORCYCLE Motorcycle 40 × 40 × 40 cm, 10 kg
VAN Van 182 × 121 × 121 cm, 700 - 800 kg
TRUCK550 5.5 Ton 450 × 195 × 195 cm, 800 - 1,200 kg
COURIER Matched with available vehicles incl.
Motorcycle
Walker
Van

Special Requests

Description WALKER MOTORCYCLE VAN TRUCK550
LALABAG Thermal Bag

Indonesia

City Code UTC offset Pricing / Harga
Bandung ID_BDO UTC +7 https://www.lalamove.com/en-id/delivery-fee?&city=bandung
Jakarta ID_JKT UTC +7 https://www.lalamove.com/en-id/delivery-fee?city=jakarta
Surabaya ID_SUB UTC +7 https://www.lalamove.com/en-id/delivery-fee?city=surabaya

Service Types

Key Description Shipment restrictions
MOTORCYCLE Motor 40 x 40 x 40 cm, 20 kg
SEDAN Sedan 150 x 80 x 80cm, 100kg
MPV Mobil 175 x 100 x 85 cm, 350 kg
VAN Van 210 x 150 x 120 cm, 600 kg
TRUCK175 Pickup Bak 200 x 160 x 120 cm, 800 kg
TRUCK330 (only in JKT) Pickup Box (1 ton) 240 x 160 x 120 cm, 1200 kg

Special Requests

Description MOTORCYCLE SEDAN MPV VAN TRUCK175
PURCHASE_SERVICE Purchase Service < 300K Rp
DOOR2DOOR Door to Door Delivery
EXTRA_HELPER Door to Door Delivery with 1 Helper
EXTRA_HELPER_TRUCK175 Door to Door Delivery with 1 Helper
ROUNDTRIP_MOTORCYCLE Roundtrip for Motorcycle
ROUNDTRIP Roundtrip
LALABAG Lalabag
TOLL Toll fee

Malaysia

City Code UTC offset Pricing / Harga
Kuala Lumpur MY_KUL UTC +8 https://www.lalamove.com/en-my/all-vehicle-pricing-detail
Johor Bahru MY_JHB UTC +8 https://www.lalamove.com/en-my/all-vehicle-pricing-detail?city=johor
Penang MY_NTL UTC +8 https://www.lalamove.com/en-my/all-vehicle-pricing-detail?&city=penang

Service Types

Key Description Shipment restrictions
MOTORCYCLE Motorcycle / Motosikal 36 x 36 x 36 cm, 10 kg
CAR Car / Kereta 100 x 90 x 75 cm, 40 kg
VAN Van 170 x 115 x 115 cm, 500 kg
4X4 4X4 120 x 91 x 91 cm, 250 kg
TRUCK330 1-Ton Lorry / Lori 1-Tan 275 x 152 x 152 cm・1,000 kg
TRUCK550 3-Ton Lorry / Lori 3-Tan 427 x 220 x 213 cm・3,000 kg

Special Requests

Description MOTORCYCLE CAR TRUCK330
MY_KULonly
TRUCK550
MY_KULonly
PURCHASE_SERVICE Buy4U
LALABAG Lalabag
DOOR2DOOR Door to Door delivery
DOOR2DOOR_TRUCK330 Moving Services by Driver
DOOR2DOOR_TRUCK550 Moving Services by Driver
DOOR2DOOR_1HELPER_TRUCK330 Moving Services by Driver + 1 Helper
DOOR2DOOR_1HELPER_TRUCK550 Moving Services by Driver + 1 Helper
DOOR2DOOR_2HELPER_TRUCK330 Moving Services by Driver + 2 Helpers
DOOR2DOOR_2HELPER_TRUCK550 Moving Services by Driver + 2 Helpers
RETURNTRIP Return Trip
LOADING_SERVICE Loading Service

Mexico

City Code UTC offset Pricing Details
Mexico City / Ciudad de México MX_MEX UTC -6 (Standard) /
UTC -5 (Daylight saving)
https://www.lalamove.com/es-mx/todos-vehiculos-tarifa-detalles

Service Types

Key Description Shipment restrictions
MOTORCYCLE Motorcycle/Moto 40 × 40 × 35 cm, 20 kg
MPV MPV/SUV 125 x 80 x 60 cm, 200 kg
UV_FIORINO Minivan/Camioneta 188 x 133 x 108 cm, 500 kg
TRUCK330 Truck/Camión 200 x 200 x 170 cm, 1,000 kg

Special Requests

Description MOTORCYCLE MPV UV_FIORINO TRUCK330
FOOD_SERVICE Food Service

Philippines

City Code UTC offset Pricing Details
Cebu PH_CEB UTC +8 https://www.lalamove.com/en-ph/all-delivery-pricing-detail?&city=cebu
Manila PH_MNL UTC +8 https://www.lalamove.com/en-ph/all-delivery-pricing-detail?&city=manila
Pampanga PH_PAM UTC +8 https://www.lalamove.com/en-ph/all-delivery-pricing-detail?&city=pampanga

Service Types

Key Description Shipment restrictions PH_CEB PH_MNL PH_PAM
MOTORCYCLE Motorcycle 1.6 x 1.25 x 1.6ft, 20 kg
MPV UV (Small) 4 x 3.2 x 2.8 ft, 300 kg
VAN Van 7 x 4 x 3.5 ft, 600 kg
TRUCK330 FB/L300 7 x 4 x 4 ft, 1,000 kg
SEDAN Sedan 3.2 x 1.9 x 2.3 ft, 200kg

Special Requests

Description MOTORCYCLE MPV VAN TRUCK330 SEDAN
COD Cash Handling
LALABAG Insulated Box
QUEUEING_MOTORCYCLE Queueing Service
PURCHASE_SERVICE Purchase Service
(>30minutes waiting: +‎₱60)
DRIVER_CARRIES Driver Carries (max 50kg)
1ASSISTANT_1_MINUS_2DROPS 1 Assistant: 1-2 drops
1ASSISTANT_3_MINUS_4DROPS 1 Assistant: 3-4 drops
1ASSISTANT_5_PLUS_DROPS 1 Assistant: 5+ drops

Singapore

City Code UTC offset Pricing Details
Singapore SG_SIN UTC +8 https://www.lalamove.com/en-sg/all-vehicle-pricing-detail

Service Types

Key Description Shipment restrictions
MOTORCYCLE Bike 40 × 25 × 25 cm, 8 kg
CAR Car 70 × 50 × 50 cm, 20 kg
MINIVAN 1.7m Van 160 × 120 × 100 cm
VAN 2.4m Van 230 × 120 × 120 cm
TRUCK330 10ft Lorry 290 × 140 × 170 cm
TRUCK550 14ft Lorry 420 × 170 × 190 cm

Special Requests

Description MOTORCYCLE CAR MINIVAN VAN TRUCK330 TRUCK550
COD Cash on delivery
RESTRICTED Secured Zone
RETURNTRIP Return Trip (for documents only)
RETURNTRIP_LORRY Return Trip (for documents only)
MOVING_DRIVER_1HELPER_VAN Moving service: Driver + 1 Helper
MOVING_DRIVER_2HELPER_VAN Moving service: Driver + 2 Helpers
MOVING_DRIVER Moving service: Driver
MOVING_DRIVER_1HELPER Moving service: Driver + 1 Helper
MOVING_DRIVER_2HELPER Moving service: Driver + 2 Helpers
TAILGATE Tailgate

Taiwan, China

City Code UTC offset Pricing Details
Taipei TW_TPE UTC +8 https://www.lalamove.com/zh-tw/all-vehicle-pricing-detail
Taichung TW_TXG UTC +8 https://www.lalamove.com/zh-tw/all-vehicle-pricing-detail
Tainan TW_TNN UTC +8 https://www.lalamove.com/zh-tw/all-vehicle-pricing-detail
Kaohsiung TW_KHH UTC +8 https://www.lalamove.com/zh-tw/all-vehicle-pricing-detail

Service Types

Key Description Shipment restrictions
MOTORCYCLE Motorcycle 30 × 60 × 40 cm, 20 kg
MPV SUV 100 × 100 × 100 cm, 200 kg (individual item weighing < 20 kg)
VAN Van 150 × 100 × 100 cm, 300 kg (individual items weighing < 20 kg)
TRUCK175 Truck 200 × 120 × 120 cm, 500 kg (individual items weighing < 20 kg)

Special Requests

Description MOTORCYCLE MPV VAN TRUCK175
LALABAG Lalamove專用保溫袋 詳情按此
HELP_BUY 需代付款,上限 $2000(請在remarks欄備註金額) 詳情按此
MOVING_UPSTAIR_WITH_LIFT MOVING_GOODS_UPSTAIR_(REQUIRE_LIFT)

Thailand

City Code UTC offset Pricing Details
Bangkok TH_BKK UTC +7 https://www.lalamove.com/en-th/all-vehicle-pricing-detail
Chonburi TH_PYX UTC +7 https://www.lalamove.com/en-th/all-vehicle-pricing-detail

Service Types

Key Description Shipment restrictions TH_BKK TH_PYX
MOTORCYCLE Motorcycle 50 × 50 × 50 cm, 20 kg
CAR Sedan 100 x 90 x 75 cm, 100kg
SUV SUV 160 x 130 x 80 cm, 300kg
MPV Hatchback 115 × 115 × 80 cm, 100 kg
TRUCK330 Box Truck 170 × 150 × 170 cm, 1,000 kg
TRUCK175 Fence Truck 210 x 170 x 170 cm,
4,000 kg
PICK_UP_TRUCK Pick-Up Truck 190 x 170 x 200 cm, 1,100 kg

Special Requests

Description MOTORCYCLE CAR MPV SUV TRUCK330 TRUCK175 PICK_UP_TRUCK
COD Cash on delivery
ROUNDTRIP Round Trip
DOOR2DOOR Door to door (by driver)
DOOR2DOOR_WITH_WORKER Door to Door (by driver) + 1 Worker
EXTRA_LENGTH Extra Length of 2.1 M (standard 1.7 M)
EXTRA_HEIGHT Extra Height of 1.9 M (standard 1.7 M)
LALABAG Food Delivery Box
HELP_BUY Purchase Service (THB 1 - 1,500).
  1. Input your details, amount and price of the desired goods in DeliveryInfo.remarks
  2. Make sure the recepient carries sufficient amount of cash to pay our driver
PURCHASE_SERVICE_2 Purchase Service (THB 1,500 - 3,000)
PURCHASE_SERVICE_3 Purchase Service (THB 3,000 - 4,500)
PURCHASE_SERVICE_4 Purchase Service (THB 4,500 - 6,000)
[Being Deprecated]
PURCHASE_SERVICE_TIER_2
Purchase Service (THB 1,000 - 2,000)

Vietnam

City Code UTC offset Pricing Details
Hanoi VN_HAN UTC +7 https://www.lalamove.com/en-vn/all-vehicle-pricing-detail?&city=hanoi
Ho Chi Minh City VN_SGN UTC +7 https://www.lalamove.com/en-vn/all-vehicle-pricing-detail?&city=hochiminhcity

Service Types

Key Description Shipment restrictions VN_HAN VN_SGN
MOTORCYCLE Motorcycle 40 x 40 x 40cm, 30kg
VAN Van 500kg 120 x 100 x 120cm, 500kg
VAN_1000 Van 1000kg 190 x 100 x 120cm, 1,000kg
TRUCK175 Truck 500kg 200 x 120 x 120cm, 500kg
TRUCK330 Truck 1000kg 300 x 160 x 160cm, 1,000kg
TRUCK550 Truck 2000kg 430 x 190 x 200cm, 2,000kg
PICK_UP_TRUCK Pickup Truck 140 x 150 x 50cm, 500kg

Special Requests

Description MOTORCYCLE VAN VAN_1000 TRUCK175 TRUCK330 TRUCK550 PICK_UP_TRUCK
LALABAG Insulated Box
ROUNDTRIP Round Trip
DOOR2DOOR Door-to-door delivery
GROUND_FLOOR_ONE_WAY Moving Help: Ground floor (1-way)
GROUND_FLOOR_TWO_WAYS Moving Help: Ground floor (2-way)
UPSTAIR_DOWNSTAIR_ONE_WAY Moving Help: Stairs (1-way)
UPSTAIR_DOWNSTAIR_TWO_WAYS Moving Help: Stairs (2-way)
PURCHASE_SERVICE_1 Purchase Service (Under 1m )
PURCHASE_SERVICE_2 Purchase Service (Under 2m)
PURCHASE_SERVICE_3 Purchase Service (Under 3m)

Get Quotation

POST https://rest.sandbox.lalamove.com/v2/quotations
POST https://rest.lalamove.com/v2/quotations

Body

{
  "scheduleAt": "2020-09-01T14:30:00.00Z",
  "serviceType": "MOTORCYCLE",
  "stops": [<Waypoint>],
  "deliveries": [<DeliveryInfo>],
  "requesterContact": <Contact>,
  "specialRequests": ["COD", "HELP_BUY", "LALABAG"]
}

Responses

200 Quotation Created

{ 
  "totalFee": "108000", 
  "totalFeeCurrency": "THB",
  "distance": {
    "text": "16.2 km",
    "value": 16210
  }
}

409 Stops and Deliveries mismatch, see DeliveryInfo

{ "message": "ERR_DELIVERY_MISMATCH" }

409 Not enough stops, number of stops should be between 2 and 16

{ "message": "ERR_INSUFFICIENT_STOPS" }

409 Reached maximum number of stops (including the pick-up point), should be between 2 and 17

{ "message": "ERR_TOO_MANY_STOPS" }

409 Invalid payment method

{ "message": "ERR_INVALID_PAYMENT_METHOD" }

409 Invalid locale, refer to Waypoint

{ "message": "ERR_INVALID_LOCALE" }

409 Invalid market, getting a quotation from a market not supported (by your credentials)

{ "message": "ERR_INVALID_MARKET" }

409 Invalid phone number, refer to Phone Validation

{ "message": "ERR_INVALID_PHONE_NUMBER" }

409 scheduleAt datetime is in the past

{ "message": "ERR_INVALID_SCHEDULE_TIME" }

409 No such service type, make sure to stick to Service types in each markets

{ "message": "ERR_INVALID_SERVICE_TYPE" }

409 No such special request(s), make sure that special requests match with selected Service types

{ "message": "ERR_INVALID_SPECIAL_REQUEST" }

409 Out of service area

{ "message": "ERR_OUT_OF_SERVICE_AREA" }

409 Fail to reverse from address to location, provide lat and lng

{ "message": "ERR_REVERSE_GEOCODE_FAILURE" }

POST /v2/quotations

Request a quotation.

Will return an object containing the fee amount, currency, and distance based on information provided.

Note that distance is computed from the pick-up location and drop-off location(s).

Field Description
Text Truncated string value of the distance, rounded up to tenth decimal before 0 (ex: 0.1).
Value Full integer value of the distance with Meters as its standard unit

Body

serviceType string The type of vechicle. See service types available in each market
stops Waypoint[] Array of Waypoints (minimum 2, maximum 10)
deliveries DeliveryInfo[] Array of DeliveryInfos
requesterContact Contact Contact person at pick up point aka stop[0], see Contact
Optional fields
scheduleAt string Pick up time in UTC timezone and ISO 8601 format; omit this if you are placing an immediate order
specialRequests string[] See special requests available in each market

scheduleAt

Our API will interpret the scheduleAt time in UTC format (Coordinated Universal Time) only. Therefore please make sure you submit your requests factoring this in. Please see the example below.

You would like to place a order with a scheduleAt time of 2020-07-10 15:00, local time in Singapore. Singapore is UTC +8 timezone. Therefore your scheduleAt time entry should be 2020-07-10T07:00:00.000Z. Please find below your current timezone compared side-by-side with UTC.

Your Local Time UTC Time

requesterContact

If you are a business, this will need to be your physical pick up location's contact information. Example for a multi-branch business:

Branch requesterContact
ACME Branch A {name: "ACME Branch A", phone: "8912121212"}
ACME Branch B {name: "ACME Branch B", phone: "8912121213"}
ACME Branch C {name: "ACME Branch C", phone: "8912121214"}

Waypoint

Waypoint

{
  "location": { 
    "lat": "13.740167", 
    "lng": "100.535237" 
    },
  "addresses": {
    "th_TH": {
      "displayString": "444 ถนน พญาไท แขวง วังใหม่ เขต ปทุมวัน กรุงเทพมหานคร 10330 ประเทศไทย",
      "market": "TH_BKK"
    }
  }
}

LOCALE is composed of ISO 639-1 language code and ISO 3166-1 alpha-2 code as follow:

{ISO 639-1}_{ISO 3166-1 alpha-2}.

See what locale keys are available in each market

location.lat string Latitude
location.lng string Longitude
addresses[<LOCALE>].displayString string Street address in plain text. Use remarks in DeliveryInfo for building, floor and flat
addresses[<LOCALE>].market string Value must match with X-LLM-Market in the request headers. See Available markets

DeliveryInfo

DeliveryInfo

{
  "toStop": 1,
  "toContact": <Contact>
  "remarks": "ORDER#94\r\n1. Tshirt จำนวน 1\r\n2. Hoodie จำนวน 1\r\n"
}

Contact person, mobile phone number and remarks for each Waypoint excluding the pick up point.

toStop number The index of waypoint in stops this information associates with, has to be >= 1, since the first stop's Delivery Info is tided to requesterContact
toContact Contact See Contact
Optional fields
remarks string Additional info about the delivery. eg. building, floor and flat. Use newline \r\n for better readability

Contact

Contact

// We accept phone number with or without market code. If you do supply a market code, please put "+" before the market code. For example, "+85237013701" or "37013701" are both acceptable for Hong Kong.
{
    "name": "Chris Wong", 
    "phone": "37013701" 
}
name string The name of the contact person
phone string Must be a valid phone number. See Phone Validation on how we validate phone numbers for each market.

Place Order

POST https://rest.lalamove.com/v2/orders
POST https://rest.sandbox.lalamove.com/v2/orders

Body

{
  "quotedTotalFee": { "amount": "108000", "currency": "THB" },
  "sms": false,
  "pod": true,
  // ... merge with body used for quotation
}

Responses

200 Order Created

{
  "orderRef": "<LALAMOVE_ORDER_ID>"
  "totalFee": "<FEE>",
  "totalFeeCurrency": "<LOCAL_CURRENCY>" ,
  "distance": {
    "text": "16.2 km",
    "value": 16210
  }
  // customerOrderId is deprecated in sandbox environment and will be shortly deprecated in production as well.
}

402 You have insufficient credit. Please top up your wallet

{ "message": "ERR_INSUFFICIENT_CREDIT" }

409 The currency you provided in quotedTotalFee.currency is not a valid currency

{ "message": "ERR_INVALID_CURRENCY" }

409 The amount or currency you provided in quotedTotalFee doesn't match quotation

{ "message": "ERR_PRICE_MISMATCH" }

429 Too Many Requests

// no body

POST /v2/orders

Provide the totalFee and totalFeeCurrency received from /quotations as quotedTotalFee.amount and quotedTotalFee.currency merged with the exact same body used for /quotations.

Body

quotedTotalFee.amount string totalFee from /quotations
quotedTotalFee.currency string totalFeeCurrency from /quotations
Optional fields
sms boolean Send delivery updates via SMS to THE recipient, or the recipient of the LAST STOP for multi-stop orders once the order has been picked-up by the driver.
Default to true
pod boolean Request driver to carry out "Proof Of Delivery" for all stops in the order. Default to false. See Proof Of Delivery for details.

Response

customerOrderId Already deprecated and removed in sandbox environment.
orderRef Lalamove Order ID

Order Details

GET https://rest.lalamove.com/v2/orders/{id}
GET https://rest.sandbox.lalamove.com/v2/orders/{id}

GET /v2/orders/{id}

URL Params

id <orderRef> (returned by /v2/orders/)

Responses

200 ASSIGNING_DRIVER

{
    "driverId": "",
    "shareLink": "https://share.lalamove.com/?TH1234556&lang=th_TH&version=2", 
    "status": "ASSIGNING_DRIVER",
    "pod": [
        {toStop:1, status: "PENDING"},
        {toStop:2, status: "PENDING"}
    "price": { "amount": "108000", "currency": "THB" },
    "distance": {
        "text": "16.2 km",
        "value": 16210"
    }
}

200 ON_GOING

{
    "driverId": "33522",
    "shareLink": "https://share.lalamove.com/?TH1234556&lang=th_TH&version=2", 
    "status": "ON_GOING",
    "pod": [
        {toStop:1, status: "PENDING"},
        {toStop:2, status: "PENDING"}
    "price": { "amount": "108000", "currency": "THB" },
    "distance": {
        "text": "16.2 km",
        "value": 16210"
    }
}

200 CANCELED

{
    "driverId": "",
    "shareLink": "https://share.lalamove.com/?TH1234556&lang=th_TH&version=2", 
    "status": "CANCELED",
    "pod": [
        {toStop:1, status: "PENDING"},
        {toStop:2, status: "PENDING"}
    "price": { "amount": "108000", "currency": "THB" },
    "distance": {
        "text": "16.2 km",
        "value": 16210"
    }
}

200 PICKED_UP

{
    "driverId": "33522",
    "shareLink": "https://share.lalamove.com/?TH1234556&lang=th_TH&version=2", 
    "status": "PICKED_UP",
    "pod": [
        {toStop:1, status: "FAILED"},
        {toStop:2, status: "PENDING"}
    "price": { "amount": "108000", "currency": "THB" },
    "distance": {
        "text": "16.2 km",
        "value": 16210"
    }
}

200 REJECTED

{
    "driverId": "",
    "shareLink": "https://share.lalamove.com/?TH1234556&lang=th_TH&version=2", 
    "status": "REJECTED",
    "pod": [
        {toStop:1, status: "PENDING"},
        {toStop:2, status: "PENDING"}
    "price": { "amount": "108000", "currency": "THB" },
    "distance": {
        "text": "16.2 km",
        "value": 16210"
    }
}

200 COMPLETED

{
    "driverId": "33522",
    "shareLink": "https://share.lalamove.com/?TH1234556&lang=th_TH&version=2",
    "status": "COMPLETED",
    "pod": [
        {toStop:1, status: "FAILED"},
        {toStop:2, status: "DELIVERED"}
    "price": { "amount": "108000", "currency": "THB" },
    "distance": {
        "text": "16.2 km",
        "value": 16210"
    }
}

200 EXPIRED

{
    "driverId": "",
    "shareLink": "https://share.lalamove.com/?TH1234556&lang=th_TH&version=2",
    "status": "EXPIRED",
    "pod": [
        {toStop:1, status: "PENDING"},
        {toStop:2, status: "PENDING"}
    "price": { "amount": "108000", "currency": "THB" },
    "distance": {
        "text": "16.2 km",
        "value": 16210"
    }
}

Response

driverId Driver ID of the order. Empty string if order is at ASSIGNING_DRIVER,CANCELED,EXPIRED or REJECTED.
shareLink See Share Link.
status See Order Status.
pod See Proof Of Delivery.
price An object that includes amount and currency of the order.

(Revised in March, 2021)

Share link is meant to be used for sharing delivery information with a 3rd party personnel. The returned link is the same as if a user press "Share" in the Lalamove app. No login is required to view the sharelink.

status

Proof Of Delivery

(Revised in May, 2021)

Proof Of Delivery (POD) is a request that you can put when you placed the order. If you submit an order requesting POD, the driver will be notified to get signature(s) from the recipient(s) (or their delegates) as a proof of a success delivery.

If you want to enable POD for your delivery, please include "pod":true in the request body.

status in POD Description
PENDING Driver has not yet carried out proof of delivery for this stop.
SIGNED The recipient has signed.
DELIVERED The package has been delivered. Recipient (or delegates) did not sign.
FAILED The delivery failed.

Driver Details

GET https://rest.lalamove.com/v2/orders/{orderId}/drivers/{driverId}
GET https://rest.sandbox.lalamove.com/v2/orders/{orderId}/drivers/{driverId}

Responses: 200

{
  "name": "David",
  "phone": "37013701",
  "plateNumber": "LALAM0VE",
  "photo": "<PROFILE_PHOTO_URL>"
}

GET /v2/orders/{orderId}/drivers/{driverId}

Retrieve driver's information.

URL Params

orderId <LALAMOVE_ORDER_ID>
driverId driverId from /orders/{id} response

Driver Location

GET https://rest.lalamove.com/v2/orders/{orderId}/drivers/{driverId}/location
GET https://rest.sandbox.lalamove.com/v2/orders/{orderId}/drivers/{driverId}/location

Responses: 200

{
  "location": { "lat": "13.740167", "lng": "100.535237" },
  "updatedAt": "2017-12-01T14:30.00Z"
}

Responses: 403

// Empty

GET /v2/orders/{orderId}/drivers/{driverId}/location

Retrieve driver's latest location in latitude and longitude.

This information is available starting 1 hour prior to datetime specified in scheduleAt datetime and remain accessible until the order is completed. Attempts made outside of this time window will get 403 Forbidden response.

URL Params

orderId <LALAMOVE_ORDER_ID>
driverId driverId from /orders/{id} response

Cancel Order

PUT https://rest.lalamove.com/v2/orders/{id}/cancel
PUT https://rest.sandbox.lalamove.com/v2/orders/{id}/cancel

Responses

200

{}

409 Cancellation Forbidden

{ "message": "ERR_CANCELLATION_FORBIDDEN" }

PUT /v2/orders/{id}/cancel

Please refer to our cancellation policy here.

Attempts to cancel an order that does not comply with our cancellation policy will get ERR_CANCELLATION_FORBIDDEN as response.

URL Params

id <LALAMOVE_ORDER_ID>

Add Priority Fee

PUT https://rest.lalamove.com/v2/orders/{id}/tips
PUT https://rest.sandbox.lalamove.com/v2/orders/{id}/tips

Body

{
    "tips":"10"
}

(Updated in February, 2021)

PUT /v2/orders/{id}/tips

Priority fees (commonly known as tips) are often used by customers to encourage drivers to accept an order.

  1. Priority fees can only be added before the driver accepts the order. This is the same logic as our user mobile and web app.
  2. Priority fees can be added to the same order on multiple occasions. However, please note the amount added subsequently must be greater than the previous one.
  3. The amount added as a priority fee each time will replace the previous amount. For example, if you were to add HKD10 the first time, followed by a subsequent priority fee of HKD20, the total amount of the priority fee would be HKD20 (as the second request supersedes the first request).

Responses

200

{}

402 You do not have enough credits for the action, please top-up your wallet.

{ "message": "ERR_INSUFFICIENT_CREDIT" }

409 The amount you attempted to add does not reach the minimum amount allowed..

{ "message": "ERR_EXCEED_MIN_TIPS" }

409 The amount you attempted to add exceed the maximum amount allowed.

{ "message": "ERR_EXCEED_MAX_TIPS" }

409 The amount is invalid, e.g. trying to add HKD20.001 while 0.1 cent is not supported in Hong Kong OR you attempted to add an amount lower than or equal to previous requests.

{ "message": "ERR_INVALID_TIPS" }

409 You are trying to add priority fee beyond allowable order status(es).

{ "message": "ERR_INVALID_ORDER_STATUS" }

URL Params

id <LALAMOVE_ORDER_ID>

Webhook

We have introduced webhook to our system. Please refer to the following deck.

tutorial

Errors

The Lalamove API uses the following error codes:

Error Code Meaning
400 -- Bad Request Your request is invalid. Make sure the body is a valid JSON string.
401 -- Unauthorized Your authorization token is incorrect. Make sure to follow instructions in Authentication.
402 -- Payment Required You do not have sufficient credit for the action, please top-up your wallet.
403 -- Forbidden Access to order or driver details is unauthorized.
404 -- Not Found The specified order or driver could not be found.
409 -- Conflict There are a list of possible reasons, please refer to coding section of respective endpoints for details.
429 -- Too Many Requests You're sending in too many requests.
Rate limit: 300 requests per minute (Production environment)
Please stop for 1 minute once you encountered 429.
500 -- Internal Server Error We had a problem with our server. Try again later.

Go-Live

  1. Customers have their own use case scenarios - we do not mandate customers to use all of our APIs. However, please make sure your integration includes both /v2/quotations and /v2/orders.
  2. Before rolling out the intergration to production (or commonly known as "Go-Live"), make sure to top up your Production wallet (You will get Production API credential only after top up). Once you are ready, drop us a note at partner.support@lalalmove.com
  3. You are set! Start submitting orders immediately.

Tutorial

To help you kick-start, you can check out this deck. It is a step-by-step walkthrough of how to make API calls using POSTMAN.

tutorial

Postman Configurations

Please refer to the table below for POSTMAN environment and colleciton files for respective cities (right-click and choose "Save Link As...".

Markets City POSTMAN Environment POSTMAN Collection
Brasil Belo Horizonte (BR_BHZ) Environment Collection
Brasil Rio de Janeiro (BR_RIO ) Environment Collection
Brasil Sao Paulo (BR_SAO) Environment Collection
Hong Kong, China Hong Kong (HK) Environment Collection
Indonesia Bandung (ID_BDO) Environment Collection
Indonesia Jakarta (ID_JKT) Environment Collection
Malaysia Kuala Lumpur (MY_KUL) Environment Collection
Malaysia Johor Bahru (MY_JHB) Environment Collection
Malaysia Penang (MY_NTL) Environment Collection
Mexico Mexico City (MX_MEX) Environment Collection
Philippines Cebu (PH_CEB) Environment Collection
Philippines Manila (PH_MNL) Environment Collection
Philippines Pampanga (PH_PAM) Environment Collection
Singapore Singapore (SG) Environment Collection
Taiwan, China Taipei (TW_TPE) Environment Collection
Taiwan, China Kaohsiung (TW_KHH) Environment Collection
Taiwan, China Taichung (TW_TXG) Environment Collection
Taiwan, China Tainan (TW_TNN) Environment Collection
Thailand Bangkok (TH_BKK) Environment Collection
Thailand Chonburi (TH_PYX) Environment Collection
Vietnam Hanoi (VN_HAN) Environment Collection
Vietnam Ho Chi Minh City (VN_SGN) Environment Collection

FAQ

(Revised in July 2021)

Why do I keep getting 401 - Unauthorized error?

Make sure you are follow the instruction on Authentication closely.

rawSignatureWithBody = `${time}\r\n${method}\r\n${path}\r\n\r\n${body}`;
rawSignatureNoBody = `${time}\r\n${method}\r\n${path}\r\n\r\n`;
// the last \r\n\r\n is untouched

If you are having trouble with requests without body like get order details, make sure you leave the line break characters untouched.

You may also want to refer to Sample Code in the Introduction section.

Does Lalamove API offer webhooks?

Yes. We encourage our customers to utilise webhook for getting prompt updates and better experience. You will use the Partner Portal to setup webhooks.

How do I get notified when an order status has changed?

You are encouraged to use webhook to receive changes in orders status of your placed orders via API.

if you have difficulties in implementing webhooks, please perform polling on /v2/orders/<order_id> using CRON jobs at the maximum rate of 1 request per order per minute to detect status updates until the order is COMPLETED. This should be considered as the interim solution only.

Can I just place an order directly without getting a quotation everytime?

Technically yes. If you know the price in advance, for example there are some pre-defined routes that you have to perform deliveries on a regular basis. You can store the pricing in previous quotations and apply the price directly to POST /v2/orders as quotedTotalFee.

How can I get drivrers to take my orders placed in the sandbox environment?

You can change the orders' statuses in our Partner Portal as per the instruction in the welcome message.

Support

Drop us an email at partner.support@lalamove.com with your questions.

Shopify/WooCommerce

shopify

Lalamove is now available on Shopify, click here to install your plugin now.

For any enquiries on WooCommerce, please drop us an email at channelpartnerships.fd@lalamove.com. Our sales representative will contact you shortly.