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.
pickupCode	String	❌	Optional 6 numeric or alphabetic code for package handover. If omitted, the system auto-generates one.
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.
receiverName	String	Recipient's name.
receiverPhone	String	Recipient's phone.
receiverEmail	String?	Recipient's email, if provided.
originAddress	String	Resolved origin street address.
destinationAddress	String	Resolved destination street address.
packageTitle	String	Package label.
packageDescription	String?	Package description, if provided.
packageCategory	String	Size tier. SMALL, MEDIUM, LARGE, or EXTRA_LARGE.
itemValue	Float?	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.
userNote	String?	Sender's note, if provided.
createdAt	String	ISO 8601 UTC timestamp.

---

caution

It is recommended to omit pickupCode to allow auto-generation. If supplying a custom pickupCode, ensure it is never visible to the sender prior to pickup. The sender will verify this code when the rider arrives to collect the package.

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
}