Submit Order¶

Create a shipment order and run packaging optimization. Packing instructions are sent by email (if enabled) or retrieved via the download endpoint.

Endpoint¶

POST

{base url}/api/v1/orders/submit-order/

Authentication Requirements¶

All requests require a valid API key. See API Authentication.

Prerequisites¶

Important

Onboarding must be complete. The following must exist before submitting:

Supplier and Consignee — Lane configured; API key has access
Item Master Data — All SKUs with dimensions and weight
Packaging — Boxes, pallets, containers defined for the lane
Lane Configuration — Transportation mode enabled; containers available

For OceanFCL and TruckFTL, the payload must include a non-empty order_containers list (see Payload Format). If the order only uses pre_builts and/or loose_boxes (no order_items), item master SKUs are not required for that cargo, but the lane and container configuration still apply.

Unknown product codes: By default the order is rejected. Bypass mode (if enabled for your lane) accepts the order, skips unknown SKUs, and returns skipped_codes in the response. Contact your administrator to enable bypass mode.

reference must be unique per order (e.g. your PO number or order ID).

shipment_type is optional and defaults to normal. normal means cargo that may be mixed with other shipments during consolidation. dangerous_goods means cargo that must not be mixed with other shipments.

Payload Structure by Transport Mode¶

Payload format and required fields depend on the transportation mode. Choose the mode:

Success Responses¶

201 Created — Order accepted and queued for optimization.

                                            {
  "message": "Order has been created and will be processed shortly",
  "order_id": 42
}

                                        

When bypass mode skips unknown item codes, the response includes skipped_codes: ["SKU-001", "SKU-002"]. The order is still created; only the unknown items are excluded.

200 Success — Supplier/consignee pair has no configured lane yet.

                                            {
  "detail": "Your request has been received. A new lane is being set up and the packing instructions will be sent as soon as possible."
}

                                        

Request submitted successfully and a new lane would be set up. If extra_recipients was provided, those contacts also receive a notification email.

Error Responses¶

400 — Validation error

                                            { "reference": ["This field is required."] }

                                        

401 — Invalid API key

422 — Business rule failure (e.g. transport mode rules, missing containers for FCL/FTL)

                                            {
  "order_containers": "Order container(s) are mandatory for ocean shipments."
}

                                        

                                            {
  "order_containers": "Lane container with code 40ft does not exist."
}

                                        

                                            {
  "non_field_errors": "Must include at least one of order_items, pre_builts, or loose_boxes."
}

                                        

For 422, the value for a field may be a single message string (as above) or a list of strings, depending on the error. See Payload Format for order_containers rules and Payload Format for modes that do not use order_containers.

Retrieving Packing Instructions¶

Use the Download Packing Instructions endpoint to fetch the PI file after the order is created.