[POST] Package best fit#

Calculates the best fit for one box across the container and pallet types you send. Use it to compare packaging and transport options before you create a shipment.

POST https://BASE_URL/api/v1/package-fit/

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

Compare how well one box fills your containers and pallets, for example to choose a box size or check packaging before you create an order.

Not for shipments

This endpoint does not plan a shipment. To optimize a real shipment, use [POST] Create an order.

Container and pallet types#

Container and pallet types are identified by short codes, for example 40HC for a high-cube container or EUR1 for a Euro pallet. These codes are provided by ALPHA for your account, based on your setup.

  • Codes are case-insensitive: 40hc and 40HC give the same result.

  • If you list the same code more than once, it is calculated only once.

  • Only types that are currently available can be used.

  • An unknown code returns 400.

Limits#

Limit

Value

Container types per request

2

Pallet types per request

3

Boxes per container type

2500

Boxes per pallet type

500

ALPHA limits the number of types and boxes per request.

Request structure#

{
  "package": {
    "box_id": "<string>",
    "length": "<number>",
    "width": "<number>",
    "height": "<number>",
    "weight": "<number>",
    "rotation": "L | W | H"
  },
  "container_types": ["<container code>"],
  "pallet_types": ["<pallet code>"],
  "pallet_max_height": "<number>",
  "include_images": false
}

Send dimensions in cm and weight in kg. This endpoint always uses these units, regardless of your lane’s Units of measure settings.

Example request#

{
  "package": {
    "box_id": "BOX-4711",
    "length": 40,
    "width": 30,
    "height": 30,
    "weight": 5,
    "rotation": "L"
  },
  "container_types": ["20DC", "40HC"],
  "pallet_types": ["EUR1", "GMA"],
  "pallet_max_height": 150
}

cURL:

curl https://BASE_URL/api/v1/package-fit/ \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "package": {
      "box_id": "BOX-4711",
      "length": 40,
      "width": 30,
      "height": 30,
      "weight": 5,
      "rotation": "L"
    },
    "container_types": ["20DC", "40HC"],
    "pallet_types": ["EUR1", "GMA"],
    "pallet_max_height": 150
  }'

Parameters#

Top-level fields for the request body.

Field

Type

Description

package

object

Required. The box to test.

container_types

array of strings

Optional. Up to two container type codes. Leave out or send [] to skip containers.

pallet_types

array of strings

Optional. Up to three pallet type codes. Leave out or send [] to skip pallets. Send at least one container or pallet type.

pallet_max_height

number

Required when you send pallet_types. Maximum height of the loaded pallet in cm, including the pallet itself.

include_images

boolean

Optional, default false. Adds a picture of the best load for each type in image. Generating images makes the call slower.

Package fields#

Objects in package.

Field

Type

Description

box_id

string

Required. Your identifier for the box, up to 255 characters. Returned unchanged.

length / width / height

number

Required. Box dimensions in cm, at least 0.01 each. height points up when the box stands upright.

weight

number

Required. Box weight in kg, at least 0.01.

rotation

string

Optional. Rotations allowed while packing, written as L, W and H. Empty means the box must stay as sent. See Rotation.

Response#

200 OK. One result for each type you requested, in the order you sent them. The containers and pallets arrays are empty when you skip that kind of type.

{
  "box_id": "BOX-4711",
  "containers": [
    {
      "container": "20DC",
      "box_count": 756,
      "layer_count": 7,
      "column_count": 19,
      "orientation": "L",
      "utilization": 81.99,
      "square_utilization": 119700.0,
      "image": null,
      "packing_instructions": null
    },
    {
      "container": "40HC",
      "box_count": 1840,
      "layer_count": 8,
      "column_count": 30,
      "orientation": "L",
      "utilization": 86.76,
      "square_utilization": 288000.0,
      "image": null,
      "packing_instructions": null
    }
  ],
  "pallets": [
    {
      "pallet": "EUR1",
      "box_count": 32,
      "layer_count": 4,
      "column_count": 3,
      "orientation": "L",
      "utilization": 88.5,
      "square_utilization": 14400.0,
      "image": null,
      "packing_instructions": null
    },
    {
      "pallet": "GMA",
      "box_count": 40,
      "layer_count": 4,
      "column_count": 3,
      "orientation": "L",
      "utilization": 85.81,
      "square_utilization": 14400.0,
      "image": null,
      "packing_instructions": null
    }
  ]
}

See Response fields.

Response fields#

Field

Type

Description

box_id

string

The identifier you sent.

containers

array

Results for the container types you requested.

pallets

array

Results for the pallet types you requested.

Each result has these fields:

Field

Type

Description

container or pallet

string

The type code as sent.

box_count

integer

How many boxes fit in this container or pallet type. 0 when the box does not fit, for example because it is too large or too heavy.

layer_count

integer

Number of layers of boxes stacked on top of each other. 0 when box_count is 0.

column_count

integer

Number of boxes in a row along the length. 0 when box_count is 0.

orientation

string

The rotations used, written as L, W and H. Empty when box_count is 0. See Rotation.

utilization

number

Percentage of the available volume filled by the boxes, from 0 to 100. On pallets, volume is measured above the deck.

square_utilization

number

Area the load covers when viewed from the side, in cm². See Square utilization.

image

string or null

Base64-encoded PNG of the load, without a data: prefix. null unless include_images is true, or if the image could not be generated.

packing_instructions

string or null

Reserved for future use. Always null in this version of the API.

Note

When box_count is 0, the box does not fit in that type. The other measurements are 0 and orientation is empty.

Errors#

HTTP status

Description

400 Bad Request

Invalid field, no types selected, unknown type code, too many types, or a box so small that the estimated box count would exceed the per-type limit.

401 Unauthorized

The API key is missing or invalid.

502 Bad Gateway

ALPHA could not complete the calculation. Try again later.

{ "container_types": ["Unknown type(s): 53HC."] }
{
  "container_types": [
    "The box is too small for these types: 20DC (up to 265567), 40HC (up to 265400). The limit is 2500 boxes per type."
  ],
  "pallet_types": [
    "The box is too small for these types: EUR1 (up to 10414), GMA (up to 12500). The limit is 500 boxes per type."
  ]
}
{ "pallet_types": ["Ensure this field has no more than 3 elements."] }
{
  "package": {
    "rotation": ["Use one or more of the letters L, W and H."]
  }
}
{ "detail": "Authentication credentials were not provided." }
{ "detail": "The packing engine could not complete the request." }

See Troubleshooting if requests fail unexpectedly.