LTL Shipments¶

Payload Format¶

Use this payload structure for Air, OceanLCL, and TruckLTL shipments.

Endpoint¶

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

Requirements¶

At least one order_items entry
Prior setup with ALPHA is required: these transportation modes need a configured lane (supplier/consignee, item master, packaging, and mode enabled for the lane). See Submit Order for prerequisites.

Tip

First-time integrator? Start with Example Request near the bottom, then come back to the field tables as needed.

Shipment Content Types¶

For Air, OceanLCL, and TruckLTL, cargo is submitted as order_items.

Type	What you provide	What ALPHA does	Best for
`order_items`	SKU + quantity (raw units)	Builds pallet/loading plan automatically	Non-containerized lanes (Air/LCL/LTL)

Request Body Fields¶

Field	Type	Is Required	Notes
`supplier_name`	String	Yes	Supplier name. Must match exactly as configured in the ALPHA Portal (case-sensitive).
`consignee_name`	String	Yes	Consignee name. Must match exactly as configured in the ALPHA Portal (case-sensitive).
`reference`	String	Yes	Your order reference (e.g. PO number). Must be unique per order.
`transportation_mode`	String	Yes	Transport type. Use `Air`, `OceanLCL`, or `TruckLTL`.
`shipment_type`	String	No	Allowed options normal (default) — may be consolidated with other shipments. dangerous_goods — must not be consolidated with other shipments.
`order_items`	Array of Objects	Yes	List of items being ordered. See Order Item Fields below.
`customer_notes`	String	No	Customer-related metadata.
`send_email`	Boolean	No	Whether to send the packing instructions by email. Defaults to true.
`extra_recipients`	Array of Strings (Email addresses)	No	A list of email addresses to send the packing instructions (To).
`extra_cc_recipients`	Array of Strings (Email addresses)	No	A list of email addresses to send the packing instructions (CC).

Order Item Fields¶

Order items represent raw, unpacked product units with no packaging. The optimizer groups these units into pallets and shipment loading automatically.

Use when: Products ship as loose units and you want automatic packing/arrangement.

Includes: item (product/SKU), quantity, and optional metadata (purchase_order, line_item_number, notes).

Summary: Raw units requiring automatic packing.

Important

This flow requires valid item master data (SKU dimensions/weights) for submitted item codes on the configured supplier/consignee lane.

Field	Type	Is Required	Notes
`item`	String	Yes	The item code that will be ordered.
`quantity`	Number ≥ 0.01	Yes	Decimals are allowed for weight and volume quantities; normalized when the order is saved.
`purchase_order`	String	No	Purchase order reference.
`line_item_number`	String	No	Line item number.
`notes`	String	No	Notes or comments.

Accepted Transportation Modes¶

Mode	Use case
`Air`	Air freight shipments
`OceanLCL`	Ocean less-than-container-load shipments
`TruckLTL`	Truck less-than-truckload shipments

Example Request¶

Minimal valid request

                                            {
  "reference": "REF-AIR-MIN-001",
  "supplier_name": "Supplier",
  "consignee_name": "Consignee",
  "transportation_mode": "Air",
  "order_items": [
    {
      "item": "PRD-001",
      "quantity": 10
    }
  ]
}

                                        

Full example

                                            {
  "reference": "REF-AIR-FULL-001",
  "supplier_name": "Supplier",
  "consignee_name": "Consignee",
  "transportation_mode": "Air",
  "shipment_type": "normal",
  "customer_notes": "Urgent, deliver by end of week",
  "send_email": false,
  "extra_recipients": ["email1@example.com", "email2@example.com"],
  "extra_cc_recipients": ["email3@example.com", "email4@example.com"],
  "order_items": [
    {
      "item": "PRD-001",
      "quantity": 2,
      "purchase_order": "PO-001",
      "line_item_number": "1",
      "notes": "Handle with care"
    }
  ]
}

                                        

Notes: order_items are required. Do not include order_containers in the request. PI is generated after creation and emailed when send_email is true (default).