Orders & Fulfillment

Order

An Order represents a sales transaction. Orders can be created manually in Nexus, imported from Shopify, or generated from email/PDF import flows.

Key fields

Field	Type	Description
id	UUID	Primary key
organization_id	UUID	Owning tenant
customer_id	UUID	Linked contact
order_number	text	Human-readable order identifier
status	text	Order lifecycle state
total_amount	numeric	Order total
currency	text	Currency code (e.g., EGP, SAR, AED)
source	text	Where the order originated (manual, shopify, import)
shipping_address	jsonb	Delivery address
notes	text	Internal notes
shopify_order_id	text	Shopify order ID (if synced)
created_at	timestamptz	When the order was placed

Order lifecycle

pending → confirmed → processing → pick_started → picked → packed → shipped → delivered
                                                                          ↘ returned

Each transition may trigger automation (e.g., sending a WhatsApp shipping notification).

Order Item

An Order Item is a line item within an order, referencing a product/SKU, quantity, and price.

Key fields

Field	Type	Description
id	UUID	Primary key
order_id	UUID	Parent order
product_name	text	Product description
sku	text	Stock-keeping unit
quantity	integer	Ordered quantity
unit_price	numeric	Price per unit
total_price	numeric	Line total

Pick List

A Pick List is generated from one or more orders to guide warehouse staff through the picking process. Pick lists group items by warehouse location for efficient picking routes.

Lifecycle

1. start-picking Edge Function creates the pick list and assigns a picker.
2. Warehouse staff uses the mobile UI to scan items (scan-item).
3. complete-pick marks the pick list as complete.
4. Items move to the packing stage.

Shipment (AWB)

An AWB (Airway Bill) represents a shipment created with a courier. The awbs table tracks tracking numbers, courier info, status, and label URLs.

Key fields

Field	Type	Description
id	UUID	Primary key
order_id	UUID	Linked order
tracking_number	text	Courier tracking number
courier	text	Courier name (e.g., bosta)
status	text	Shipment status
label_url	text	URL to printable shipping label
created_at	timestamptz	When the AWB was created

Status tracking

Courier status updates flow in via tracking-webhook and update the awb_status_logs table with a timestamped history.

Returns

Returns are handled by updating order and shipment status. The return-confirmation-webhook Edge Function processes return confirmations from couriers.

Related tables

Table	Purpose
orders	Order records
order_items	Line items
awbs	Shipment / AWB records
awb_status_logs	Shipment status history
pick_lists	Pick list records
pick_list_items	Items within a pick list