Import Packing Layout

The wholesale_order_import_packing_layout mutation allows you to define the full packing structure of a wholesale order in a single API call, rather than building it container-by-container through the ShipHero UI.

Prerequisites

• The wholesale order must be in packing status.
• The order must not have an existing packing configuration. If one already exists (even partially), the import will be rejected. Reset the order’s packing state before re-importing.

Mutation

mutation ImportPackingLayout($data: WholesaleOrderImportPackingLayoutInput!) {
  wholesale_order_import_packing_layout(data: $data) {
    request_id
    complexity
    wholesale_order {
      id
    }
  }
}

Variables:

{
  "data": {
    "order_id": "T3JkZXI6MTIzNDU2",
    "packing_data": {
      "containers": [
        {
          "type": "Package",
          "details": {
            "height": 12.0,
            "length": 10.0,
            "width": 8.0,
            "weight_in_oz": 32.0,
            "container_number": 1
          },
          "line_items": [
            {
              "order_line_item_id": "TGluZUl0ZW06MTIzNDU2",
              "quantity": 1
            }
          ]
        }
      ]
    }
  }
}

This request example assumes the wholesale order uses the COURIER shipping option.

Example response:

{
  "data": {
    "wholesale_order_import_packing_layout": {
      "request_id": "7f4fca5e8cf84cf5967ee27f",
      "complexity": 11,
      "wholesale_order": {
        "id": "V2hvbGVzYWxlT3JkZXI6MTIzNDU2"
      }
    }
  }
}

The packing_data field accepts a JSON object describing the entire container hierarchy.

JSON Structure

The top-level object must contain a containers array. Each entry in the array is a top-level container.

{
  "containers": [
    { "...container object..." },
    { "...container object..." }
  ]
}

Container Types

Every container object must include a type field and a details field. The supported types are:

Shipping option constraints

• Freight orders: Only Pallet and UOM Pallet are allowed at the top level. Packages and CasePacks must be nested inside a pallet.
• Courier orders: Pallet and UOM Pallet are not allowed at any level. Use Package and CasePack as top-level containers.

Nesting rules

• Pallets and UOM Pallets can only appear at the top level. They cannot be placed inside another container.
• Packages can be nested inside other packages or inside pallets, up to a maximum depth:
  • Freight: 3 levels (e.g., Pallet → Package → Package)
  • Courier: 2 levels (e.g., Package → Package)
• CasePacks can appear inside a pallet, inside a package, or at the top level (courier orders). They are always leaf nodes and do not count toward the nesting depth.

Container Fields

Shipping boxes and dimension precedence

Pallet and Package containers can reference either a custom box or a carrier box. The two fields are mutually exclusive.

weight_in_oz is always required for Pallet and Package; weight never comes from the referenced box.

When using a box reference, omit height, length, and width. If supplied, they do not override the box, although each supplied value must still be greater than 0.

Use the custom_boxes query to obtain a custom box id, or the carrier_boxes query to obtain a carrier box box_code. The selected box must be active, accessible to the authenticated user, and available at the order’s staging warehouse. A carrier box code must resolve to one connected carrier without ambiguity.

The referenced box must have all three dimensions configured. Each dimension must be greater than 0 and at most 99.9999, with up to 4 decimal places.

Pallet

{
  "type": "Pallet",
  "details": {
    "weight_in_oz": 1600.0,
    "sscc_barcode": "PALLET001",
    "custom_box_id": "QXZhaWxhYmxlQm94OjEyMzQ1Ng==",
    "container_number": 1
  },
  "line_items": [ ],
  "containers": [ ]
}

Package

{
  "type": "Package",
  "details": {
    "weight_in_oz": 320.0,
    "sscc_barcode": "PKG001",
    "carrier_box_code": "86",
    "container_number": 1
  },
  "line_items": [ ],
  "containers": [ ]
}

CasePack

{
  "type": "CasePack",
  "details": {
    "sscc_barcode": "CASE001",
    "container_number": 1
  },
  "order_line_item_id": "TGluZUl0ZW06OTg3Ng==",
  "case_sku": "CASE-SKU-001"
}

UOM Pallet

