Lalamove MCP by usefulapi

The cities of the connected market with the vehicle types (serviceType keys such as MOTORCYCLE or CAR), their size and load, and the special requests each vehicle accepts. Use these exact keys in lalamove_create_quotation. GET /v3/cities.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

A quotation by id: stops (with stopId), vehicle, price breakdown, currency, distance and expiresAt (a quotation can be ordered for 5 minutes). GET /v3/quotations/{quotationId}.

{
  "type": "object",
  "properties": {
    "quotation_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "Lalamove quotation id (quotationId from lalamove_create_quotation)."
    }
  },
  "required": [
    "quotation_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One delivery order: status (ASSIGNING_DRIVER, ON_GOING, PICKED_UP, COMPLETED, CANCELED, REJECTED, EXPIRED), price breakdown, driver id, share link, distance, stops with proof of delivery and metadata. Only orders from the last 60 days can be read. GET /v3/orders/{orderId}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "Lalamove order id (the orderId of an order, e.g. 107900701184 or a 19-digit id)."
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The driver of an order: name, phone, masked plate number, photo and last known coordinates (updated about every 10 seconds). Lalamove only shares this from 1 hour before the scheduled pickup (or the driver's arrival, whichever is earlier) until the order is completed; outside that window it answers 403. GET /v3/orders/{orderId}/drivers/{driverId}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "Lalamove order id (the orderId of an order, e.g. 107900701184 or a 19-digit id)."
    },
    "driver_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "Lalamove driver id (the driverId of the order once a driver accepted it)."
    }
  },
  "required": [
    "order_id",
    "driver_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Where is my delivery: the order status, stop-level proof of delivery and share link, plus (when a driver has the order and it is on its way) the driver's name and live coordinates. Two reads: GET /v3/orders/{orderId} and, if a driver is assigned and the order is ON_GOING or PICKED_UP, GET /v3/orders/{orderId}/drivers/{driverId}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "Lalamove order id (the orderId of an order, e.g. 107900701184 or a 19-digit id)."
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Price a delivery: 2-16 stops (the first is the pickup, the rest are drop-offs), a vehicle type and optional extras. Returns quotationId, per-stop stopId, the price breakdown and currency, distance and expiresAt (about 5 minutes). It creates a quotation only: nothing is ordered and nothing is charged. Get the vehicle keys from lalamove_list_cities. Show the price to the user before placing an order. POST /v3/quotations.

{
  "type": "object",
  "properties": {
    "service_type": {
      "type": "string",
      "pattern": "^[A-Z0-9_]{1,60}$",
      "description": "Vehicle key from lalamove_list_cities, e.g. MOTORCYCLE, CAR, VAN."
    },
    "stops": {
      "minItems": 2,
      "maxItems": 16,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500,
            "description": "Street address in plain text."
          },
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude, decimal degrees."
          },
          "lng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude, decimal degrees."
          }
        },
        "required": [
          "address",
          "lat",
          "lng"
        ]
      },
      "description": "The stops in order: stop 1 = pickup, the others = drop-offs (2-16 stops)."
    },
    "schedule_at": {
      "description": "Pickup time in UTC (ISO 8601, ending in Z), up to 30 days ahead. Omit for an immediate delivery. Local 15:00 in Singapore (UTC+8) is 07:00Z.",
      "type": "string"
    },
    "special_requests": {
      "description": "Special request keys valid for the vehicle (lalamove_list_cities), e.g. COD, DOOR_TO_DOOR.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Z0-9_]{1,60}$"
      }
    },
    "language": {
      "description": "Address language key, e.g. en_HK or zh_HK. Default: English for the market.",
      "type": "string",
      "pattern": "^[a-z]{2}_[A-Z]{2}$"
    },
    "route_optimized": {
      "description": "Let Lalamove reorder the drop-offs for the cheapest route (needs 3+ stops).",
      "type": "boolean"
    },
    "priority_tier": {
      "description": "Priority tier: faster matching, higher price. Default false (regular tier).",
      "type": "boolean"
    },
    "item": {
      "description": "Item information (only supported in Thailand, Vietnam and Hong Kong).",
      "type": "object",
      "properties": {
        "quantity": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000
        },
        "weight": {
          "description": "Weight enum from the city's deliveryItemSpecification, e.g. LESS_THAN_3_KG.",
          "type": "string",
          "pattern": "^[A-Z0-9_]{1,40}$"
        },
        "categories": {
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Z0-9_]{1,40}$"
          }
        },
        "handling_instructions": {
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Z0-9_]{1,40}$"
          }
        }
      }
    }
  },
  "required": [
    "service_type",
    "stops"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, SPENDS MONEY: order a delivery from a quotation. In production the total price is charged to the prepaid Lalamove wallet and a driver is dispatched; cancellation is only free within Lalamove's policy. Only call it after the user has seen the quotation price and said yes. confirm_total must equal the quotation total (it is checked against Lalamove, and an expired quotation is refused). The recipients are given in stop order and matched to the quotation's drop-off stops by the tool. The order is placed once: do not retry after an error without checking lalamove_get_order. POST /v3/orders.

{
  "type": "object",
  "properties": {
    "quotation_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "Lalamove quotation id (quotationId from lalamove_create_quotation)."
    },
    "sender": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Pickup contact name (shown to the driver)."
        },
        "phone": {
          "type": "string",
          "pattern": "^\\+[1-9]\\d{1,14}$",
          "description": "Phone number in E.164 format with the country code, e.g. +85256847123."
        }
      },
      "required": [
        "name",
        "phone"
      ],
      "description": "Contact at the pickup stop."
    },
    "recipients": {
      "minItems": 1,
      "maxItems": 15,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Recipient name."
          },
          "phone": {
            "type": "string",
            "pattern": "^\\+[1-9]\\d{1,14}$",
            "description": "Phone number in E.164 format with the country code, e.g. +85256847123."
          },
          "remarks": {
            "description": "Note for the driver at this stop (building, floor, ...), up to 1500 characters.",
            "type": "string",
            "maxLength": 1500
          }
        },
        "required": [
          "name",
          "phone"
        ]
      },
      "description": "One contact per drop-off stop, in the same order as the quotation's stops after the pickup."
    },
    "proof_of_delivery": {
      "description": "Ask the driver for a photo or signature at each stop.",
      "type": "boolean"
    },
    "metadata": {
      "description": "Your own reference key/value pairs stored on the order (e.g. your order number).",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 60
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      }
    },
    "confirm_total": {
      "type": "string",
      "pattern": "^\\d{1,12}(\\.\\d{1,4})?$",
      "description": "The total price the user approved, exactly as in the quotation priceBreakdown.total (e.g. \"124\")."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true. Set it only after the user has explicitly confirmed this action."
    }
  },
  "required": [
    "quotation_id",
    "sender",
    "recipients",
    "confirm_total",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, SPENDS MONEY: add a priority fee (tip) to an order to attract a driver. Only possible before a driver accepts the order. The amount replaces the earlier fee and must be higher than it; the difference is charged to the wallet. Amount in the market's currency (see the order's priceBreakdown.currency). POST /v3/orders/{orderId}/priority-fee.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "Lalamove order id (the orderId of an order, e.g. 107900701184 or a 19-digit id)."
    },
    "amount": {
      "type": "string",
      "pattern": "^(?!0+(\\.0+)?$)\\d{1,9}(\\.\\d{1,2})?$",
      "description": "The new total priority fee, e.g. \"20\"."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true. Set it only after the user has explicitly confirmed this action."
    }
  },
  "required": [
    "order_id",
    "amount",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, DESTRUCTIVE: cancel a delivery order. Lalamove only allows it while the order is ASSIGNING_DRIVER, or less than 5 minutes after a driver accepted it; otherwise it answers ERR_CANCELLATION_FORBIDDEN. A cancelled order cannot be revived, only re-placed from a new quotation. DELETE /v3/orders/{orderId}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "Lalamove order id (the orderId of an order, e.g. 107900701184 or a 19-digit id)."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true. Set it only after the user has explicitly confirmed this action."
    }
  },
  "required": [
    "order_id",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: ask Lalamove to replace the driver of an order (no extra fee). Allowed 15 minutes after the driver was matched and before pickup; the order goes back to ASSIGNING_DRIVER and a new driver is looked for. Needs the current driver id from lalamove_get_order. DELETE /v3/orders/{orderId}/drivers/{driverId}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "Lalamove order id (the orderId of an order, e.g. 107900701184 or a 19-digit id)."
    },
    "driver_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "Lalamove driver id (the driverId of the order once a driver accepted it)."
    },
    "reason": {
      "type": "string",
      "enum": [
        "DRIVER_LATE",
        "DRIVER_ASKED_CHANGE",
        "DRIVER_UNRESPONSIVE",
        "DRIVER_RUDE"
      ],
      "description": "Why the driver is changed."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true. Set it only after the user has explicitly confirmed this action."
    }
  },
  "required": [
    "order_id",
    "driver_id",
    "reason",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}