FCL/FTL Shipments¶

Payload Format¶

Use this payload structure for OceanFCL and TruckFTL shipments.

Endpoint¶

POST

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

Requirements¶

Container list: A non-empty order_containers array. Each object has a code (and optional count).
Cargo: At least one of order_items, pre_builts, or loose_boxes

Tip

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

Shipment Content Types¶

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

Type	What you provide	What ALPHA does	Best for
`order_items`	SKU + quantity (raw units)	Builds pallets and container plan	Supplier does not pre-pack
`pre_builts`	Ready pallet dimensions + weight	Loads pallets as provided	Supplier sends pre-assembled pallets
`loose_boxes`	Box dimensions + weight + count	Places cartons into containers	Standalone cartons not pre-palletized

Field details for each content type are in the sections below.

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 Max 64 chars	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.
`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	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_containers`	Array of Objects	Yes	One or more container specifications for this order. Use a list (not a single object). 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¶

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).

Summary: Raw units requiring automatic packing.

Important

When order_items are provided, ALPHA runs palletization optimization as part of the order flow before final container loading.

This requires prior setup (onboarding) for the lane, including supplier/consignee mapping and valid item master data (SKU dimensions/weights) for submitted items.

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 Max 64 chars	No	Purchase order reference. Do not use & or commas.
`line_item_number`	String Max 64 chars	No	Line item number. Do not use & or commas.
`notes`	String	No	Notes or comments.

Pre-Built Pallet Fields¶

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 (LxWxH), weight, count, optional stackability (double_stacked_bottom, double_stacked_top), optional rotation_x, and optional prebuiltitem_set.

Summary: Ready-made pallets for direct loading.

Field	Type	Is Required	Notes
`name`	String Max 64 chars	Yes	Name of the pre-built pallet.
`length`, `width`, `height`	String > 0 Max 12 digits, 6 decimals	Yes	Outer dimensions of the pallet (length, width, height). Units follow your lane (Units of Measure).
`weight`	String > 0 Max 15 digits, 6 decimals	Yes	Total weight of the pallet. Units follow your lane (Units of Measure).
`count`	Integer ≥ 1	Yes	How many identical pallets this row describes.
`prebuiltitem_set`	Array of Objects	No	Items on the pallet. See Pre-Built Item Fields.
`double_stacked_bottom`	Boolean	No	This pallet can be stacked below. Optional; defaults apply when omitted.
`double_stacked_top`	Boolean	No	This pallet can be stacked above. Optional; defaults apply when omitted.
`rotation_x`	Boolean	No	Default is true. Allows turning the pallet in the floor plane (length/width may swap). false locks the footprint you sent.

Loose Box Fields¶

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, optional stackability (double_stacked_bottom, double_stacked_top), optional rotation flags (rotation_x, rotation_y, rotation_z), and optional PO/line/quantity metadata.

Summary: Individual cartons not palletized.

Field	Type	Is Required	Notes
`name`	String Max 64 chars	Yes	Identifier for the box.
`length`, `width`, `height`	String > 0 Max 12 digits, 6 decimals	Yes	Outer dimensions of the carton (length, width, height). Units follow your lane (Units of Measure).
`weight`	String > 0 Max 15 digits, 6 decimals	Yes	Total weight of the carton. Units follow your lane (Units of Measure).
`count`	Integer ≥ 1	Yes	How many identical cartons this row describes.
`purchase_order`	String Max 64 chars	No	Related purchase order.
`line_item_number`	String Max 64 chars	No	Line item number.
`product_quantity`	Integer ≥ 1 if set	No	Optional. Total quantity of items in a box.
`product_packages`	Integer ≥ 1 if set	No	Optional. Total count of packages for this line.
`double_stacked_bottom`	Boolean	No	This box can be stacked below. Optional; defaults apply when omitted.
`double_stacked_top`	Boolean	No	This box can be stacked above. Optional; defaults apply when omitted.
`rotation_x`, `rotation_y`, `rotation_z`	Boolean	No	Optional; defaults to true for all three. Send all three together. Use all false for no rotation, only rotation_x for floor spin, only rotation_y for limited tilt, or all true / omit for any orientation.

Pre-Built Item Fields¶

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.

Summary: What is inside each pre-built pallet.

Field	Type	Is Required	Notes
`purchase_order`	String Max 64 chars	No	Purchase order number.
`line_item_number`	String Max 64 chars	No	Line item reference.
`quantity`	Integer ≥ 1	Yes	Units of this SKU on one pallet.
`packages`	Integer ≥ 1 if set	No	Optional. If you send it, use a whole number ≥ 1.

Order Container Fields¶

Each object in order_containers specifies a container type and an optional count (FCL/FTL).

Note

count is optional. If you omit it, ALPHA uses the default value.
For OceanFCL and TruckFTL, order_containers is still required and must be non-empty.
If you want ALPHA to consider all configured container types for a lane, include each desired code in order_containers and omit count where you do not want to specify quantities.

Quantity behavior at a glance

What you want	What to send	Outcome
Use a specific number of a container type	Include `code` + `count`	ALPHA uses your exact quantity for that type.
Use a container type but do not specify quantity	Include `code` and omit `count`	ALPHA applies the default quantity.
Use all configured container types	Include each lane-supported `code` in `order_containers` (omit `count` where needed)	ALPHA evaluates all listed types.

Warning

For OceanFCL and TruckFTL, do not omit order_containers entirely. It is mandatory and must include at least one code.

Example: omit count for one container type

                                                {
  "transportation_mode": "OceanFCL",
  "shipment_type": "normal",
  "order_items": [{ "item": "PRD-001", "quantity": 10 }],
  "order_containers": [
    { "code": "20ft", "count": 2 },
    { "code": "40ft" }
  ]
}

                                            

