Create Multipiece Booking

Multipiece Write

Combine multiple individual bookings into a single multipiece shipment. This allows consolidated shipping, unified tracking, and combined invoicing for related packages.

Returns

Multipiece object with totals

Auth

Bearer token required

Use cases

Bulk shipping · Related orders · Multi-box items

---

Endpoint overview

POST Authenticated

URL: {{base_url}}/partner/booking/create-multipiecebooking

• Requires a valid bearer token in the Authorization header.
• Combines two or more existing bookings into a multipiece shipment.
• Automatically calculates combined totals and FX conversions.

---

Required headers

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

---

Request body

Field	Type	Required	Description
rootId	string	Yes	Primary booking ID (becomes the root of multipiece)
secondaryId	string	Yes	Secondary booking ID to combine

---

Sample request

{
  "rootId": "690d0a040cce5203adb0a9bb",
  "secondaryId": "690d09cb0cce5203adb0a9af"
}

---

Response

{
  "success": true,
  "data": {
    "multiPiece": {
      "bookings": ["690d0a040cce5203adb0a9bb", "690d09cb0cce5203adb0a9af"],
      "total": 64566,
      "branchName": "Yaba",
      "_id": "6914589406b15ab9ac9e84b9",
      "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-12T09:51:17.190Z",
      "__v": 0
    }
  },
  "status": 201,
  "message": "MultiPiece booking created successfully",
  "timestamp": "2025-11-12T09:51:17.678Z"
}

---

Key response fields

Field	Type	Description
success	boolean	Indicates whether the creation was successful
data.multiPiece	object	The created multipiece booking object
data.multiPiece._id	string	Unique identifier for the multipiece booking
data.multiPiece.bookings	array	List of booking IDs included in this multipiece
data.multiPiece.total	number	Combined total cost of all bookings (in NGN)
data.multiPiece.branchName	string	Branch where the multipiece was created
data.multiPiece.piecesBreakdown	array	Breakdown of individual pieces (if applicable)
data.multiPiece.fx	array	Foreign exchange conversions
data.multiPiece.fx[].currency	string	Currency code (USD, NGN, EUR)
data.multiPiece.fx[].rate	number	Exchange rate used
data.multiPiece.fx[].amount	number	Total amount in that currency
data.multiPiece.createdAt	string	ISO timestamp of creation
data.multiPiece.updatedAt	string	ISO timestamp of last update
status	number	HTTP status code (201 for created)
message	string	Confirmation message
timestamp	string	Response timestamp

---

Error responses

Booking Not Found

{
  "success": false,
  "status": 404,
  "message": "One or more bookings not found",
  "timestamp": "2025-11-12T09:51:17.678Z"
}

Booking Already in Multipiece

{
  "success": false,
  "status": 400,
  "message": "Booking is already part of a multipiece shipment",
  "timestamp": "2025-11-12T09:51:17.678Z"
}

---

Tip: After creating a multipiece booking, use Update Multipiece Booking to add more bookings or Get Multipiece Booking to retrieve details.