Cancel Order

Overview

The Pickup Order Endpoint allows users to schedule a pickup for their orders at a specific date and time, with a choice of vehicle types to accommodate different shipping needs. This ensures flexibility and efficiency in handling order deliveries while maintaining operational constraints.

By leveraging this endpoint, users can manage pickup schedules seamlessly, ensuring that orders are collected by couriers within the allowed timeframe.

Key Feature

✅ Schedule a Courier Pickup Easily : Allows merchants to request a pickup from the logistics partner based on the shipping address and order details provided.
✅ Supports Multiple Couriers : Compatible with various supported courier partners, ensuring flexibility and broad delivery coverage.
✅ Auto-Validation of Pickup Requirements : Validates whether pickup can be scheduled based on courier rules, address eligibility, and required fields before confirming the request.
✅ Pickup Request Status Feedback : Provides clear status messages to indicate if the pickup has been successfully scheduled, or if further action is needed.
✅ Linked to Order Flow : Seamlessly integrates with the order creation process — pickups can only be requested for valid and confirmed orders.
✅ Real-Time Scheduling : Pickup requests are processed immediately, allowing merchants to coordinate handoffs without delay.

How it Works

1. User Schedules a Pickup Request
   • Users provide the pickup date, pickup time, and vehicle type.
   • Orders to be picked up must be specified using their order numbers.
   • The system validates that the selected pickup time is at least 90 minutes from the current time or the order creation time (whichever is later).
2. System Processes the Request
   • The system checks if the orders are eligible for pickup.
   • It ensures the selected vehicle type is appropriate based on the total weight of the orders.
   • If the request meets all requirements, the pickup is scheduled and confirmed.
3. Courier Arrives for Pickup
   • At the scheduled time, the courier will collect the orders from the pickup location.
   • The system updates the status to “Out for Pickup” once the request is confirmed.

Vehicle Selection Guideline

• 🚀 Motorcycle Pickup
  • Recommended for lightweight packages.
  • Each order must not exceed 5 kg.
  • Best suited for small parcels and documents.
• 🚗 Car Pickup
  • Recommended for bulk pickups when multiple orders need to be collected.
  • Suitable for medium-sized packages.
  • Users can group multiple orders in a single pickup request for efficiency.
• 🚛 Truck Pickup
  • Required for shipments weighing 10 kg or more.
  • Ideal for large or heavy orders that exceed the capacity of smaller vehicles.

Request Body

cURL

curl --location 'https://api-sandbox.collaborator.komerce.id/order/api/v1/pickup/request' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: inputapikey' \
--data '{
    "pickup_date": "YYYY-MM-DD",
    "pickup_time": "HH:MM",
    "pickup_vehicle": "{{ Vehicle : Motor/Mobil/Truk }}",
    "orders": [
        {
            "order_no": "KOMXXXXXXXXXXXXXXXXX"
        }
    ]
}'

JavaScript

PHP

GoLang

Node

Query Parameter

Headers

Key	Type	Description
x-api-key*	string	this Value contain an secret APIKEY identic for Shipping API.

Body RAW

Key	Type	Value
pickup_date*	date	Set order pickup days.
pickup_time*	time	Set order pickup hours.
pickup_vehicle*	string	Set order pickup vehicle, only available for Motor, Mobil, and Truk.
orders.order_no*	string	Select the order number that will be scheduled for pickup by the courier, multiple order numbers can be filled in one request.

danger

For each header and parameter that has a * sign, it is a parameter that must be Required when making a request, otherwise there will be a system error that will warn the user regarding the request made.

Response

Response Structure

Key	Value (Description)
meta.message	Message indicating the result of the API request.
meta.code	HTTP status code representing the request status.
meta.status	Status of the API response (e.g., success or error).
data.status	Information on the status of the pickup request to the courier, if the request is successful it will be success, if the request fails it will be failed.
data.order_no	Information from the order number submitted for pickup scheduling
data.awb	Information from the awb number that was successfully obtained for scheduling package pickup from the order number.

Success Respons for Pickup Order

{
    "meta": {
        "message": "Success Request Pickup",
        "code": 201,
        "status": "success"
    },
    "data": [
        {
            "status": "success",
            "order_no": "KOMXXXXXXXXXXXXXXXXX",
            "awb": "KOMERKOMXXXXXXXXXXXXXXXXX"
        }
    ]
}

Error Respons for Pickup Order

{
    "meta": {
        "message": "Success Request Pickup",
        "code": 201,
        "status": "success"
    },
    "data": [
        {
            "status": "failed",
            "order_no": "KOMXXXXXXXXXXXXXXXXXX",
            "awb": ""
        }
    ]
}

Error Code

Code	Status	Description	How to Fix
400	Pickup Failed	Pickup request failed, date pickup is cannot before today	Make sure the pickup request time occurs in the next few hours/day.
401	Unauthorized	API key invalid or missing from parameter	Make sure your API key is valid using your Account
500	Request Failed	Request Pickup failed	Check all body raw request

Tips to Avoid Error

1. Use Valid order_no Values : Ensure each order_no provided exists and is eligible for pickup.
2. Provide Correct pickup_date and pickup_time : Use the format YYYY-MM-DD for dates and HH:mm:ss for times.
3. Specify pickup_vehicle Accurately : Choose from accepted vehicle types like "Motor" or "Mobil".
4. Avoid Duplicate Pickup Requests : Do not send multiple pickup requests for the same order.
5. Validate JSON Payload Structure : Ensure your JSON payload is correctly formatted.
6. Use a Valid API Token : Include a valid and authorized API token in your request headers.
7. Check for Successful Response : A successful request will return a status code of 200 and include AWB numbers in the response.