Receiving

Overview

A Warehouse Receiving Order (WRO) is how ShipBob manages inbound shipments into their fulfillment centers. Some other solutions call this an “ASN” (Advanced Ship Notice).

This guide will walk you through building an integration to send inventory to ShipBob and sync it back to your system.

How It Works

Here’s the flow of creating and tracking a Warehouse Receiving Order:

Step 1: Check if Products Exist in ShipBob

Before creating a WRO, every product needs an inventory_id from ShipBob.

Check if a product exists:

1
GET https://api.shipbob.com/2026-01/product?sku=light-roast

If the product doesn’t exist, create it first:

1
POST https://api.shipbob.com/2026-01/product
2
3
{
4
  "name": "Light Roast Coffee",
5
  "type_id": 1,
6
  "variants": [
7
    {
8
      "name": "Light Roast Coffee",
9
      "sku": "light-roast",
10
      "packaging_requirement_id": 1,
11
      "packaging_material_type_id": 1,
12
      "barcode": "06547321109",
13
      "customs": {
14
        "country_code_of_origin": "US",
15
        "hs_tariff_code": "6103.22.00",
16
        "value": "10",
17
        "description": "coffee"
18
      }
19
    }
20
  ]
21
}

Step 2: Create a WRO

Once you have your inventory_id values, create the WRO:

1
POST https://api.shipbob.com/2026-01/receiving

Example request (sending packages):

1
{
2
  "fulfillment_center": {
3
    "id": 10
4
  },
5
  "package_type": "Package",
6
  "box_packaging_type": "EverythingInOneBox",
7
  "expected_arrival_date": "2025-01-15",
8
  "purchase_order_number": "PO-2026-001",
9
  "boxes": [
10
    {
11
      "tracking_number": "1Z999AA10123456784",
12
      "box_items": [
13
        {
14
          "inventory_id": 12345678, // get the inventory_id by making request to GET Products /2026-01/product?sku=light-roast
15
          "quantity": 50
16
        }
17
      ]
18
    }
19
  ]
20
}

What you’ll get back:

1
{
2
  "id": 987654,
3
  "status": "Awaiting",
4
  "package_type": "Package",
5
  "box_packaging_type": "EverythingInOneBox",
6
  "expected_arrival_date": "2025-01-15T00:00:00+00:00",
7
  "purchase_order_number": "PO-2026-001",
8
  "box_labels_uri": "/2026-01/receiving/987654/labels"
9
  // ... additional fields
10
}

Package types:

• Package - For boxes (max 50 boxes per request)
• Pallet - For palletized freight shipments (each pallet is a separate box)
• FloorLoadedContainer - For container shipments (entire container as one box)

Creating WROs with Lot Items

If you’re sending lot-tracked items (products with expiration dates or batch numbers), you must include lot_date and lot_number for each item in your WRO.

Example request with lot items:

1
POST https://api.shipbob.com/2026-01/receiving
2
3
{
4
  "fulfillment_center": { "id": 8 },
5
  "package_type": "Package",
6
  "box_packaging_type": "EverythingInOneBox",
7
  "expected_arrival_date": "2025-12-20T00:00:00Z",
8
  "purchase_order_number": "PO-LOT-001",
9
  "boxes": [
10
    {
11
      "tracking_number": "1Z999AA10123456784",
12
      "box_items": [
13
        {
14
          "inventory_id": 12345678,
15
          "quantity": 50,
16
          "lot_number": "2222",
17
          "lot_date": "2025-06-15T00:00:00Z"
18
        }
19
      ]
20
    }
21
  ]
22
}

Key fields for lot items:

Multiple lots in one box:

You can include multiple lots of the same product or different products in a single box:

1
{
2
  "boxes": [
3
    {
4
      "tracking_number": "1Z999AA10123456784",
5
      "box_items": [
6
        {
7
          "inventory_id": 12345678,
8
          "quantity": 50,
9
          "lot_number": "LOT-2222",
10
          "lot_date": "2025-06-15T00:00:00Z"
11
        },
12
        {
13
          "inventory_id": 12345678,
14
          "quantity": 30,
15
          "lot_number": "LOT-3333",
16
          "lot_date": "2025-08-20T00:00:00Z"
17
        },
18
        {
19
          "inventory_id": 98765432,
20
          "quantity": 100,
21
          "lot_number": "BATCH-A1",
22
          "lot_date": "2026-01-10T00:00:00Z"
23
        }
24
      ]
25
    }
26
  ]
27
}

Step 3: Generate Box Labels (Optional)

Print box labels to help the warehouse identify your shipment:

