Factorizer/Cluster ERP WikiCluster ERP Türkçe
Home / Business modules

Reference

Shipments

Reference for the shipments sub-module of sales_orders, with shipment, line, unit, package, and event fields, statuses, dispatch checks, POD, and order roll-up.

This page describes the shipments sub-module of src/cluster_erp/modules/sales_orders/. A shipment (SalesOrderShipment) dispatches quantities of order lines and individual units of one sales order. It carries packages, transport data, a timeline of events, and the proof of delivery (POD). Each dispatch and delivery rolls the order status up. Generated documents are described on trade documents.

Scope and source

  • Defined in: shipments/models.py, shipments/services.py (ShipmentService, dispatch_checks), shipments/routes.py, and shipments/metadata.py.
  • Count: 5 tables, 32 routes (@router. decorators), 8 ActionMeta entries.

Shipment fields

Group Fields Source
Identity code (yearly sequence shipment), sales_order_id, status src/cluster_erp/modules/sales_orders/shipments/models.py:37-55, src/cluster_erp/modules/sales_orders/shipments/services.py:624
Dates ready_at, shipped_at, eta_at, delivered_at src/cluster_erp/modules/sales_orders/shipments/models.py:56-62
Transport tracking_no, carrier, transport_mode, vehicle_plate, trailer_plate, forwarder_party_id, transport_document_type, transport_document_no, mrn, seal_no, incoterm src/cluster_erp/modules/sales_orders/shipments/models.py:66-83
Delivery contractual_ship_to, actual_delivery_address, receiver_name, pod_signed, pod_received_at src/cluster_erp/modules/sales_orders/shipments/models.py:84-92
Notes on_hold_reason, cancel_reason, notes, extra src/cluster_erp/modules/sales_orders/shipments/models.py:33, src/cluster_erp/modules/sales_orders/shipments/models.py:94-96

Child records

Entity Table Key fields Source
ShipmentPackage so_packages package_no, package_type, net_weight, gross_weight, weight_unit_id, length, width, height, dimension_unit_id, volume_m3 src/cluster_erp/modules/sales_orders/shipments/models.py:99-134
ShipmentLine so_shipment_lines sales_order_line_id, qty_shipped, package_id src/cluster_erp/modules/sales_orders/shipments/models.py:137-164
ShipmentUnit so_shipment_units unit_id, package_id src/cluster_erp/modules/sales_orders/shipments/models.py:167-201
ShipmentEvent so_shipment_events event_type, occurred_at, eta_at, location, note, actor_id src/cluster_erp/modules/sales_orders/shipments/models.py:204-222

Statuses and actions

The service allows these transitions (src/cluster_erp/modules/sales_orders/shipments/services.py:65-74).

stateDiagram-v2
 [*] --> planned
 planned --> ready_to_ship: ready
 packed --> ready_to_ship: ready
 planned --> shipped: ship
 packed --> shipped: ship
 ready_to_ship --> shipped: ship
 shipped --> in_transit: in_transit
 shipped --> delivered: deliver
 in_transit --> delivered: deliver
 planned --> on_hold: hold
 ready_to_ship --> on_hold: hold
 on_hold --> planned: resume
 planned --> cancelled: cancel
 on_hold --> cancelled: cancel

In prose: a shipment is planned, optionally readied, and then dispatched. A dispatched shipment goes in transit and is delivered. Before dispatch it can be put on hold, resumed to planned, or cancelled. The header and content change only in planned, packed, ready_to_ship, or on_hold (src/cluster_erp/modules/sales_orders/shipments/services.py:75-78). The status packed is kept only as a legacy value for older rows; no code sets it (src/cluster_erp/modules/sales_orders/shipments/schemas.py:25).

Action Label Condition Endpoint Permission Source
ready Ready to Ship status is planned or packed POST /sales-orders/shipments/{id}/ready shipment.update src/cluster_erp/modules/sales_orders/shipments/metadata.py:206-213, src/cluster_erp/modules/sales_orders/shipments/routes.py:208
ship Dispatch status is planned, packed, or ready_to_ship POST /sales-orders/shipments/{id}/ship shipment.dispatch src/cluster_erp/modules/sales_orders/shipments/metadata.py:214-221, src/cluster_erp/modules/sales_orders/shipments/routes.py:219
in_transit In Transit / ETA status is shipped POST /sales-orders/shipments/{id}/in-transit shipment.update src/cluster_erp/modules/sales_orders/shipments/metadata.py:222-248, src/cluster_erp/modules/sales_orders/shipments/routes.py:230
deliver Record Delivery (POD) status is shipped or in_transit POST /sales-orders/shipments/{id}/deliver shipment.deliver src/cluster_erp/modules/sales_orders/shipments/metadata.py:249-280, src/cluster_erp/modules/sales_orders/shipments/routes.py:242
hold Put on Hold status is planned, packed, or ready_to_ship POST /sales-orders/shipments/{id}/hold shipment.update src/cluster_erp/modules/sales_orders/shipments/metadata.py:281-298, src/cluster_erp/modules/sales_orders/shipments/routes.py:254
resume Resume status is on_hold POST /sales-orders/shipments/{id}/resume shipment.update src/cluster_erp/modules/sales_orders/shipments/metadata.py:299-306, src/cluster_erp/modules/sales_orders/shipments/routes.py:266
cancel Cancel Shipment status is planned, packed, ready_to_ship, or on_hold POST /sales-orders/shipments/{id}/cancel shipment.cancel src/cluster_erp/modules/sales_orders/shipments/metadata.py:307-326, src/cluster_erp/modules/sales_orders/shipments/routes.py:277
generate_documents Generate Documents status is planned, packed, ready_to_ship, shipped, in_transit, or delivered POST /sales-orders/shipments/{id}/generate-documents trade_document.create src/cluster_erp/modules/sales_orders/shipments/metadata.py:327-338, src/cluster_erp/modules/sales_orders/trade_documents/routes.py:102