{
  "type": "UOM Pallet",
  "details": {
    "height": 60.0,
    "length": 48.0,
    "width": 40.0,
    "weight_in_oz": 2400.0,
    "sscc_barcode": "UOMPALLET001",
    "container_number": 2
  },
  "order_line_item_id": "TGluZUl0ZW06OTg3Nw==",
  "case_sku": "PALLET-SKU-001"
}

Line Items

Line items represent individual product units (eaches) packed directly inside a Package or on a Pallet.

{
  "order_line_item_id": "TGluZUl0ZW06MTIzNDU2",
  "quantity": 10
}

Line items can only appear inside a Package or directly on a Pallet. They cannot appear inside a CasePack or UOM Pallet.

Container Numbering

Container numbers are sequential identifiers used for label generation, SSCC-18 codes, packing lists, and ASN transmissions. There are three independent sequences:

Rules:

1. Each sequence must start at 1 and increment by 1 with no gaps or duplicates.
2. Regular pallets and UOM pallets count together. If you have 2 pallets and 1 UOM pallet, their container numbers must be 1, 2, 3.
3. All packages across the entire hierarchy share one sequence. A top-level package and a deeply nested inner box both draw from the same counter. If you have 3 packages total (at any depth), they must be numbered 1, 2, 3.
4. All case packs share one sequence, regardless of which pallet or package they sit inside.

Example with correct numbering:

Pallet (container_number: 1)          ← pallet sequence
├── CasePack (container_number: 1)    ← case pack sequence
├── Package (container_number: 1)     ← package sequence
│   ├── LineItem
│   └── Package (container_number: 2) ← package sequence (continues)
│       └── LineItem
UOM Pallet (container_number: 2)      ← pallet sequence (continues)

One CasePack = One Physical Unit

Each CasePack entry always represents exactly one physical sealed case — one SSCC-18 barcode and one container in ShipHero. This holds regardless of whether the case pack is nested inside a parent container or sits at the top level.

To pack N cases of the same product, send N separate CasePack entries. For example, to pack 3 cases:

{
  "containers": [
    {
      "type": "CasePack",
      "details": { "container_number": 1 },
      "order_line_item_id": "TGluZUl0ZW06MTAwMQ==",
      "case_sku": "CASE-SKU-A"
    },
    {
      "type": "CasePack",
      "details": { "container_number": 2 },
      "order_line_item_id": "TGluZUl0ZW06MTAwMQ==",
      "case_sku": "CASE-SKU-A"
    },
    {
      "type": "CasePack",
      "details": { "container_number": 3 },
      "order_line_item_id": "TGluZUl0ZW06MTAwMQ==",
      "case_sku": "CASE-SKU-A"
    }
  ]
}

Quantity Validation

Every order line item must be accounted for in the packing layout, and the total quantity packed for each must exactly match the ordered quantity. If a line item is omitted entirely or its packed total does not match, the import will be rejected.

The system validates this by summing:

• quantity from all line_items entries referencing that line item ID.
• For CasePack entries: case_multiplier per entry, where the case multiplier is the number of eaches (ordered units) contained in one case, resolved from the product case hierarchy. Each CasePack is one case, so to account for more units add more CasePack entries.
• For UOM Pallet entries: 1 × case_multiplier. UOM Pallets always represent exactly one physical pallet.

All integer quantity fields (quantity on line items, and container_number) must be ≥ 1. Zero, negative, or non-numeric values will be rejected.

Packing rules by order UOM

Current Limitations

The following features are not currently supported by the import:

Packed Outside ShipHero Only

This import is designed for orders packed outside ShipHero’s warehouse workflows. It does not validate against staged inventory (order bin allocations) and bypasses the standard picking flow. Do not use it for orders being packed through the ShipHero warehouse UI.

Lot Tracking

The import does not currently accept or assign lot information. If your account uses lot tracking, the imported packing layout will not have lots associated with line items or case packs. This means:

• Lot-tracked products will not show lot assignments on packed items.
• If lot tracking enforcement is required for your workflow, coordinate with ShipHero support before using this endpoint.

LPN (License Plate Number) Assignment