1
GET https://api.shipbob.com/2026-01/receiving/{wro_id}/box-labels

This returns a PDF with labels for each box/pallet. Print and attach them to your shipment before sending.

Step 4: Poll for Completed WROs

Set up a recurring job (every 15-30 minutes) to check for completed WROs that need to be synced.

Check for completed WROs:

1
GET https://api.shipbob.com/2026-01/receiving?statuses=Completed&ExternalSync=false

This returns all WROs that are:

• Completed - The warehouse has finished processing them
• Not synced - You haven’t updated your system yet (ExternalSync=false)

Here’s what to do with each completed WRO:

1. Get the inventory quantities from the WRO
2. Update your system with the new inventory levels
3. Mark the WRO as synced so you don’t process it again

Example code:

1
// Run this every 15-30 minutes
2
async function checkForCompletedWROs() {
3
  // 1. Get completed WROs that haven't been synced
4
  const response = await fetch(
5
    'https://api.shipbob.com/2026-01/receiving?statuses=Completed&ExternalSync=false',
6
    {
7
      headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
8
    }
9
  );
10
  
11
  const wros = await response.json();
12
  
13
  // 2. Process each WRO
14
  for (const wro of wros) {
15
    // Get the inventory quantities
16
    wro.boxes.forEach(box => {
17
      box.inventory.forEach(item => {
18
        // Update your system with item.stowed_quantity
19
        console.log(`Product ${item.inventory_id}: +${item.stowed_quantity} units`);
20
      });
21
    });
22
    
23
    // 3. Mark as synced
24
    await fetch(
25
      `https://api.shipbob.com/2026-01/receiving:setExternalSync`,
26
      {
27
        method: 'POST',
28
        headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
29
        body: JSON.stringify({ "ids": [987654], "is_external_sync": true })
30
      }
31
    );
32
  }
33
}

Step 5: Mark WRO as Synced

After updating your inventory system, mark the WRO as synced to prevent duplicate processing:

1
POST https://api.shipbob.com/2026-01/receiving:setExternalSync
2
3
{
4
  "ids": [987654],
5
  "is_external_sync": true
6
}

This endpoint accepts an array of WRO IDs, allowing you to mark multiple WROs as synced in a single request.

Advanced: Track Individual Boxes

Want to see details for each box? Use this endpoint:

1
GET https://api.shipbob.com/2026-01/receiving/{wro_id}/boxes

This shows you the status and quantities for each box, which would enable you to do partial receiving.

Understanding the Inventory Quantities

When you sync a completed WRO, you’ll see three quantity fields:

Example:

1
{
2
  "inventory_id": 12345678,
3
  "sku": "light-roast",
4
  "expected_quantity": 50,    // You sent 50 units
5
  "received_quantity": 48,    // Only 48 arrived
6
  "stowed_quantity": 48       // 48 added to inventory
7
}

Important Fields

package_type - Determines how your shipment is configured. Choose based on your shipping method:

• Package - Standard boxes shipped via carrier (max 50 per request)
• Pallet - Palletized freight shipments (each pallet = one box)
• FloorLoadedContainer - Full container shipments (entire container = one box)

expected_arrival_date - The date your shipment is expected to arrive at the fulfillment center. Must be set to a future date - using today’s date or a past date will result in an error.

purchase_order_number - Your internal PO number or shipment identifier. Use a unique value for each WRO to simplify tracking and reconciliation.

tracking_number - The carrier tracking number for each box or pallet. This enables the warehouse to scan and verify your shipment upon arrival.

is_external_sync - A boolean flag that tracks whether you’ve synced the WRO data back to your system:

• Default value: false when the WRO is created
• Query unsynced WROs: Use ExternalSync=false to find WROs that need processing
• Mark as synced: Set to true after updating your inventory system
• Purpose: Prevents duplicate processing of the same WRO

To mark one or more WROs as synced, use the batch endpoint:

1
POST https://api.shipbob.com/2026-01/receiving:setExternalSync
2
3
{
4
  "ids": [987654],
5
  "is_external_sync": true
6
}

WRO Status Flow

Your WRO goes through these stages:

For complete status reference including hub-related statuses, see the Status Reference documentation.

Common Issues

Tips

• Poll every 15-30 minutes - Receiving can take hours or a few days depending on warehouse volume
• Use unique PO numbers - Makes tracking and reconciliation easier
• Always verify inventory_id exists - Prevents WRO creation failures
• API rate limit - 150 requests per minute
• Consider time zones - Dates are in UTC; convert appropriately

Related Resources

• Create Warehouse Receiving Order API
• ShipBob Receiving Best Practices