[GET] Retrieve container loading steps#

Returns the load plan of an FCL / FTL shipment once it has been optimized: every container used, the loading steps for each container in the order they are carried out, and every collo (box or pallet) to load at each step.

GET https://BASE_URL/api/v1/orders/container-loading-steps/

Note

In the examples, BASE_URL is the base URL of your environment, for example https://api.alphaaugmented.com. See Base URLs for the complete list.

Requires Authentication.

When to call#

Use this endpoint

After optimization completes on an FCL or FTL shipment, to load the containers step by step.

Not for pallet shipments

Air, LCL and LTL shipments have no containers. Use [GET] Retrieve pallet contents for what is on each ALPHA-built pallet.

Production flows should wait for packing_instructions.ready ( Event types) instead of polling. This endpoint is also useful for retries and backfills once you know optimization finished.

Parameters#

Same lookup as [GET] Download packing instructions: the order’s reference or alpha_ref. If several orders share a reference, the API uses the newest match.

Parameter

Type

Description

order

string

Required. The order’s reference or alpha_ref.

include_images

boolean

Optional, default false. Adds an image of each loading step. Rendering the images makes the response slower.

Request#

curl "https://BASE_URL/api/v1/orders/container-loading-steps/?order=YOUR_REF" \
  -H "Authorization: Api-Key YOUR_API_KEY"

Response#

200 OK with Content-Type: application/json. Containers are listed in the order produced by the optimizer, steps in loading order, and the colli in each step from bottom to top.

Shape:

{
  "meta": {
    "interactive_pi_url": "<portal link>"
  },
  "containers": [
    {
      "container": <integer>,
      "container_code": "<lane container type, e.g. 40HC>",
      "total_weight": <number>,
      "total_colli": <integer>,
      "steps": [
        {
          "step": <integer>,
          "image": "<base64 PNG>" | null,
          "contents": [
            {
              "position": "<e.g. Row: 1, Position: 1, Layer: 1>",
              "load_type": "box" | "pallet",
              "pallet_id": "<pallet index, e.g. AP1>" | null,
              "rotation": "<e.g. LWH>",
              "name": "<name>",
              "width": <number>,
              "length": <number>,
              "height": <number>,
              "un_number": ["<UN number>"],
              "dg_class": ["<DG class>"],
              "pi_number": ["<PI number>"],
              "warehouse_location": "<location>",
              "limited_quantity": ["<LQ>"],
              "huid": "<handling unit ID>",
              "bonded_cargo": <boolean>,
              "double_stacked_bottom": <boolean>,
              "double_stacked_top": <boolean>,
              "containerize": <boolean>
            }
          ]
        }
      ]
    }
  ]
}

Example:

{
  "meta": {
    "interactive_pi_url": "https://portal.alphaaugmented.com/interactive-packing-instructions?ref=ALPHA-000123"
  },
  "containers": [
    {
      "container": 1,
      "container_code": "40HC",
      "total_weight": 1850.5,
      "total_colli": 3,
      "steps": [
        {
          "step": 1,
          "image": null,
          "contents": [
            {
              "position": "Row: 1, Position: 1, Layer: 1",
              "load_type": "pallet",
              "pallet_id": "AP1",
              "rotation": "LWH",
              "name": "EUR",
              "width": 80.0,
              "length": 120.0,
              "height": 150.0,
              "un_number": [],
              "dg_class": [],
              "pi_number": [],
              "warehouse_location": "",
              "limited_quantity": [],
              "huid": "",
              "bonded_cargo": false,
              "double_stacked_bottom": true,
              "double_stacked_top": true,
              "containerize": true
            },
            {
              "position": "Row: 1, Position: 2, Layer: 1",
              "load_type": "pallet",
              "pallet_id": null,
              "rotation": "WLH",
              "name": "Pallet 1",
              "width": 80.0,
              "length": 120.0,
              "height": 110.0,
              "un_number": ["1234"],
              "dg_class": ["3"],
              "pi_number": ["966"],
              "warehouse_location": "R-12",
              "limited_quantity": [],
              "huid": "HUID-0001",
              "bonded_cargo": true,
              "double_stacked_bottom": true,
              "double_stacked_top": false,
              "containerize": true
            }
          ]
        },
        {
          "step": 2,
          "image": null,
          "contents": [
            {
              "position": "Row: 2, Position: 1, Layer: 1",
              "load_type": "box",
              "pallet_id": null,
              "rotation": "LWH",
              "name": "Carton 12",
              "width": 40.0,
              "length": 60.0,
              "height": 45.0,
              "un_number": [],
              "dg_class": [],
              "pi_number": [],
              "warehouse_location": "B-03",
              "limited_quantity": [],
              "huid": "HUID-0002",
              "bonded_cargo": false,
              "double_stacked_bottom": false,
              "double_stacked_top": true,
              "containerize": false
            }
          ]
        }
      ]
    }
  ]
}

