Create a Shipment

Dispatch a new shipment. The system resolves origin and destination addresses from Google Place IDs, calculates the full cost breakdown, verifies your wallet balance, and creates the shipment. all in a single request. The calculated fee is deducted atomically from your prepaid wallet.

---

Endpoint

POST/v1/shipments

Required permission: shipments:create

---

Request Body

Field	Type	Required	Description
senderPlaceId	String	✅	Google Maps Place ID for the pickup address. Use the Location Search endpoint to get this.
senderName	String	✅	Full name of the person handing over the package.
senderPhone	String	✅	Sender's contact phone number.
senderEmail	String	❌	Sender's email address.
receiverPlaceId	String	✅	Google Maps Place ID for the delivery address.
receiverName	String	✅	Full name of the recipient.
receiverPhone	String	✅	Recipient's contact phone number.
receiverEmail	String	❌	Recipient's email address.
packageTitle	String	✅	Short label for the package contents (e.g. "Laptop & Charger").
packageDescription	String	❌	Longer description of what is inside the package.
packageCategory	String	✅	Size/weight tier. One of SMALL, MEDIUM, LARGE, or EXTRA_LARGE. See table below.
itemValue	Integer	❌	Declared monetary value of the contents in ₦. Required if enableInsurance is true.
enableInsurance	Boolean	❌	Set to true to add insurance coverage based on itemValue.
userNote	String	❌	A note from the sender attached to the shipment.

Package Categories

Value	Description	Operational Weight
SMALL	Fits in a shoebox. documents, keys, phones	up to 3 kg
MEDIUM	Fits in a backpack. clothes, laptops	up to 10 kg
LARGE	Requires two hands. microwaves, multiple boxes	up to 25 kg
EXTRA_LARGE	Requires a van or truck. furniture, wholesale goods	25 kg+

---

Response

On success, returns 200 OK with the full shipment record.

Field	Type	Description
id	String	Internal shipment ID (e.g. SHP_A1B2C3D4).
trackingCode	String	Customer-facing tracking code (e.g. TCL-SB-3891829).
senderName	String	Sender's name.
senderPhone	String	Sender's phone.
senderEmail	String?	Sender's email, if provided.
senderPlaceId	String	Origin Place ID.
receiverName	String	Recipient's name.
receiverPhone	String	Recipient's phone.
receiverEmail	String?	Recipient's email, if provided.
receiverPlaceId	String	Destination Place ID.
originAddress	String	Resolved origin street address.
originCity	String	Origin city.
originState	String	Origin state.
destinationAddress	String	Resolved destination street address.
destCity	String	Destination city.
destState	String	Destination state.
packageTitle	String	Package label.
packageDescription	String?	Package description, if provided.
packageCategory	String	Size tier. SMALL, MEDIUM, LARGE, or EXTRA_LARGE.
itemValue	Integer?	Declared item value in ₦, if provided.
enableInsurance	Boolean?	Whether insurance is enabled.
distanceKm	Float	Calculated route distance in kilometers.
baseFare	Integer	Flat base charge in ₦.
distanceFee	Integer	Distance-based charge in ₦.
weightSurcharge	Integer	Weight-tier surcharge in ₦.
valueSurcharge	Integer	Insurance/value-based surcharge in ₦.
totalCost	Integer	Total amount debited from your wallet in ₦.
status	String	Initial status. always PENDING on creation.
events	Array	Shipment lifecycle events. Each entry has title, description, and createdAt.
userNote	String?	Sender's note, if provided.
createdAt	String	ISO 8601 UTC timestamp.

---

Wallet Pre-check

note

If your wallet balance is lower than the calculated totalCost, the request fails immediately before any shipment record is created. Top up your wallet first and retry.

---

{
"senderPlaceId": "ChIJi4eLcz4OdkgRlgpAD5e4OCg",
"senderName": "Grace Adegoke",
"senderPhone": "+2348031234567",
"senderEmail": "grace@marketify.ng",
"receiverPlaceId": "ChIJv1SCIS2TOxARgv6-Zj4i_yw",
"receiverName": "John Doe",
"receiverPhone": "+2348123456789",
"packageTitle": "Laptop & Charger",
"packageDescription": "Space Grey MacBook Pro 16-inch in original box",
"packageCategory": "MEDIUM",
"itemValue": 450000,
"enableInsurance": true
}