The import itself does not create or assign LPN identifiers to containers — the imported layout starts without LPNs. They are created later, when you call wholesale_order_mark_as_packed, which also moves inventory out of the staging bin into the containers. LPNs are required for:

• Scanning containers in the warehouse.
• Unpacking and repacking operations.
• Label generation and fulfillment workflows.

Weight Recalculation

Pallet and Package weights are taken as-is from the payload. CasePack and UOM Pallet weights use the submitted override or the linked product case’s configured weight. The system does not recalculate container weights from their contents, so ensure submitted and configured weights are accurate.

Partial Imports and Incremental Updates

The import creates the full packing configuration in a single call. You cannot add containers to an existing configuration or import a partial layout. To modify a previously imported layout, reset the order’s packing configuration and re-import the full layout.

Full Examples

The examples below intentionally mix Public API GIDs, JSON numbers, and numeric strings for order_line_item_id to demonstrate all accepted formats.

Freight Order

A freight order with 4 line items packed across a regular pallet and a UOM pallet:

{
  "containers": [
    {
      "type": "Pallet",
      "details": {
        "weight_in_oz": 1600.0,
        "custom_box_id": "QXZhaWxhYmxlQm94OjEyMzQ1Ng==",
        "sscc_barcode": "PALLET001",
        "container_number": 1
      },
      "line_items": [
        { "order_line_item_id": 1001, "quantity": 10 }
      ],
      "containers": [
        {
          "type": "CasePack",
          "details": {
            "sscc_barcode": "CASE001",
            "container_number": 1
          },
          "order_line_item_id": "1002",
          "case_sku": "CASE-SKU-A"
        },
        {
          "type": "Package",
          "details": {
            "weight_in_oz": 320.0,
            "custom_box_id": "QXZhaWxhYmxlQm94OjY1NDMyMQ==",
            "sscc_barcode": "PKG001",
            "container_number": 1
          },
          "line_items": [
            { "order_line_item_id": "1002", "quantity": 2 }
          ],
          "containers": [
            {
              "type": "Package",
              "details": {
                "height": 8.0,
                "length": 6.0,
                "width": 4.0,
                "weight_in_oz": 80.0,
                "sscc_barcode": "PKG002",
                "container_number": 2
              },
              "line_items": [
                { "order_line_item_id": "TGluZUl0ZW06MTAwMw==", "quantity": 15 }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "UOM Pallet",
      "details": {
        "sscc_barcode": "UOMPALLET001",
        "container_number": 2
      },
      "order_line_item_id": "1004",
      "case_sku": "PALLET-SKU-B"
    }
  ]
}

Numbering breakdown

• Pallet sequence: Pallet → 1, UOM Pallet → 2
• Package sequence: PKG001 → 1, PKG002 → 2
• CasePack sequence: CASE001 → 1

In this example, the regular pallet and PKG001 use dimensions from distinct custom_box_id values, while PKG002 uses its submitted dimensions. The CasePack and UOM Pallet omit dimensions and weight, so those values come from their linked product case configurations.

Courier Order

A courier order with 2 line items — one packed as loose eaches in a box, and one as a standalone case pack. Both Package and CasePack are valid top-level containers for courier orders.

{
  "containers": [
    {
      "type": "Package",
      "details": {
        "weight_in_oz": 320.0,
        "carrier_box_code": "86",
        "sscc_barcode": "PKG001",
        "container_number": 1
      },
      "line_items": [
        { "order_line_item_id": 2001, "quantity": 5 }
      ]
    },
    {
      "type": "CasePack",
      "details": {
        "height": 12.0,
        "length": 10.0,
        "width": 8.0,
        "weight_in_oz": 100.0,
        "sscc_barcode": "CASE001",
        "container_number": 1
      },
      "order_line_item_id": "TGluZUl0ZW06MjAwMg==",
      "case_sku": "CASE-SKU-X"
    }
  ]
}

Numbering breakdown

• Package sequence: PKG001 → 1
• CasePack sequence: CASE001 → 1

The package uses dimensions from carrier_box_code. The CasePack submits all three dimensions and weight_in_oz, so those values override its linked product case configuration. The package and case pack sequences are independent — both start at 1.

Error Responses

The mutation will raise an error with a descriptive message in the following cases: