Create a single shipment

POST

/api/v1/create-shipment

---

Creates one shipment, its details, its consignee record, and — for reverse shipments — an ad-hoc pickup location, all inside a single database transaction.

Request shape

The body has three top-level keys: shipment (the flat shipment payload), cmpService (the operation), and subAccountId (the owning merchant). An optional locationId selects an explicit warehouse/pickup location.

Flat vs legacy nested payload

The preferred shape is flat: consignee fields (consigneeName, consigneePhone, cityId, governorateId, address parts) live directly on the shipment object. The legacy contact object is still accepted and is normalised to the flat layout by the server — new integrations should use the flat shape.

Flow type — DELIVERY vs REVERSE

• DELIVERY: goods go from the warehouse to the customer. businessLocationId is the merchant warehouse; deliveryBranchId is resolved from cityId.
• REVERSE: the customer's flat data is saved as an ad-hoc pickup origin. businessLocationId is the merchant warehouse; the stored consignee is the merchant (final recipient of the returned goods).

Address resolution pyramid

1. If streetName or buildingNumber is present → the server builds addressText from the structured parts (auto-detecting Arabic vs English).
2. Otherwise → the client-supplied addressText is used as-is.

newAddressText is a separate optional field stored as a secondary address on the consignee. It does not affect the pyramid above.

District auto-resolution

If districtId is provided without cityId / governorateId, the server resolves both values automatically from the district record before validation.

Server-derived fields — do not send

• businessLocationId — always set to the merchant warehouse.
• Branch ids (deliveryBranchId, toBranchId, currentBranchId, fromBranchId) — computed from the destination city and the warehouse.
• awb — auto-generated when omitted; if supplied it must be free/unused.

Required fields

Field	Rule
consigneeName	Always required.
consigneePhone	Always required — E.164 format, e.g. +201001234567.
cityId	Required unless districtId is provided.
governorateId	Required unless districtId is provided.
districtId	Optional — server auto-fills cityId/governorateId from the district when sent alone.
addressText	Required unless streetName or buildingNumber is provided.

Request

Responses

201 Created

Shipment created — returns the generated AWB.

400 Bad Request

Validation or business-rule error.

401 Unauthorized

Unauthorized.

404 Not Found

Sub-account, pickup location, or product not found.

500 Internal Server Error

Internal Server Error.