Sales Shipments

What this guide covers

Picking, dispatching, and (optionally) couriering customer-bound shipments against a Sales Order. Covers the full flow: create from SO → place hold on stock → collect into staging → dispatch → optionally request an Aramex courier and download the waybill.

For internal moves see Local Shipments; for parts going to external service providers see External Service Shipments.

Where to find it

Open Operations → Shipments → Sales Shipments. The page lists shipments filterable by status, customer, sales order ref, shipment number.

Who can do what

• Warehouse staff (SALES_SHIPMENT_USER or STOCK_SHIPMENTS_USER) — view; create from a Sales Order; place stock holds; collect into staging; dispatch; upload signatures and delivery photos.
• Courier user — same permissions; the Request Courier (Aramex) button is gated by access to the dialog, not a separate role.
• Site admin (ADMIN) — full access.

A user without either permission can still see the list (read-only) when granted page access via JSF, but the action buttons (Create, Hold, Collect, Dispatch, Request Courier) are hidden.

Creating from a Sales Order

1. From a Sales Order's detail page, click Create Shipment.
2. The system creates the shipment and places holds on the relevant stock so other shipments can't grab the same units.
3. The shipment starts in a draft state, visible in the Sales Shipments list.

Multiple shipments can hold the same product across different Sales Orders — the system tracks allocations so each shipment dispatches its own slice.

Picking and dispatching

1. From the list, open the shipment with Process.
2. The picking dialog opens. For each line:
   • The dropdown shows bins with stock for this product, scoped to the right Sales Order's allocations.
   • Pick a bin and enter the qty (the system suggests the lower of bin qty vs remaining need).
   • Click Collect to move stock to the SHIP_COLLECT staging marker.
3. Repeat until every line is fully collected.
4. Click Dispatch to consume staged stock and update the shipment to Dispatched.

Requesting an Aramex courier

1. After dispatch (or any time the customer details are confirmed), click Request Courier.
2. The Aramex dialog pre-fills receiver details from the customer record.
3. Specify:
   • Service type — domestic (SMP / EMD / ONP / PEC / PEX road express, default) or international (PPX / PDX).
   • Parcels — height, length, width per parcel all required, all > 0.
   • Pickup date, insurance (optional), payment type (default P = account-holder).
4. Click Submit. The system calls the Aramex API; on success a waybill number (format LAR…) and a collection reference (format D…) come back, both stored in the shipment record.
5. Download Waybill opens the Aramex-hosted PDF for printing the label.
6. Track Waybill (later) calls the Aramex tracking API to fetch live status.

See Aramex for the full courier-integration reference.

Common errors and fixes

• "All items already in dispatched, placed or parked shipments." — the Sales Order's stock is already fully allocated to other shipments. Wait for one of them to dispatch and free up the hold, or split the SO.
• "Picking Up more than required" — collect qty > planned for the line. Reduce.
• "Cannot collect more than shipment qty!" — same idea, hard guard. Reduce.
• "Positive qty required" — qty <= 0 entered. Enter a positive number.
• "sales order warehouse is incorrect: [warehouse]" — the SO is bound to a different warehouse than where you're trying to pick. Either switch warehouses, or split the SO.
• "Cannot submit shipment: Dimensions of a parcel is not complete" (Aramex) — height / length / width missing or zero. Fill all three on every parcel.
• Aramex API error (variable text) — the dialog surfaces the status_description from Aramex when status_code != 0. Common cases: invalid postal code, account suspended, malformed phone number. Fix the offending field and resubmit.

Tips and gotchas

• Aramex credentials are hardcoded in the integration — the same account number drives every couriered shipment. If the account suspends, every Aramex booking fails until cleared.
• Waybill format is LAR… — collection reference is D…. Both stored pipe-delimited in customerRef / trackingNumber. Don't try to edit those fields manually.
• PDF download URL is public — anyone with the waybill number can fetch the label. Treat the waybill number as sensitive.
• Country code is hardcoded ZA in the waybill request. International shipments still go through but Aramex assumes a domestic address; if you ship outside SA regularly, get the integration extended.
• Stock holds persist until dispatch. A Parked or Placed shipment holds its stock indefinitely; if you cancel, the holds release immediately.
• Hold allocations are first-come-first-served. If two shipments are created against an SO simultaneously, the one that saves first gets the stock; the second sees "All items already in dispatched, placed or parked shipments."