Create multiple shipments asynchronously (NDJSON)

POST

/api/v1/create-shipment/bulk

Queues a background job that creates shipments from a Newline-Delimited JSON (NDJSON) file. Each line in the file is a single shipment object — blank lines are ignored.

The endpoint returns immediately with a jobId. Poll GET /api/create-shipment/bulk/status/{jobId} to track progress. Maximum 500 shipments per request.

How to upload

Send a multipart/form-data request containing:

Form field	Required	Description
`shipments`	✅	The `.ndjson` file. The server identifies it by field name `shipments` or by `.ndjson` file extension.
`cmpService`	✅	Service type: `DELIVERY` or `REVERSE`. Applied to all rows in the batch.
`subAccountId`	❌	UUID of the sub-account. Optional when authenticating via API key.
`locationId`	❌	Pickup location ID. When provided every shipment starts as `AWAITING_PICKUP` and a pickup request is auto-created. When absent shipments start as `NEW`.

NDJSON Row Schema — one JSON object per line

Each line in the uploaded .ndjson file represents a single shipment. Blank lines and BOM-prefixed first lines are silently skipped. The file must be UTF-8 encoded.

✅ Required fields

Field	Type	Validation	Description
`consigneeName`	string	max 255	Full name of the recipient / consignee.
`consigneePhone`	string	E.164 — `+[1-9]\d{6,14}`	Primary phone of the recipient. Example: `+201001234567`
`governorateId`	integer	≥ 1	Destination governorate ID. Omit only if `districtId` is provided — the server auto-fills this from the district.
`cityId`	integer	≥ 1	Destination city ID — drives branch routing. Omit only if `districtId` is provided.
`addressText` or structured parts	string / parts	—	Free-text delivery address. Optional when `streetName` or `buildingNumber` is present — the server builds `addressText` from the parts automatically.

🔑 District auto-resolution

If only districtId is sent (without cityId/governorateId), the server resolves both values from the district record before validation, so no extra round-trip is needed from the client.

📐 Shipment dimensions

Field	Type	Default	Description
`weight`	number	0	Gross weight in kg. Chargeable = `max(weight, W×H×L / 5000)`.
`length`	number	0	Length in cm.
`width`	number	0	Width in cm.
`height`	number	0	Height in cm.
`noOfPcs`	integer	1	Total pieces (≥ 1).

👤 Consignee contact details

Field	Type	Description
`attentionTo`	string (max 255)	Attention-to / care-of name.
`consigneePhoneAlt`	string (E.164)	Alternate phone.
`consigneePhoneAlt2`	string (E.164)	Second alternate phone.
`consigneeEmail`	string (max 255)	Consignee email address.
`nationalId`	string (max 50)	National ID for identity-verified delivery.
`districtId`	integer	Destination district ID. When sent without `cityId`/`governorateId` both are resolved automatically.
`consigneeNotes`	string	Delivery notes shown to the courier.
`latitude`	number (max 6dp)	GPS latitude.
`longitude`	number (max 6dp)	GPS longitude.

🏠 Structured address components

Address resolution pyramid:

If streetName or buildingNumber is present → the server builds addressText from the structured parts (auto-detects Arabic vs English) and ignores any addressText you sent.
Otherwise → the provided addressText is used as-is.

newAddressText is independent — stored as a secondary address on the consignee and does not affect the pyramid.

Field	Type	Description
`streetName`	string (max 255)	Street name — triggers pyramid when present.
`buildingNumber`	string (max 255)	Building/house number — triggers pyramid when present.
`floor`	string (max 255)	Floor number.
`apartment`	string (max 255)	Apartment / unit number.
`landmarkNearby`	string (max 255)	Nearby landmark for courier guidance.
`newAddressText`	string	Optional secondary address. Stored independently on the consignee.

📋 Shipment metadata

Field	Type	Description
`ref`	string (max 255)	Your internal order or reference number.
`packageType`	`PARCEL` \| `DOCUMENTS` \| `BULKY`	Packaging type — drives handling rules.
`contents`	string (max 500)	Description of the shipment contents.
`itemValue`	number (≥ 0)	Declared value in EGP — used for insurance.
`cash`	number (≥ 0)	Cash-on-delivery (COD) amount in EGP. Zero = no COD.
`specialInstructions`	string (max 500)	Special handling instructions.
`productId`	integer (≥ 1)	Product type ID. Overridden by the form-level `productId` if that is supplied.
`shipmentServiceIds`	integer[]	Add-on service IDs. Fetch from `GET /create-shipment/all-services`.

