FCL/FTL Shipments¶

Payload Format¶

Use this payload structure for OceanFCL and TruckFTL shipments.

Endpoint¶

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

Requirements¶

At least one of order_items, pre_builts, or loose_boxes

Shipment Content Types¶

Select the content type(s) that match how your goods are supplied. You can mix types in one order.

Order Items (order_items)

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

Use when: You want automatic pallet building; products ship as loose units; the supplier does not pre-pack.

Includes: item (product/SKU), quantity, and optional metadata (PO, line number, notes). See Order Item Fields below.

Summary: Raw units requiring automatic packing.

Pre-Built Pallets (pre_builts)

A fully assembled pallet prepared by the supplier before submission. Dimensions, weight, and item composition are fixed.

Use when: Supplier provides ready-made pallets; you want direct container loading; you do not want the optimizer to build pallets.

Includes: Dimensions (L×W×H), weight, count, and optional prebuiltitem_set. See Pre-Built Pallet Fields below.

Summary: Ready-made pallets for direct loading.

Pre-Built Item Set (prebuiltitem_set)

A detailed breakdown of items inside each pre-built pallet.

Use when: You need item-level packing instructions; customs or compliance requires item breakdown; traceability is needed.

Includes: See Pre-Built Item Breakdown Fields below.

Summary: What is inside each pre-built pallet.

Loose Boxes (loose_boxes)

A single carton not part of any pallet. Each carton has known dimensions and weight and is arranged during optimization.

Use when: Supplier ships standalone cartons; cartons need dynamic placement; box dimensions influence load planning.

Includes: Dimensions, weight, count, and optional PO/line/product data. See Loose Box Fields below.

Summary: Individual cartons not palletized.

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 for this order. Determines required fields and how packing is optimized. See: Accepted Transportation Modes.
`order_items`	Array of Objects	No	A list of items being ordered. See Order Item Fields below.
`pre_builts`	Array of Objects	No	A list of pre-built pallets. See Pre-Built Pallet Fields below.
`loose_boxes`	Array of Objects	No	A list of loose boxes. See Loose Box Fields below.
`order_container`	Object	Yes	Container information for the order. See: Order Containers Details
`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	No	Email addresses for additional recipients (To).
`extra_cc_recipients`	Array of Strings	No	CC recipients for the packing instruction email.

Order Item Fields¶

See Order Item Explanation above for usage.

Field	Type	Is Required	Notes
`item`	String	Yes	The item code that will be ordered.
`quantity`	Integer	Yes	Number of units ordered.
`purchase_order`	String	No	Purchase order reference.
`line_item_number`	String	No	Line item number.
`notes`	String	No	Notes or comments.

Pre-Built Pallet Fields¶

See Pre-Built Explanation above for usage.

Field	Type	Is Required	Notes
`name`	String	Yes	Name of the prebuilt pallet.
`length`, `width`, `height`, `weight`	String	Yes	Dimensions and weight of the pallet.
`count`	Integer	Yes	Number of pallets.
`prebuiltitem_set`	Array of Objects	No	Items included inside the pallet.

Pre-Built Item Breakdown Fields¶

See Pre-Built Item Set Explanation above for usage.

Field	Type	Is Required	Notes
`purchase_order`	String	No	Purchase order number.
`line_item_number`	String	No	Line item reference.
`quantity`	Integer	Yes	Quantity of the item.
`packages`	Integer	No	Number of packages.
`product_code`	String	Yes	Product code reference.
`product_type`	String	No	Type/category of product.

Loose Box Fields¶

See Loose Box Explanation above for usage.

Field	Type	Is Required	Notes
`name`	String	Yes	Identifier for the box.
`length`, `width`, `height`, `weight`	String	Yes	Dimensions and weight of the box.
`count`	Integer	Yes	Number of boxes.
`purchase_order`	String	No	Related purchase order.
`line_item_number`	String	No	Line item number.
`product_quantity`	Integer	No	Total quantity of items in a box.
`product_packages`	Integer	No	Total count of boxes.

Order Container Fields¶

Specifies the container type (and optionally count) for FCL/FTL shipments.

Field	Type	Is Required	Notes
`code`	String	Yes	Must be one of the Accepted Container Codes.
`count`	Integer	No	Number of containers. Default is 5 (used when count is omitted).

Accepted Container Codes¶

20ft, 40ft, 40ft-HC, 45ft-HC, 20ft-RF, 40ft-HC RF, 20ft-OT, 40ft-OT

Accepted Transportation Modes¶

OceanFCL, TruckFTL

Example Request¶

                                            {
  "order_items": [
    {
      "item": "PRD-001",
      "quantity": 2,
      "purchase_order": "string",
      "line_item_number": "string",
      "notes": "string"
    }
  ],
  "pre_builts": [
    {
      "name": "PreBuilt Box A",
      "length": "120.0",
      "width": "80.0",
      "height": "100.0",
      "weight": "35.5",
      "count": 2,
      "prebuiltitem_set": [
        {
          "purchase_order": "PO-001",
          "line_item_number": "L1",
          "quantity": 20,
          "packages": 5,
          "product_code": "PRD-A",
          "product_type": "Electronics"
        }
      ]
    }
  ],
  "loose_boxes": [
    {
      "name": "Loose Box 1",
      "length": "60.0",
      "width": "40.0",
      "height": "30.0",
      "weight": "8.5",
      "count": 5,
      "purchase_order": "PO-002",
      "line_item_number": "L2",
      "product_quantity": 100,
      "product_packages": 10
    }
  ],
  "reference": "REF-999",
  "customer_notes": "Urgent, deliver by end of week",
  "supplier_name": "Supplier",
  "consignee_name": "Consignee",
  "transportation_mode": "OceanFCL",
  "send_email": false,
  "extra_recipients": ["email1@example.com", "email2@example.com"],
  "extra_cc_recipients": ["email3@example.com", "email4@example.com"],
  "order_container": {
    "code": "20ft",
    "count": 5
  }
}

                                        

Notes: Include at least one of order_items, pre_builts, or loose_boxes. order_container.code must match an accepted container code.