Wholesale Orders Packed Outside ShipHero

This complete flow leverages our Public API to enable third-party systems to fully automate B2B fulfillment, drastically reducing manual operational time while keeping all ShipHero data perfectly accurate and in real-time sync.

When handling Wholesale Orders that are packed outside ShipHero, the Public API allows you to manage the entire flow — from creation to fulfillment — programmatically, without touching the ShipHero UI.

Below you’ll find each step in order, exactly as tested.

Statuses and transitions

Before diving into the flow, it’s important to understand how wholesale order statuses work in ShipHero. Each wholesale order goes through a series of well-defined states —from creation and inventory reservation to final fulfillment— that reflect its progress through warehouse operations. Transitions between these states are governed by strict business rules: inventory must be allocated before picking starts, packing can only occur after picking completes, and Fulfilled marks the point of no return when inventory is deducted and stores are notified.

1. Create the Wholesale Order

First, create a wholesale order.
You must include a valid SKU that already exists in your account.

mutation {
  wholesale_order_create(
    data: {
      partner_order_id: "WHOLESALE-1004"
      shop_name: "My B2B Channel"
      order_number: "OR-04"
      tags: ["wholesale"]
      shipping_address: {
        first_name: "Customer"
        last_name: "Wholesale"
        address1: "123 Street"
        city: "Santa Fe"
        state: "SF"
        zip: "3000"
        country: "AR"
      }
      line_items: [
        {
          sku: "WHITE-TSHIRT-M"
          quantity: 12
          price: "15.00"
          partner_line_item_id: "LINE-WHITE-TSHIRT-M-04"
        }
      ]
      allow_partial: false
      picking_flow: DESKTOP
    }
  ) {
    request_id
    wholesale_order {
      id
      picking_flow
      order {
        id
        order_number    
        fulfillment_status
      }
    }
  }
}

In this example we’re using manual picking (picking_flow: DESKTOP).

query {
  wholesale_order(order_id: "T3JkZXI6Njg2MzAwMDEz") {
    data { id status picking_flow shipping_option }
  }
}

mutation { wholesale_order_update_picking_flow(
  data: { order_id: "T3JkZXI6Njg2MzAwMDEz", picking_flow: DESKTOP }
) { request_id wholesale_order { id picking_flow } } }

mutation { wholesale_order_update(
  data: { order_id: "T3JkZXI6Njg2MzAwMDEz", shipping_option: COURIER }
) { request_id wholesale_order { id shipping_option } } }

2. Get Available Staging Locations

To see which staging bins are available, use:

query {
  wholesale_staging_location_candidates(warehouse_id: "V2FyZWhvdXNlOjE1MDU2") {
    request_id
    data {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

Example result:

{
  "data": {
    "wholesale_staging_location_candidates": {
      "data": {
        "edges": [
          { "node": { "id": "QmluOjI0MTYxMjY5", "name": "EAD_II_11" } }
        ]
      }
    }
  }
}

3. Assign a Staging Location

Assign one of the free locations from the list:

mutation {
  wholesale_order_update_staging_location(
    data: {
      order_id: "T3JkZXI6Njg2MzAwMDEz"   # new order id for OR-04
      staging_location_id: "QmluOjI0MTYxMjY5" # EAD_II_11
    }
  ) {
    request_id
    wholesale_order {
      id
      staging_location_id
      status
      order { id order_number }
    }
  }
}

4. Allocate Inventory for Picking

Now allocate inventory for this order.

mutation {
  wholesale_order_auto_allocate_for_picking(
    data: {
      order_id: "T3JkZXI6Njg2MzAwMDEz"
      prioritized_location_ids: ["V2FyZWhvdXNlOjE1MDU2"]
    }
  ) {
    request_id
    complexity
    line_items {
      line_item_id
      quantity
      product { sku }
      allocations {
        __typename
      }
    }
  }
}

A successful allocation will show "__typename": "AllocatedAllocationType".

5. Mark as Ready to Pick

After allocation:

mutation {
  wholesale_set_as_ready_to_pick(
    data: { order_id: "T3JkZXI6Njg2MzAwMDEz" }
  ) {
    request_id
    ok
  }
}

The order now moves from default → ready_to_pick.

6. Print the Manual Picking Sheet

Generate a PDF with manual picking instructions:

mutation {
  wholesale_order_print_manual_picking_sheet(
    data: { order_id: "T3JkZXI6Njg2MzAwMDEz" }
  ) {
    request_id
    picking_sheet_url
  }
}

Response example:

{
  "data": {
    "wholesale_order_print_manual_picking_sheet": {
      "picking_sheet_url": "https://d2s9s6xmfnfu1v.cloudfront.net/wholesale/picking_slips/2025-10-10/picking_slip_686300013.pdf"
    }
  }
}

This PDF can be printed and handed to warehouse staff for manual picking.

7. Transfer Picks to Staging

After picking is done, move items into staging.

mutation {
  wholesale_order_transfer_picks_to_staging(
    data: { order_id: "T3JkZXI6Njg2MzAwMDEz" }
  ) {
    request_id
    wholesale_order {
      id
      status
      staging_location_id
      order { id order_number }
    }
  }
}

Status should now read packing.

8. Inspect the Staged Manifest (Optional)

Once picks are in staging, you can query the staged inventory manifest to see exactly what is sitting in the staging location for this order, broken down per line item by SKU, lot, container type (eaches vs cases), quantity, and bin. This is especially useful when your packing is driven by an external system: it tells you which lots were allocated, what’s available to pack, and gives you the IDs you need to build the wholesale_order_import_packing_layout payload in the next step.

The manifest is exposed as a staged_inventory field on each wholesale_line_item:

query {
  wholesale_order(order_id: "T3JkZXI6Njg2MzAwMDEz") {
    request_id
    data {
      id
      status
      wholesale_line_items {
        edges {
          node {
            id
            staged_inventory {
              line_item_id
              sku
              quantity
              case_type
              lot_id
              lot_name
              lot_expiration_date
              location_id
              location_name
            }
          }
        }
      }
    }
  }
}

Example response:

{
  "data": {
    "wholesale_order": {
      "data": {
        "wholesale_line_items": {
          "edges": [
            {
              "node": {
                "id": "V2hvbGVzYWxlTGluZUl0ZW06MTIz",
                "staged_inventory": [
                  {
                    "line_item_id": "TGluZUl0ZW06OTg3Ng==",
                    "sku": "WHITE-TSHIRT-M",
                    "quantity": 12,
                    "case_type": null,
                    "lot_id": "TG90OjQzMg==",
                    "lot_name": "LOT-2026-04",
                    "lot_expiration_date": "2027-04-01T00:00:00",
                    "location_id": "QmluOjI0MTYxMjY5",
                    "location_name": "EAD_II_11"
                  }
                ]
              }
            }
          ]
        }
      }
    }
  }
}

Notes on the response:

• Only items still pending packing are returned. Once a row is fully packed, it disappears from the manifest — so an empty list for a line item means everything staged has already been packed.
• case_type is null for loose eaches and set (for example, CASE, INNER_CASE, MASTER_CASE) when the staged unit is a product case.
• lot_id, lot_name, and lot_expiration_date are only populated for lot-tracked products.
• line_item_id is the order line item GID. You can pass this value directly into the order_line_item_id field of the packing_data JSON in step 9 — no translation needed.

9. Import Packing Layout (Optional)

If your packing is managed by an external system and you want to reflect the full container structure (pallets, packages, case packs, and line items) in ShipHero before fulfilling, you can import the packing layout at this point.

The order must be in packing status (after step 7) and must not have an existing packing configuration.

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

Variables:

{
  "data": {
    "order_id": "T3JkZXI6Njg2MzAwMDEz",
    "packing_data": {
      "containers": [
        {
          "type": "Pallet",
          "details": {
            "weight_in_oz": 1600.0,
            "custom_box_id": "QXZhaWxhYmxlQm94OjEyMzQ1Ng==",
            "container_number": 1
          },
          "line_items": [
            {
              "order_line_item_id": "TGluZUl0ZW06OTg3Ng==",
              "quantity": 12
            }
          ]
        }
      ]
    }
  }
}

This example assumes the order uses the FREIGHT shipping option. For a COURIER order, use a top-level Package instead and follow the container rules in the detailed flow.

For the full JSON schema, container types, numbering rules, and validation details, see Import Packing Layout.

10. Mark as Packed (Optional)

Only mandatory if you completed step 9. After the packing layout is imported, this step advances the order from packing to packed and lets ShipHero finish processing the imported layout so the order is ready for the downstream label and BOL flow:

mutation MarkAsPacked {
  wholesale_order_mark_as_packed(
    data: { order_id: "T3JkZXI6Njg2MzAwMDEz" }
  ) {
    request_id
    complexity
    ok
  }
}

Expected response:

{
  "data": {
    "wholesale_order_mark_as_packed": {
      "ok": true
    }
  }
}

What happens under the hood:

• LPNs are created for the imported layout. A layout imported in step 9 starts without License Plate Numbers (LPNs). At mark_as_packed time, ShipHero creates an LPN for each container (pallet, package, case pack) that doesn’t already have one, and moves the corresponding inventory out of the staging bin and into those containers.
• SSCC-18 barcodes are seeded for trading partners that require GS1 labeling, so the later label-generation step can render them onto the GS1 labels. If you already provided sscc_barcode values when importing the packing layout in step 9, those are preserved — ShipHero only fills in barcodes for containers that don’t have one.

ok returns true when the order transitions to packed. If allocated items are still unpacked, ok is false and the order stays in packing — resolve the remaining items and call the mutation again.

11. Generate Labels (Optional)

After the order is packed (step 10), you can have ShipHero generate the shipping labels — including GS1/carton labels for trading partners that require them — instead of printing your own externally. Label generation runs asynchronously:

mutation GenerateLabels {
  wholesale_order_generate_labels(
    data: {
      order_id: "T3JkZXI6Njg2MzAwMDEz"
      generate_carton_labels: true
    }
  ) {
    request_id
    complexity
    wholesale_order {
      id
      status
    }
  }
}

Because generation is asynchronous, the mutation kicks off the work and transitions the order to generating_labels. Poll the wholesale order status until it becomes:

• ready_to_print — labels generated successfully; continue to step 12.
• label_error — generation failed; inspect the order’s status_message, fix the cause, and retry.

query {
  wholesale_order(order_id: "T3JkZXI6Njg2MzAwMDEz") {
    request_id
    data {
      id
      status
      status_message
    }
  }
}

12. Print Labels (Optional)

Once the order reaches ready_to_print (step 11), retrieve the shipping labels PDF. This marks the order’s labels as printed and advances it toward fulfillment:

mutation PrintLabels {
  wholesale_order_print_labels(
    data: { order_id: "T3JkZXI6Njg2MzAwMDEz" }
  ) {
    request_id
    complexity
    labels_url
  }
}

Expected response:

{
  "data": {
    "wholesale_order_print_labels": {
      "labels_url": "https://d2s9s6xmfnfu1v.cloudfront.net/wholesale/labels/686300013/labels.pdf"
    }
  }
}

Behavior worth knowing:

• labels_url is the URL of the shipping labels PDF. It can be null if the order is printable but the PDF isn’t available yet.
• The order must be in ready_to_print, warehouse_completed, or fulfilled status. Once every package has a printed label, the order advances to warehouse_completed.

13. Fulfill the Order

Finally, mark the order as fulfilled. The value of is_packed_externally depends on where the order was packed:

• Packed externally — you packed the order outside ShipHero and skipped the packing layout import (steps 9–12). Use is_packed_externally: true. This requires the order to still be in packing status, with no ShipHero-generated shipping labels and an empty packing configuration.
• Packed in ShipHero — you imported the packing layout and marked it as packed (steps 9–10), optionally generating and printing labels through ShipHero (steps 11–12), so the order has a packing configuration and is no longer in packing status. Use is_packed_externally: false.

mutation {
  wholesale_order_fulfill(
    data: {
      order_id: "T3JkZXI6Njg2MzAwMDEz"
      is_packed_externally: true   # or false if you packed in ShipHero (steps 9–12)
    }
  ) {
    request_id
    wholesale_order {
      id
      status
    }
  }
}

Expected response:

{
  "data": {
    "wholesale_order_fulfill": {
      "wholesale_order": {
        "status": "fulfilled"
      }
    }
  }
}

The order is now fully fulfilled, just like an internal ShipHero order.

14. Verify the Order Status

Check the final state:

query {
  wholesale_order(order_id: "T3JkZXI6Njg2MzAwMDEz") {
    request_id
    data {
      id
      status
      picking_flow
      staging_location_id
      order {
        order_number
        fulfillment_status
      }
    }
  }
}

Summary Table