Update Multipiece Booking¶

Multipiece Write

Add or remove bookings from an existing multipiece shipment. Totals and FX conversions are automatically recalculated after each modification.

Actions

add or remove

Auth

Bearer token required

Use cases

Add packages · Remove items · Adjust shipments

Add booking to multipiece¶

PATCH Authenticated

URL: {{base_url}}/employee/booking/update-multipiecebooking/{{multipiece_id}}?action=add

Requires a valid bearer token in the Authorization header.
Adds the specified booking to the multipiece shipment.
Recalculates totals automatically.

Required headers¶

Header	Value
`Authorization`	`Bearer {{token}}`
`Content-Type`	`application/json`

Path and query parameters¶

Parameter	Type	Required	Description
`multipiece_id`	`string`	Yes	The unique identifier of the multipiece booking
`action`	`string`	Yes	Action to perform: `add` or `remove`

Request body¶

Field	Type	Required	Description
`bookingId`	`string`	Yes	The booking ID to add or remove

Sample request (Add)¶

{
  "bookingId": "690cf6030cce5203adb0a631"
}

Response (Add)¶

{
  "success": true,
  "data": {
    "multiPiece": {
      "_id": "6914589406b15ab9ac9e84b9",
      "bookings": [
        "690d0a040cce5203adb0a9bb",
        "690d09cb0cce5203adb0a9af",
        "690cf6030cce5203adb0a631"
      ],
      "total": 97709,
      "branchName": "Yaba",
      "piecesBreakdown": [],
      "fx": [
        {
          "currency": "USD",
          "rate": 1500,
          "amount": 65.13933333333334
        },
        {
          "currency": "NGN",
          "rate": 1,
          "amount": 97709
        },
        {
          "currency": "EUR",
          "rate": 1700,
          "amount": 57.47588235294118
        }
      ],
      "createdAt": "2025-11-12T09:51:17.190Z",
      "updatedAt": "2025-11-12T09:56:22.902Z",
      "__v": 3
    }
  },
  "status": 200,
  "message": "Booking successfully added to MultiPiece",
  "timestamp": "2025-11-12T09:56:23.364Z"
}

Remove booking from multipiece¶

PATCH Authenticated

URL: {{base_url}}/employee/booking/update-multipiecebooking/{{multipiece_id}}?action=remove

Removes the specified booking from the multipiece shipment.
Recalculates totals automatically.
Multipiece must have at least 2 bookings after removal.

Sample request (Remove)¶

{
  "bookingId": "690cf6030cce5203adb0a631"
}

Response (Remove)¶

{
  "success": true,
  "data": {
    "multiPiece": {
      "_id": "6914589406b15ab9ac9e84b9",
      "bookings": ["690d0a040cce5203adb0a9bb", "690d09cb0cce5203adb0a9af"],
      "total": 64566,
      "branchName": "Yaba",
      "piecesBreakdown": [],
      "fx": [
        {
          "currency": "USD",
          "rate": 1500,
          "amount": 43.044
        },
        {
          "currency": "NGN",
          "rate": 1,
          "amount": 64566
        },
        {
          "currency": "EUR",
          "rate": 1700,
          "amount": 37.98
        }
      ],
      "createdAt": "2025-11-12T09:51:17.190Z",
      "updatedAt": "2025-11-12T14:36:04.009Z",
      "__v": 4
    }
  },
  "status": 200,
  "message": "Booking successfully removed from MultiPiece",
  "timestamp": "2025-11-12T14:36:04.469Z"
}

Key response fields¶

Field	Type	Description
`success`	`boolean`	Indicates whether the update was successful
`data.multiPiece`	`object`	The updated multipiece booking object
`data.multiPiece._id`	`string`	Unique identifier for the multipiece booking
`data.multiPiece.bookings`	`array`	Updated list of booking IDs
`data.multiPiece.total`	`number`	Recalculated total cost (in NGN)
`data.multiPiece.branchName`	`string`	Branch name
`data.multiPiece.piecesBreakdown`	`array`	Breakdown of individual pieces
`data.multiPiece.fx`	`array`	Updated foreign exchange conversions
`data.multiPiece.createdAt`	`string`	ISO timestamp of creation
`data.multiPiece.updatedAt`	`string`	ISO timestamp of last update
`status`	`number`	HTTP status code (200 for success)
`message`	`string`	Confirmation message
`timestamp`	`string`	Response timestamp

Error responses¶

Multipiece Not Found¶

{
  "success": false,
  "status": 404,
  "message": "MultiPiece booking not found",
  "timestamp": "2025-11-12T09:56:23.364Z"
}

Booking Not in Multipiece¶

{
  "success": false,
  "status": 400,
  "message": "Booking is not part of this multipiece shipment",
  "timestamp": "2025-11-12T09:56:23.364Z"
}

Cannot Remove (Minimum Bookings)¶

{
  "success": false,
  "status": 400,
  "message": "Multipiece must contain at least 2 bookings",
  "timestamp": "2025-11-12T09:56:23.364Z"
}

Note: Removing a booking from a multipiece does not delete the booking itself—it remains as an individual booking in the system.