Example Request Payload of Update Shipment Status API
The payload examples below are used in updateShipmentStatus API.
1. Full Confirmation
Request
{
"statuses": [
{
"shipments":[
{
"identifier": "12345383008471878029",
"products": []
}
],
"status": "bag_confirmed", // Enter next applicable status
}
],
}
2. Bag Invoiced Transition
When the seller has confirmed the order and created the invoice, the status will automatically change to DP Assigned (except MTO orders, where the status will change to ready_for_dp_assignment state).
Request
{
"statuses": [
{
"shipments":[
{
"identifier": "16563383008471878029",
"products": [],
"data_updates": {
"products": [
{
"filters": [{}],
"data": {
"store_invoice_id": "123"
}
},
],
"entities": [
{
"filters": [{}],
"data": {
"store_invoice_id": "123"
}
}
]
}
}
],
"status": "bag_invoiced",
"exclude_bags_next_state": null
},
],
}
Response
{
status: 200,
final_state: {
bag_invoiced: 'dp_assigned',
shipment_id: '12345634657861443427'
},
identifier: '12345634657861443427'
}
3. Full Cancellation with Same Reason Applied to All Products
Request
{
"statuses": [
{
"shipments":[
{
"identifier": "12345643769771400691",
"products": [],
"reasons": {
"products": [
{
"filters": [{}],
"data": {
"reason_id": 1, // What is reason ID
"reason_text": "Product Not Available"
}
},
],
"entities": []
}
},
],
"status": "bag_not_confirmed",
"exclude_bags_next_state": ""
}
],
}
Response
{
status: 200,
final_state: {
bag_not_confirmed: 'bag_not_confirmed',
shipment_id: '12345648882371728210'
},
identifier: '12345643769771400691'
}
4. Partial Confirmation at Products and Quantity Level
In the below given example request, items that are confirmed move to the next allowed state mentioned in status (here, bag_confirmed). Items that are not confirmed move to the allowed state mentioned in exclude_bags_next_state (here, bag_not_confirmed). For example, if a shipment has 10 items and you confirm five, those five will move to bag_confirmed and the remaining will move to bag_not_confirmed.
Request
{
"statuses": [
{
"shipments":[
{
"identifier": "12345383008471878029",
"products": [
{
"line_number": 1,
"quantity": 5 // partial quantity for line number 1
},
{
"line_number": 2,
"quantity": 10 // partial quantity for line number 2
}
],
"reasons": {
"products": [
{
"filters": [
{"line_number": 1, "quantity": 3}, // partial quantity to give multiple reasons for line number 1
{"line_number": 2, "quantity": 4} // partial quantity to give multiple reasons for line number 2
],
"data": {
"reason_id": 1,
"reason_text": "Product Not Available"
}
},
{
"filters": [
{"line_number": 1, "quantity": 2}, // partial quantity to give multiple reasons for line number 1
{"line_number": 2, "quantity": 1} // partial quantity to give multiple reasons for line number 2
],
"data": {
"reason_id": 2,
"reason_text": "Defective Product"
}
}
],
"entities": []
}
}
]
"status": "bag_confirmed",
"exclude_bags_next_state": "bag_not_confirmed"
}
],
}
5. Partial Cancellation (Without Affecting Status of Other Items)
The cancelled items move to the next allowed state, as defined in the status (here, bag_not_confirmed). Items that are not confirmed do not change state because exclude_bags_next_state is set to null; they remain in their current state. For example, if an order has 10 items and five are updated to bag_not_confirmed, the remaining five remain in the same state (e.g., placed).
Request
{
"statuses": [
{
"shipments":[
{
"identifier": "12345383008471878029",
"products": [
{
"line_number": 1,
"quantity": 5
},
{
"line_number": 2,
"quantity": 10
}
],
"reasons": {
"products": [
{
"filters": [
{"line_number": 3, "quantity": 3},
{"line_number": 4, "quantity": 5}
],
"data": {
"reason_id": 1,
"reason_text": "Product Not Available"
}
},
{
"filters": [
{"line_number": 3, "quantity": 2},
{"line_number": 4, "quantity": 5}
],
"data": {
"reason_id": 2,
"reason_text": "Defective Product"
}
}
],
"entities": []
}
}
],
"status": "bag_not_confirmed",
"exclude_bags_next_state": null
}
],
}
Response
{
status: 200,
final_state: {
bag_not_confirmed: 'bag_not_confirmed',
shipment_id: '17564716568041127262'
},
identifier: '17564712845211426575'
}
6. Delivery Partner Assignment
In the below given example request, DP is assigned to the shipment ("status" : "dp_assigned"). DP extension can use this payload to update DP details via data_updates.
Request
{
"statuses" : [
{
"shipments" : [
{
"identifier" : "17564650712821463339",
"products" : [
],
"data_updates" : {
"entities" : [
{
"filters" : [
],
"data" : {
"meta" : {
"ewaybill_info" : {
"ewayBillNo" : 391009665287.0,
"ewayBillDate" : "05/09/2024 08:23:00 PM",
"validUpto" : null,
"success" : true,
"delivery_type" : "forward",
"forward" : {
"ewayBillNo" : 391009665287.0,
"ewayBillDate" : "05/09/2024 08:23:00 PM",
"validUpto" : null,
"success" : true,
"delivery_type" : "forward"
}
},
"courier_partner_extension_id" : "65d6f66b0e1050fe6299d0b8",
"courier_partner_scheme_id" : "65d72c5bd606d646adc9f00d",
"logistics_meta" : {
"remark" : "NAN"
},
"is_own_account" : false,
"shipping_label_provided" : false,
"courier_partner_name" : "Bvc Bvc Bvc 0-5"
},
"delivery_awb_number" : "RSC000000513"
}
}
],
"products" : [
{
"filters" : [
],
"data" : {
"meta" : {
"ewaybill_info" : {
"ewayBillNo" : 391009665287.0,
"ewayBillDate" : "05/09/2024 08:23:00 PM",
"validUpto" : null,
"success" : true,
"delivery_type" : "forward",
"forward" : {
"ewayBillNo" : 391009665287.0,
"ewayBillDate" : "05/09/2024 08:23:00 PM",
"validUpto" : null,
"success" : true,
"delivery_type" : "forward"
}
},
"courier_partner_extension_id" : "65d6f66b0e1050fe6299d0b8",
"courier_partner_scheme_id" : "65d72c5bd606d646adc9f00d",
"is_own_account" : false,
"courier_partner_name" : "Bvc Bvc Bvc 0-5",
"logistics_meta" : {
"remark" : "NAN"
}
},
"delivery_awb_number" : "RS000000513"
}
}
],
"order_item_status" : [
{
"filters" : [
],
"data" : {
"meta" : {
"courier_partner_details" : {
"courier_partner_extension_id" : "65d6f66b0e1050fe6299d0b8",
"courier_partner_scheme_id" : "65d72c5bd606d646adc9f00d",
"courier_partner_name" : "Bvc Bvc Bvc 0-5",
"is_own_account" : false
}
}
}
}
]
}
}
],
"status" : "bag_packed",
"exclude_bags_next_state" : ""
}
]
}
Response
{
status: 200,
final_state: {
bag_packed: 'bag_packed',
shipment_id: '12345650712821463339' },
identifier: '12345650712821463339'
}
Common Error Scenarios (HTTP 200)
-
Entity id doesn't have any bag or child entity against it -
Invalid Reasons:
ReasonError: Reason is not allowed for <entity_type> <ids>ReasonError: Reason is missing for <entity_type> <ids>ReasonError: ReasonError: Invalid reason ids for <entity_type> <ids>
-
Data Errors:
Unable to convert to <data type> datalength is greater than <limit>Not allowed keys {keys} for {entity_type}mandatory keys {keys} must be present for all {entity}
-
Shipment is locked:
Entity is under {lock_status} lock for transition operations
-
Invalid shipment breaking:
Breaking up of child entities is not allowed for current parent config
-
Duplicate bags in multiple transitions at a time:
Child bag ids are repeated in multiple transitions,
-
No valid bags found in shipment:
Not found bag_ids {} against shipment_id {}
-
Invalid state transition:
Invalid State Transition {0} detected for given entity
-
Invalid user facing state transition:
Invalid user facing state transition detected
-
Invalid shipment breaking:
Breaking up of bags/entities is not allowed for current entity status