Response fields#

meta holds information about the shipment as a whole:

Field

Type

Description

interactive_pi_url

string

Link to the interactive packing instructions in the Alpha portal. Opening it requires a portal login with access to the shipment.

Each object in containers:

Field

Type

Description

container

integer

Position of the container in the shipment, starting at 1.

container_code

string

Lane container type code (for example 40HC).

total_weight

number

Weight of all colli in the container. Units follow the lane setting.

total_colli

integer

Number of colli in the container.

steps

array

Loading steps, in the order to load them.

Each object in steps:

Field

Type

Description

step

integer

Step number, starting at 1.

image

string or null

The container after this step, as a base64-encoded PNG (no data: prefix). null unless include_images=true, and also null if the image could not be rendered; the contents are still returned.

contents

array

One entry per collo loaded at this step, bottom to top.

Each object in contents:

Field

Type

Description

position

string

Where the collo goes, as Row: <n>, Position: <n>, Layer: <n>. All three count from 1: Row from the back of the container, Position across the width and Layer up from the floor. Older optimizations may return the earlier R1, A1 form, or an empty string if they ran before positions were available.

load_type

string

box or pallet.

pallet_id

string or null

For ALPHA-built pallets, the pallet_index to look up in [GET] Retrieve pallet contents. null for boxes and pre-built pallets.

rotation

string

How the collo is turned, as the order of its length (L), width (W) and height (H). LWH means not rotated.

name

string

Name of the box or pallet as submitted. For ALPHA-built pallets, the lane pallet type (for example EUR).

width, length, height

number

Dimensions of the collo. Units follow the lane setting.

un_number, dg_class, pi_number, limited_quantity

array of strings

Dangerous goods details, as submitted on the loose box or pre-built pallet. Empty when not set.

warehouse_location

string

Warehouse location as submitted. Empty when not set.

huid

string

Handling unit ID as submitted. Empty when not set.

bonded_cargo

boolean

Whether the shipment was submitted as bonded cargo. false for ALPHA-built pallets.

double_stacked_bottom

boolean

Whether the box or pre-built pallet may be stacked below, as submitted. true for ALPHA-built pallets.

double_stacked_top

boolean

Whether the box or pre-built pallet may be stacked above, as submitted. true for ALPHA-built pallets.

containerize

boolean

Whether the box or pre-built pallet is to be containerized, as submitted. true for ALPHA-built pallets.

Errors#

HTTP status

Description

400 Bad Request

Unknown order, not an FCL / FTL shipment, or results not ready

401 Unauthorized

Missing or invalid API key

{
  "order": [
    "No order found matching the provided reference."
  ]
}
{
  "order": [
    "Container loading steps are only available for FCL and FTL shipments"
  ]
}
{
  "order": [
    "Optimization results not available yet, please try after a couple of minutes. If not ready within 10 minutes, reach out to our support team"
  ]
}
{ "detail": "Invalid API key." }

See Troubleshooting if requests fail unexpectedly.