Field	Type	Is Required	Notes
`code`	String	Yes	Must be one of the Accepted Container Codes.
`count`	Integer ≥ 1 if set	No	Optional. If you omit it, 5 is used for that row. If you send it, use a whole number ≥ 1.

Accepted Container Codes¶

Note

The lane must be configured with the requested code. A known code can still be rejected if it is not enabled for your supplier/consignee lane.

Standard / High Cube	Specialized
`20ft`, `40ft`, `40ft-HC`, `45ft-HC`	`20ft-RF`, `40ft-HC RF`, `20ft-OT`, `40ft-OT`

Accepted Transportation Modes¶

Mode	Use case
`OceanFCL`	Full container load by ocean
`TruckFTL`	Full truck load by road

Example Request¶

Minimal valid request

                                            {
  "reference": "REF-FCL-MIN-001",
  "supplier_name": "Supplier",
  "consignee_name": "Consignee",
  "transportation_mode": "OceanFCL",
  "shipment_type": "dangerous_goods",
  "order_containers": [
    {
      "code": "40ft"
    }
  ],
  "order_items": [
    {
      "item": "PRD-001",
      "quantity": 10
    }
  ]
}

                                        

Full example (mixed cargo)

                                            {
  "reference": "REF-999",
  "supplier_name": "Supplier",
  "consignee_name": "Consignee",
  "transportation_mode": "OceanFCL",
  "shipment_type": "dangerous_goods",
  "order_containers": [
    {
      "code": "20ft",
      "count": 5
    }
  ],
  "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": "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
        }
      ]
    }
  ],
  "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
    }
  ]
}

                                        

Notes: Include at least one of order_items, pre_builts, or loose_boxes. Omitting order_containers or sending an empty array is invalid for OceanFCL and TruckFTL (order_containers is required and must have at least one entry with a code). See Accepted Container Codes for allowed code values.

Warning

Do not include duplicate container code values inside order_containers. Each container type should appear once with its corresponding count.

Example: Multiple container types¶

You can request more than one container type in a single order by including several objects in order_containers (for example, two 20ft and one 40ft, each with its own count).

                                                {
  "reference": "REF-MULTI-CTN-001",
  "supplier_name": "Supplier",
  "consignee_name": "Consignee",
  "transportation_mode": "OceanFCL",
  "shipment_type": "normal",
  "order_containers": [
    { "code": "20ft", "count": 2 },
    { "code": "40ft", "count": 1 }
  ],
  "order_items": [
    {
      "item": "PRD-001",
      "quantity": 10,
      "purchase_order": "PO-100",
      "line_item_number": "1"
    }
  ]
}

                                            

Example: Pre-built pallets and loose boxes only (no `order_items`)¶

You can submit an order with only pre_builts and loose_boxes—omit order_items entirely. In that case you do not need SKU lines from item master data for the cargo: dimensions and weights are fully described on each pre-built pallet and each loose box. (Lane, supplier, consignee, and container configuration still apply as for any order; see Submit Order prerequisites.)

                                                {
  "reference": "REF-FCL-PB-LB-001",
  "supplier_name": "Supplier",
  "consignee_name": "Consignee",
  "transportation_mode": "OceanFCL",
  "shipment_type": "normal",
  "order_containers": [
    {
      "code": "40ft",
      "count": 2
    }
  ],
  "pre_builts": [
    {
      "name": "Floor slot A",
      "length": "120.0",
      "width": "80.0",
      "height": "100.0",
      "weight": "35.5",
      "count": 2,
      "double_stacked_bottom": true,
      "double_stacked_top": false,
      "rotation_x": true,
      "prebuiltitem_set": []
    }
  ],
  "loose_boxes": [
    {
      "name": "Loose carton B",
      "length": "60.0",
      "width": "40.0",
      "height": "30.0",
      "weight": "8.5",
      "count": 4,
      "double_stacked_bottom": true,
      "double_stacked_top": true,
      "rotation_x": true,
      "rotation_y": false,
      "rotation_z": true
    }
  ]
}

                                            

How to¶

Practical workflows for OceanFCL and TruckFTL orders.

Use this section after reviewing the payload field tables and examples above. Each topic is written as a short implementation guide you can follow directly.

How to mark dangerous goods¶

Use this when the whole shipment contains dangerous goods.

At a glance

Goal	Mark the order as dangerous goods.
Field to use	Top-level field shipment_type.
Default	normal
Allowed options	‘normal’ (default) — may be consolidated with other shipments. ‘dangerous_goods’ — must not be consolidated with other shipments.
Where to apply	At the top level of the order submission payload.

Tip

For normal cargo, omit shipment_type (that implies normal). For dangerous goods, set shipment_type to dangerous_goods on the top-level payload object.

Step-by-step¶

Identify dangerous goods shipments Review whether the order contains dangerous goods.
Set the shipment type Set shipment_type to dangerous_goods at the top level of the request body.
Leave normal shipments unchanged For normal cargo, omit shipment_type or set it to normal.

Warning

Do not send shipment_type inside pre_builts or loose_boxes objects.

FCL/FTL Shipments¶

Payload Format¶

Endpoint¶

Requirements¶

Shipment Content Types¶

Request Body Fields¶

Order Item Fields¶

Pre-Built Pallet Fields¶

Loose Box Fields¶

Pre-Built Item Fields¶

Order Container Fields¶

Accepted Container Codes¶

Accepted Transportation Modes¶

Example Request¶

Example: Multiple container types¶

Example: Pre-built pallets and loose boxes only (no order_items)¶

How to¶

How to mark dangerous goods¶

Step-by-step¶

Example: Pre-built pallets and loose boxes only (no `order_items`)¶