Shipment routes

Method and path Permission Source
GET /sales-orders/shipments/, GET /sales-orders/{order_id}/shipments, GET /sales-orders/shipments/{shipment_id} shipment.read src/cluster_erp/modules/sales_orders/shipments/routes.py:85-151
POST /sales-orders/{order_id}/shipments; PATCH /sales-orders/shipments/{shipment_id} shipment.create, shipment.update src/cluster_erp/modules/sales_orders/shipments/routes.py:135, src/cluster_erp/modules/sales_orders/shipments/routes.py:164
GET .../order-lines, GET .../available-units shipment.read src/cluster_erp/modules/sales_orders/shipments/routes.py:179-192
Lines: GET /sales-orders/shipment-lines/, GET, PUT, DELETE /sales-orders/shipment-lines/{line_id}, POST /sales-orders/shipments/{shipment_id}/lines shipment_line.read, .create, .update, .delete src/cluster_erp/modules/sales_orders/shipments/routes.py:292-344
Units: GET /sales-orders/shipment-units/, GET, PUT, DELETE /sales-orders/shipment-units/{row_id}, POST /sales-orders/shipments/{shipment_id}/units shipment_unit.read, .create, .update, .delete src/cluster_erp/modules/sales_orders/shipments/routes.py:357-409
Packages: GET /sales-orders/packages/, GET, PUT, DELETE /sales-orders/packages/{package_id}, POST /sales-orders/shipments/{shipment_id}/packages shipment_package.read, .create, .update, .delete src/cluster_erp/modules/sales_orders/shipments/routes.py:422-471
Events: GET /sales-orders/shipment-events/, GET /sales-orders/shipment-events/{event_id}, POST /sales-orders/shipments/{shipment_id}/events shipment_event.read, shipment_event.create src/cluster_erp/modules/sales_orders/shipments/routes.py:484-508

Constraints and validation

  • dispatch_checks returns errors and warnings by level: none, transport (a plate, or a carrier with a tracking number), or export (transport plus packages that are measured and weighed, net not above gross, and every item packed). A missing HS code or country of origin on a product is a warning (src/cluster_erp/modules/sales_orders/shipments/services.py:102-192).
  • Dispatch uses the tenant's dispatch_check_level and refuses on any error; the units become shipped (src/cluster_erp/modules/sales_orders/shipments/services.py:558-580, src/cluster_erp/modules/sales_orders/shipments/services.py:1106-1126).
  • A shipped quantity may not exceed the ordered quantity minus what other shipments already took (src/cluster_erp/modules/sales_orders/shipments/services.py:679-750).
  • A unit can join a shipment only while it is open or ready (src/cluster_erp/modules/sales_orders/shipments/services.py:799-839).
  • A package's volume in cubic metres is length times width times height, converted with the dimension unit's factor to the metre; any missing piece gives no volume (src/cluster_erp/modules/sales_orders/shipments/services.py:79-100).
  • Delivery without POD data is refused when the setting pod_rule is block, and logged as the event delivered_without_pod when it is warn (src/cluster_erp/modules/sales_orders/shipments/services.py:1148-1191).
  • Cancel returns the units to open (src/cluster_erp/modules/sales_orders/shipments/services.py:1218-1238).
  • A change to a shipment marks its generated documents stale (src/cluster_erp/modules/sales_orders/shipments/services.py:1239-1252).
  • The order roll-up marks a line shipped or delivered once its cumulative shipped quantity reaches the ordered quantity, and the order partially_shipped, shipped, or delivered accordingly; it emits SalesOrderPartiallyShipped, SalesOrderShipped, or SalesOrderDelivered (src/cluster_erp/modules/sales_orders/shipments/services.py:1253-1392).
  • Manual events are eta_update, location_update, or note (src/cluster_erp/modules/sales_orders/shipments/schemas.py:257).
  • Dispatch does not post a goods movement: a grep for PostGoodsIssue in src/cluster_erp/modules/sales_orders/ finds no call.

Terms introduced

Term Code identifier Definition Turkish term Source
dispatch check dispatch_checks The list of errors and warnings a shipment must clear before dispatch, by level. Sevk kontrolü src/cluster_erp/modules/sales_orders/shipments/services.py:102
proof of delivery pod_signed, pod_received_at The receiver's confirmation recorded on delivery. Teslim kanıtı (POD) src/cluster_erp/modules/sales_orders/shipments/models.py:89-92
package ShipmentPackage A physical package of a shipment with weights and dimensions. Paket src/cluster_erp/modules/sales_orders/shipments/models.py:99

Verified against commit 92f8051 on 2026-11-13.

Verified against commit 92f8051 · 2026-11-13