Update Status and Info
This page guides you on how to update shipment statuses and tracking information for orders using the Fynd Platform SDK. It covers API methods for marking a shipment as assigned or not assigned to a delivery partner (DP), and for updating real-time tracking details, with ready-to-use code examples and explanations.
When to Use
- updateShipmentStatus API: Use when you need to change the shipment's OMS state (e.g., from
"ready_to_ship"to"dp_assigned"). - updateShipmentTracking API: Use for real-time tracking updates (location, status, delivery dates) without changing the OMS state.
This page covers a few common use cases of the updateShipmentStatus API. There are many more use cases and scenarios supported by this method. For the complete list of use cases, parameters, and examples, refer to the updateShipmentStatus API documentation.
Prerequisites
- Access to the Fynd Platform SDK (FDK)
- Valid extension API credentials
- Understanding of Order Management System (OMS) states. Refer to OMS states for the complete list of OMS states.
- Company ID for your platform instance
Update Shipment Status
The updateShipmentStatus method is used to update a shipment and its status. It can also be used to update bags (order items grouped together) present in that shipment.
DP extensions must provide shipment tracking updates in real time. If real-time updates are not possible, updates must be sent at the configured update interval. The DP must update the shipment status to Fynd within the specified interval time.
Metadata Organization
DP extensions can send additional information in meta fields under entities and products:
- Shipment-level metadata: If the information is related to the shipment itself, send it under shipment meta (
entities). - Product-level metadata: If the information is related to items/products within the shipment, send it under products meta (
products).
Example
The following example demonstrates updating a shipment status to "dp_assigned" with complete DP details, tracking information, and delivery metadata:
basicRouter.post('/update_shipment_status', async function view(req, res, next) {
try {
// Replace with your company ID from platform configuration
const platformClient = await fdkExtension.getPlatformClient(1234);
const response = await platformClient.order.updateShipmentStatus({
"body": {
"task": false,
"force_transition": false,
"lock_after_transition": false,
"unlock_before_transition": false,
"resume_tasks_after_unlock": false,
"statuses": [
{
"shipments": [
{
"identifier": "17334083479041568015",
"products": [],
"data_updates": {
"entities": [
{
"filters": [],
"data": {
"meta": {
"courier_partner_extension_id": process.env.EXTENSION_API_KEY,
"courier_partner_scheme_id": "Scheme_id_3",
"sort_code": "1129",
"ewaybill_info": {
"success": true
},
"waybill": [
"6806010004126"
],
"tracking_url": "https://www.test.com/track/package/6806010004126",
"courier_partner_shipper_name": "Test",
"logistics_meta": {
"remark": "NAN"
},
"is_own_account": true,
"shipping_label_provided": false,
"estimated_delivery_date": null,
"promised_delivery_date": null,
"rider_details": {
"name": "xyz",
"phone": "+1234567890"
},
"label": "https://cdn.fynd.com/v2/falling-surf-7c8bb8/fyprod/wrkr/documents/label/PDFs/17291005908611498449.pdf",
"courier_partner_name": "Test Partner Name"
},
"delivery_awb_number": "6806010004126",
"pdf_links": {
"label": "https://cdn.fynd.com/v2/falling-surf-7c8bb8/fyprod/wrkr/documents/label/PDFs/17291005908611498449.pdf"
}
}
}
],
"products": [
{
"filters": [],
"data": {
"meta": {
"courier_partner_extension_id": process.env.EXTENSION_API_KEY,
"courier_partner_scheme_id": "Scheme_id_3",
"sort_code": "1129",
"ewaybill_info": {
"success": true
},
"waybill": [
"6806010004126"
],
"tracking_url": "https://www.test.com/track/package/6806010004126",
"courier_partner_shipper_name": "Test",
"is_own_account": true,
"estimated_delivery_date": null,
"promised_delivery_date": null,
"rider_details": {
"name": "xyz",
"phone": "+1234567890"
},
"label": "https://cdn.fynd.com/v2/falling-surf-7c8bb8/fyprod/wrkr/documents/label/PDFs/17291005908611498449.pdf",
"courier_partner_name": "Test Partner Name"
},
"delivery_awb_number": "6806010004126"
}
}
],
"order_item_status": [
{
"filters": [],
"data": {
"meta": {
"courier_partner_details": {
"courier_partner_extension_id": process.env.EXTENSION_API_KEY,
"courier_partner_scheme_id": "Scheme_id_3",
"courier_partner_name": "Test Partner Name",
"is_own_account": true,
"courier_partner_shipper_name": "Test"
}
}
}
}
]
}
}
],
"status": "dp_assigned",
"exclude_bags_next_state": "",
"split_shipment": false
}
]
}
});
res.json(response);
} catch (err) {
console.error("Error updating shipment status:", err);
// Use appropriate HTTP status codes:
// 400 for bad requests, 500 for server errors
const statusCode = err.status || 500;
res.status(statusCode).json({
success: false,
error: err.message || "Failed to update shipment status"
});
}
});
Update Shipment Status if DP Not Assigned
When a DP assignment attempt fails (due to unavailability, configuration errors, missing agreements, or unsupported locations), update the shipment status to "dp_not_assigned". This clearly communicates that shipment allocation with a logistics partner wasn't successful.
Example
- Status Transition: Always set the shipment status to
"dp_not_assigned". - Data Updates: Populate
data_updateswith the latest attempted DP details so analytics and troubleshooting remain possible (fields:courier_partner_extension_id,courier_partner_scheme_id, etc.). Set"is_own_account": falseif the shipment couldn't be assigned to your account or a partner. - Transition Comments: Add a comment explaining the reason for the assignment failure. Use detailed, structured messages (e.g., include configuration mismatches or missing contracts).
basicRouter.post('/update_shipment_status', async function view(req, res, next) {
try {
// Replace with your company ID from platform configuration
const platformClient = await fdkExtension.getPlatformClient(1234);
const response = await platformClient.order.updateShipmentStatus({
"body": {
"task": false,
"force_transition": false,
"lock_after_transition": false,
"unlock_before_transition": false,
"resume_tasks_after_unlock": false,
"statuses": [
{
"shipments": [
{
"identifier": "17695825620291431134",
"products": [],
"data_updates": {
"entities": [
{
"filters": [],
"data": {
"meta": {
"courier_partner_extension_id": "67a5a7b39b82cd92dc0fd21f",
"courier_partner_scheme_id": "692811bb64377e14d2b8bdf6",
"courier_partner_name": "Bikasboroborzoforward",
"is_own_account": false
}
}
}
],
"products": [
{
"filters": [],
"data": {
"meta": {
"courier_partner_extension_id": "67a5a7b39b82cd92dc0fd21f",
"courier_partner_scheme_id": "692811bb64377e14d2b8bdf6",
"courier_partner_name": "Bikasboroborzoforward",
"is_own_account": false
}
}
}
],
"order_item_status": [
{
"filters": [],
"data": {
"meta": {
"courier_partner_details": {
"courier_partner_extension_id": "67a5a7b39b82cd92dc0fd21f",
"courier_partner_scheme_id": "692811bb64377e14d2b8bdf6",
"courier_partner_name": "Bikasboroborzoforward",
"is_own_account": false
}
}
}
}
]
},
"transition_comments": [
{
"title": "Delivery Partner Assignment Failed",
"message": "Reason: COD agreement required but not configured. Missing cash voucher requirement."
}
]
}
],
"status": "dp_not_assigned"
}
]
}
});
res.json(response);
} catch (err) {
console.error("Error updating shipment status (DP not assigned):", err);
const statusCode = err.status || 500;
res.status(statusCode).json({
success: false,
error: err.message || "Failed to update shipment status"
});
}
});
Response
A successful update returns the shipment's status and identifier, confirming the operation:
{
"statuses": [
{
"shipments": [
{
"status": 200,
"final_state": {
"dp_not_assigned": "dp_not_assigned",
"shipment_id": "12345678927931984116"
},
"identifier": "12345678927931984116"
}
]
}
]
}
Simultaneous attempts to assign DPs should be deduplicated in your system. Always verify if a DP is already assigned before transitioning to "dp_not_assigned".
Update Shipment Tracking Info
The updateShipmentTracking method is used for updating tracking information to show the latest shipment status, location, and delivery timelines. Unlike updateShipmentStatus, this method focuses specifically on tracking updates without changing the shipment's OMS state. It ensures that both the seller and the customer have accurate and up-to-date logistics information.
updateShipmentTrackingExample
The following example demonstrates updating tracking details for a shipment identified by its shipment ID. Key fields such as the AWB number, current DP location, status (dp_status: out_for_delivery), and status update timestamp are provided. Additional information includes the DP's name, the shipment's journey stage, and estimated and promised delivery dates.
basicRouter.post('/update_shipment_tracking', async function view(req, res, next) {
try {
// Replace with your company ID from platform configuration
const platformClient = await fdkExtension.getPlatformClient(8948);
const response = await platformClient.order.updateShipmentTracking({
"body": {
"awb": "6806010004126",
"dp_location": "Mumbai",
"dp_name": "Test bluedart",
"dp_status": "out_for_delivery",
"dp_status_updated_at": "2024-12-06T10:15:30Z",
"estimated_delivery_date": "2024-12-10T10:15:30Z",
"journey": "forward",
"meta": {},
"operational_status": "great",
"promised_delivery_date": "2024-12-10T10:15:30Z",
"remark": "Not Applicable",
"shipment_id": "17334083479041568015"
}
});
res.json(response);
} catch (err) {
console.error("Error updating shipment tracking:", err);
const statusCode = err.status || 500;
res.status(statusCode).json({
success: false,
error: err.message || "Failed to update shipment tracking"
});
}
});
Response
The response confirms the successful update of the tracking details. It echoes back the updated fields, such as the DP status, location, estimated and promised delivery dates, and other metadata. This ensures that all stakeholders, including sellers, buyers, and the logistics team, are aligned with the current status of the shipment.
{
"remark": "Not Applicable",
"operational_status": "great",
"journey": "forward",
"dp_location": "Mumbai",
"meta": {},
"promised_delivery_date": "2024-12-10T10:15:30+00:00",
"dp_name": "Test bluedart",
"estimated_delivery_date": "2024-12-10T10:15:30+00:00",
"shipment_id": "17334083479041568015",
"dp_status_updated_at": "2024-12-06T10:15:30+00:00",
"dp_status": "out_for_delivery",
"awb": "6806010004126"
}