History AWB Order

Overview

Endpoint provides a detailed view of a shipment's delivery history by tracking the status updates based on its AWB (Air Waybill) number. This endpoint acts as a bridge between your system and the courier's tracking services, offering up-to-date delivery events that help merchants and customers stay informed about their package's journey.

Tracking transparency is crucial for both operational teams and end-users. With this endpoint, businesses can monitor every logistical step-from pickup confirmation to successful delivery-improving delivery reliability, building trust with customers, and streamlining after-sales support in case of delays or delivery issues.

Whether you're managing hundreds of daily shipments or offering individual tracking to customers via your application, this endpoint empowers your system to deliver real-time shipping visibility.

Key Feature

Real-Time Delivery Status Updates: Retrieves real-time tracking history from the courier's system using a valid AWB number. Includes timestamps, status codes, and detailed descriptions.
Courier-Agnostic Integration: Automatically fetches tracking data from the relevant courier, depending on the logistics provider used in the original order.
Structured Timeline: Returns a chronological series of events showing the full lifecycle of a package, from pickup, transit, attempted deliveries, to final delivery or return.
Supports Customer Service Workflows: Can be used to proactively inform customers about delays, resolve complaints faster, and improve support ticket handling.
Enables End-to-End Shipment Monitoring: Useful for operational dashboards or customer-facing tracking pages, allowing both internal teams and buyers to follow shipment progress.
Compatible with Label-Generated Shipments: Designed to work in tandem with the POST /label-order process, ensuring traceability for each AWB assigned via the Komerce platform.

How it Works

Order Label is Generated: When an order is created and labeled via POST /label-order, an AWB number is returned from the courier.
Tracking Request Made: Send a GET request to the /history-airwaybill endpoint with the AWB number included as a query parameter.
System Connects with Courier: Komerce routes the request to the relevant courier's tracking system and retrieves the complete tracking log for that shipment.
Receive Status Timeline: The API responds with a list of historical status updates, each containing a date-time, status code, and description of the event.
Integrate with UI or Operations: Display returned data on merchant dashboards, customer tracking pages, or use it for operations follow-up and support tickets.
Refresh As Needed: Poll this endpoint at intervals to refresh delivery status until the package reaches a final state (delivered, returned, canceled, etc.).

Request Body

curl --location 'https://api-sandbox.collaborator.komerce.id/order/api/v1/orders/history-airway-bill?shipping={{courier}}&airway_bill=KOMERKOMXXXXXXXXXXXXXXXXX' \
  --header 'x-api-key: inputapikey'

Query Parameter

Headers

Key	Type	Description
x-api-key *	string	This value contains a secret API key used for the Shipping API.

Query Parameters

Key	Type	Description
shipping *	string	Name of the courier used for delivery of the package.
airway_bill *	string	AWB number that will be checked for package travel history.

danger

All headers and parameters marked with a * are required. If omitted, the system will return an error indicating that the request is invalid.

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.airway_bill	The AWB number being searched for in the travel history.
data.last_status	The latest delivery status information of the AWB.
data.history[].desc	Description of each event in the AWB's travel history.
data.history[].date	Date and time of each travel history event (YYYY-MM-DD HH:MM:SS).
data.history[].code	Status code corresponding to each travel history event.
data.history[].status	General status description for each travel history event.

Success Response for History AWB Order

{
  "meta": {
    "message": "success get data",
    "code": 200,
    "status": "success"
  },
  "data": {
    "airway_bill": "KOMERKOMXXXXXXXXXXXXXXXXX",
    "last_status": "{{ last status }}",
    "history": [
      {
        "desc": "{{ description }}",
        "date": "{{ YYYY-MM-DD HH:MM:SS }}",
        "code": "{{ code }}",
        "status": "{{ status }}"
      }
    ]
  }
}

Error Response for History AWB Order

{
  "meta": {
    "message": "invalid cnote/airway bill",
    "code": 400,
    "status": "error"
  },
  "data": {}
}

Error Codes

Code	Status	Description	How to Fix
200	Success	Successfully retrieved AWB history
400	Invalid	AWB data not found	Make sure the AWB number you are looking for is correct
422	Failed	Failed to retrieve data	Ensure all required request parameters are provided and valid
500	Error	Internal server error	Contact support or retry the request later

Tips to Avoid Errors

Use a valid AWB number generated from a successful POST /label-order call. Invalid or mistyped numbers will return no data or an error.
Wait for pickup confirmation before making tracking requests. If the package hasn't been scanned by the courier yet, the tracking history may be empty.
Not all couriers support real-time tracking or may have delays in updating status. Implement fallback logic for cases where tracking data is temporarily unavailable.
Handle empty or null results gracefully in UI displays and inform users that tracking may not be available yet.
Implement rate-limiting and caching for high-frequency tracking requests to avoid performance bottlenecks or overuse of courier resources.
Avoid exposing query parameter AWB numbers on the client-side if your application needs privacy or added security for tracking details.

← Previous