Order Status
Our API allows you to retrieve the latest delivery updates of your orders.
Overview
These requests allow you to get order status information and an image of your order status page widget with a single HTTPS request.
You can retrieve the current status of an order using set parameters (for example: order number, tracking number, and carrier) through these APIs and get a visual representation of your order status page to display on customer-facing platforms.
Get Order Status Updates
You can retrieve the latest status updates for an order (for example: to display on your order status page) using the v4/track/orders/info endpoint.
The response includes tracking status, checkpoints, and reporting information. Use one of these lookup pairs:
Order number
order_number and account
parcelLab order ID (external_id, a UUID)
external_order_id and account
Carrier tracking number
tracking_number and courier
Other lookup modes, such as external_reference, customer_number, tracking_id, and recipient_email, are listed in the operation reference.
For example, from your server:
curl --get 'https://api.parcellab.com/v4/track/orders/info/' \
--header 'Authorization: Parcellab-API-Token <encoded-token>' \
--data-urlencode 'account=1234567' \
--data-urlencode 'order_number=ORDER-123'Use the v4 parameter names shown here. The v2 names orderNo and user are not the v4 query names. For browser integrations without an API token, access depends on your account's verification settings, such as s (security hash) or recipient_postal_code. Keep API tokens on your server.
Omit live_refresh for a normal lookup. Setting live_refresh=true requests a carrier refresh, so this GET request can cause additional processing.
Retrieves order status information (trackings, checkpoints, and reporting info), typically for customer-facing use cases like an order status page.
Orders can be looked up using one of the following primary identifier sets.
Primary lookup methods:
Order Number: Requires
order_numberandaccount. Optionally,client(Client Key).External Order ID: Requires
external_order_idandaccount.External Reference: Requires
external_referenceandaccount. Note: uniqueness of external references is not ensured by the system.Tracking Number: Requires
tracking_numberandcourier. Optionally,accountCustomer Number: Requires
customer_numberandaccount.Recipient Email: Requires
recipient_emailandaccount.
All lookups can also include these optional parameters:
postal_code: Recipient's postal code.recipient_email: Recipient's email (for secondary verification/filtering).lang: Language for the response content.s: HMAC signature for secure access.live_refresh: Boolean to force a live data refresh from carriers.show_returns: Boolean to include return shipments associated with the order.
Send Authorization: Parcellab-API-Token <encoded-token>.
<encoded-token> = base64(account_id:token) as provided in the portal.
Account of order (if lookup by order number)
Client key of order (if lookup by client key)
Courier of order (if lookup by courier/tracking number)
Customer number of order (if lookup by customer number)
External ID of order (if lookup by external ID)
External reference of tracking (if lookup by external reference)
Language of order status information (falls back to trackings language and 'en' as last choice)
enPerform an inline (live) refresh to the carrier API if applicable.
Order number to lookup (if lookup by order number)
Recipient email of order (if no API token is provided, determines level of information access in accordance with your account setup)
Recipient postal code of order (if no API token is provided, determines level of information access in accordance with your account setup)
Security hash of tracking (if no API token is provided, determines level of information access in accordance with your account setup)
Include return shipments associated with the order.
Only return tracking data that matches the provided tracking number and courier
falseID of tracking (if lookup by tracking ID)
Tracking number of order (if lookup by courier/tracking number)
Resolved URL for starting a return for this order.
Name of the client (e.g. brand), as configured in account setup.
Date of the order
Name of the recipient
Email of the recipient
ISO 3166-1 alpha-3 country code of the destination country
^\w{3}$GET /v4/track/orders/info/ HTTP/1.1
Authorization: Parcellab-API-Token YOUR_BASE64_ENCODED_API_TOKEN
Accept: */*
{
"order_number": "text",
"returns_portal_url": "text",
"client_key": "text",
"order_date": "2026-01-01T00:00:00.000Z",
"recipient_name": "text",
"recipient_email": "text",
"destination_country_iso3": "text",
"trackings": [
{
"tracking_number": "text",
"courier_info": {
"courier": "text",
"courier_name": "text",
"courier_tracking_url": "text",
"hide_tracking_url": false,
"tracking_url_label": "text",
"courier_reroute_url": "text",
"reroute_url_label_short": "text",
"reroute_url_label_long": "text",
"reroute_url_label_info": "text",
"last_mile_courier": "text",
"last_mile_courier_name": "text",
"color_scheme": {
"primary": "text",
"secondary": "text",
"logo_url": "text"
}
},
"last_delivery_status": {
"step": 1,
"status_code": "text",
"status_text": "",
"status_details": "",
"lifecycle_status": "Pending",
"delivery_extra_info": "text",
"exception_type": "text",
"event_timestamp": "2026-01-01T00:00:00.000Z",
"next_action": "text",
"icon_hint": "text"
},
"delivery_location": "text",
"is_delayed": false,
"is_exception": false,
"is_return": false,
"has_multiple_shipments": true,
"is_sms_opt_in": true,
"sms_optin_consent_text": "text",
"action_box": {
"type": "pickup-location",
"label": "text",
"label_communication": "text",
"label_caption": "text",
"address": "text",
"opening_hours": [
{
"day": "mon",
"open": "00:00:00",
"close": "00:00:00"
}
],
"raw": {
"earliest_date": "2026-01-01",
"latest_date": "2026-01-01",
"has_time": true,
"earliest_time": "text",
"latest_time": "text"
}
},
"recipient_name": "text",
"recipient_email": "text",
"recipient_phone": "text",
"destination_country_iso3": "text",
"recipient_postal_code": "text",
"identifiers_consignment": "text",
"order_external_reference": "text",
"warehouse": "text",
"shipping_address": {
"first_name": "text",
"last_name": "text",
"company_name": "text",
"address_line": "text",
"address_line_extra": "text",
"postal_code": "text",
"city": "text",
"country_iso3": "text",
"region_code": "text",
"phone": "text"
},
"articles": [
{
"article_name": "Blue T-Shirt",
"line_item_id": "ITEM-001",
"product_id": "PROD-123",
"quantity": 2,
"sku": "TSHIRT-BLUE-M"
}
],
"articles_order": [
{
"article_name": "Blue T-Shirt",
"line_item_id": "ITEM-001",
"product_id": "PROD-123",
"quantity": 2,
"sku": "TSHIRT-BLUE-M"
}
],
"additional_attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"announced_delivery_date": "2026-01-01",
"announced_delivery_date_min": "2026-01-01",
"pod_identifier": "text",
"pod_signature": "text",
"pod_date": "2026-01-01",
"timezone": "text",
"reporting_info": {
"is_forgotten": true,
"is_delayed": true,
"has_failed_attempt": true,
"is_delayed_dispatch": true,
"is_returned": true,
"is_customer_promise_exceeded": true,
"trending_late_probability": 1,
"trending_late_status": "normal",
"contacted_with_messages": [
"text"
],
"exception_messages": [
"text"
],
"in_transit_date": "2026-01-01T00:00:00.000Z",
"pickup_date": "2026-01-01T00:00:00.000Z",
"courier_dropoff_date": "2026-01-01T00:00:00.000Z",
"delivery_date": "2026-01-01T00:00:00.000Z",
"returned_date": "2026-01-01T00:00:00.000Z"
},
"supports_live_refresh": true,
"checkpoints": [
{
"step": 1,
"courier": "text",
"status_code": "text",
"event_timestamp": "2026-01-01T00:00:00.000Z",
"status_text": "text",
"status_details": "text",
"is_hidden": true,
"location": "text",
"delivery_location_type": "ParcelShop",
"delivery_extra_info": "text",
"estimated_delivery_date": {
"start_date": "2026-01-01",
"end_date": "2026-01-01",
"start_time": "00:00:00",
"end_time": "00:00:00"
},
"exception_type": "text",
"next_action": "text"
}
]
}
]
}Customer Lookup and Multiple Matches
customer_number or recipient_email, each with account, can be used to find an order, subject to account and recipient verification. A recipient_email lookup requires an API token. The response contains one order. If the lookup matches multiple orders, this endpoint returns the first order of an unsorted match set; it does not provide a cursor to retrieve the remaining orders. Use an order or tracking identifier when you need a specific result.
For a complete account-level list, use the authenticated order-list endpoint and its pagination. That endpoint does not expose a customer-number or email filter. Filter the returned orders in your integration if you need all orders for a customer.
Get Order Status Widget
You can retrieve the order status page widget as an image for displaying order status information using the v4/track/orders/info-widget endpoint.
Retrieves order status widget as image
Send Authorization: Parcellab-API-Token <encoded-token>.
<encoded-token> = base64(account_id:token) as provided in the portal.
Account of order (if lookup by order number)
Client key of order (if lookup by client key)
Courier of order (if lookup by courier/tracking number)
Customer number of order (if lookup by customer number)
External ID of order (if lookup by external ID)
External reference of tracking (if lookup by external reference)
Language of order status information (falls back to trackings language and 'en' as last choice)
enPerform an inline (live) refresh to the carrier API if applicable.
Order number to lookup (if lookup by order number)
Recipient email of order (if no API token is provided, determines level of information access in accordance with your account setup)
Recipient postal code of order (if no API token is provided, determines level of information access in accordance with your account setup)
Security hash of tracking (if no API token is provided, determines level of information access in accordance with your account setup)
Include return shipments associated with the order.
Only return tracking data that matches the provided tracking number and courier
falseID of tracking (if lookup by tracking ID)
Tracking number of order (if lookup by courier/tracking number)
GET /v4/track/orders/info-widget/ HTTP/1.1
Authorization: Parcellab-API-Token YOUR_BASE64_ENCODED_API_TOKEN
Accept: */*
binaryLast updated
Was this helpful?