Choosing between /pack and /pack_pallet

Both endpoints share the same request and response schema (orders, items, bins). The difference is which packing problem they solve.

Quick decision

Use /pack when:

• You are cartonising, picking the best carton out of a catalogue per order.
• You want carrier-cost optimisation (cheapest box + cheapest carrier combo). See the cost-optimisation guide.
• You are using box-on-demand (right-sized cartons via adjust_*_min). See the box-on-demand guide.
• You are packing into trucks or generic 3D bins.

Use /pack_pallet when:

• You are stacking onto a pallet with layer-based rules, divider plates, or robotic-arm constraints.
• A single pallet shape (or shape-per-tag-group) is the goal, not bin selection.

Differences in detail

Bin selection

• /pack chooses among all bins in the request per order. The algorithm picks the bin that fits while minimising cost (or, with no costs, count).
• /pack_pallet uses the first bin in the request as the pallet shape. Items with tags can be routed to specific bins with tags via tag-subset matching, but the algorithm itself does not select between multiple pallet shapes.

Carrier cost optimisation

• /pack supports config.carrier_preset_ids and per-bin packaging_cost / transport_cost. See the cost-optimisation guide.
• /pack_pallet does not evaluate carriers. Cost fields on the bin are ignored.

Box-on-demand (right-sized cartons)

• /pack auto-switches to box-on-demand when any bin has adjust_width_min, adjust_height_min, or adjust_depth_min set. See the box-on-demand guide.
• /pack_pallet ignores adjust_*_min.

Pallet-only knobs (/pack_pallet only)

• Layer-based stacking: max_layers, max_layer_height_diff, min_layer_fill_rate, volume_percentage_bottom_layer.
• Divider plates: dividers, min_dividers, requires_divider_under_box.
• Robotic-arm constraints: stack_on_width_edge, stack_on_height_edge, stack_on_depth_edge, interlock, pick_boxes.
• Multi-pallet output via small-item handling: small_items_min_layer_qty_of_towers, small_items_max_layer_unique_ids.

To have an accurate overview of which attributes are taken into account only by the cartonization or only by the palletization algorithm, see our generated API docs of the Item and Bin models. Attributes that are only relevant for one of the two algorithms contain a "Applies to:" tag. If no such tag is found in the description of the attribute, it is relevant for both algorithms.

Access control

• /pack_pallet requires has_pallet_access on the account. If your account does not have it, the request is rejected with 403.

Request options

• /pack accepts ?compressed=true to compress the response payload (useful for orders with many packed bins).
• Both endpoints accept ?synchronous=false for asynchronous invocation.

At a glance

Capability	/pack	/pack_pallet
Multi-bin selection per order	✓
Carrier cost optimisation	✓
Box-on-demand (adjust_*_min)	✓
Compressed response payload	✓
Layer-based stacking		✓
Divider plates		✓
Robotic-arm constraints		✓
Tag-based bin routing		✓
Same request and response schema	✓	✓
Async via Lambda	✓	✓

Examples

The same minimal order, sent to both endpoints. Note that the request body shape is identical; the response shape is also identical, but the optimised quantity (packed cartons vs packed pallets) reflects each algorithm's goal.

/pack

curl -X POST 'https://optiapp.api.optioryx.com/pack' \
  -H 'x-api-key: <API_KEY>' \
  -d '{
    "orders": [
      {
        "id": "order_1",
        "items": [
          {
            "id": "item_1",
            "width": 1,
            "height": 1,
            "depth": 1,
            "quantity": 2
          },
          {
            "id": "item_2",
            "width": 2,
            "height": 0.5,
            "depth": 2,
            "quantity": 2
          },
          {
            "id": "item_3",
            "width": 1,
            "height": 2,
            "depth": 0.25,
            "quantity": 4
          }
        ]
      }
    ],
    "bins": [
      {
        "id": "bin_1",
        "width": 2,
        "height": 2,
        "depth": 2
      }
    ]
  }'

/pack_pallet

curl -X POST 'https://optiapp.api.optioryx.com/pack_pallet' \
  -H 'x-api-key: <API_KEY>' \
  -d '{
    "orders": [
      {
        "id": "order_1",
        "items": [
          {"id": "sku_a", "width": 12, "height": 10, "depth": 20, "quantity": 42},
          {"id": "sku_b", "width": 40, "height": 10, "depth": 40, "quantity": 14}
        ]
      }
    ],
    "bins": [
      {"id": "euro_pallet", "width": 120, "height": 40, "depth": 80}
    ]
  }'