🔑 AWB and backdating

Field	Type	Description
`awb`	string	Manual AWB override. Auto-generated when omitted. Duplicate AWBs are skipped and reported in the `skipped` array.

↩️ Return location

Field	Type	Description
`returnLocationId`	integer (≥ 1)	Location to which the shipment is returned on delivery failure. Defaults to the sub-account warehouse. The server derives `returnBranchId` from this location automatically.

📦 Sub-packages breakdown

Use packages when a single shipment contains multiple pieces with different dimensions:

"packages": [
  { "quantity": 2, "weight": 3.5, "length": 30, "width": 20, "height": 15 },
  { "quantity": 1, "weight": 0.8, "length": 20, "width": 10, "height": 10 }
]

🌍 International shipment data

"createInternationalData": {
  "purposeOfShipment": "COMMERCIAL_SAMPLE",
  "hsCode": "6109.10",
  "madeInId": 1
}

🚫 Server-derived fields — do NOT include in the NDJSON

Field	Derived from
`businessLocationId`	Sub-account warehouse (or `locationId` form field).
`returnBranchId`	Branch of the resolved `returnLocationId`.
`deliveryBranchId`	Branch of `cityId` (DELIVERY) or warehouse branch (REVERSE).
`currentBranchId`	Always `null` at creation.
`fromBranchId`	Always `null` at creation.

⚠️ REVERSE shipment notes

When cmpService = REVERSE (the form field — not per-row):

The customer's flat address data (streetName, buildingNumber, addressText, etc.) becomes an ad-hoc pickup origin (fromLocationId).
Consignee = the merchant — the sub-account name + warehouse address is stored as the consignee.
returnLocationId — should be the merchant warehouse (or omit to default to it).

📄 Minimal valid NDJSON examples

DELIVERY — districtId only (server resolves city + governorate):

{"consigneeName":"Ahmed Hassan","consigneePhone":"+201001234567","districtId":1,"addressText":"15 شارع النصر، شقة 4، مدينة نصر","weight":2.5,"length":30,"width":20,"height":15,"cash":250,"ref":"ORD-001","packageType":"PARCEL","contents":"ملابس","productId":1}

DELIVERY — cityId + structured address:

{"consigneeName":"Mariam Tarek","consigneePhone":"+201223334445","governorateId":2,"cityId":25,"streetName":"شارع الجلاء","buildingNumber":"18","floor":"3","apartment":"12","landmarkNearby":"أمام مسجد النور","weight":0.5,"cash":0,"ref":"ORD-002","packageType":"DOCUMENTS","productId":1}

REVERSE — with explicit return location:

{"consigneeName":"Khaled Mohamed","consigneePhone":"+201501112233","governorateId":1,"cityId":10,"addressText":"45 شارع الهرم، الجيزة","weight":1.5,"length":25,"width":15,"height":10,"cash":0,"ref":"RTN-001","packageType":"PARCEL","returnLocationId":7,"productId":1}

Request

Responses

201 Created

Job enqueued. Poll trackingUrl for progress.

400 Bad Request

Validation error — malformed JSON, missing required fields, invalid enum, or > 500 rows. The message array contains per-row error details.

401 Unauthorized

Unauthorized.

404 Not Found

Sub-account or pickup location not found.

500 Internal Server Error

Internal Server Error.

Create multiple shipments asynchronously (NDJSON)

How to upload​

NDJSON Row Schema — one JSON object per line​

✅ Required fields​

🔑 District auto-resolution​

📐 Shipment dimensions​

👤 Consignee contact details​

🏠 Structured address components​

📋 Shipment metadata​

🔑 AWB and backdating​

↩️ Return location​

📦 Sub-packages breakdown​

🌍 International shipment data​

🚫 Server-derived fields — do NOT include in the NDJSON​

⚠️ REVERSE shipment notes​

📄 Minimal valid NDJSON examples​

Request​

Responses​