API Docs

Inbound Receiving & Container Shipments

Inbound shipments track goods arriving at your warehouse — whether full shipping containers or small parcel deliveries. This guide covers listing, filtering, and monitoring inbound shipments via the API.

Required Scope

Your OAuth application needs the shipments scope to access these endpoints.

Inbound Shipment Types

Inbound Lifecycle
Draft
Shipment created
Pending
Shipment expected
Processing
Being received
Forwarded
Received & stocked

The API supports two inbound shipment types:

TypeCodeDescription
Containerinbound-containerFull shipping containers arriving at the warehouse — typically from overseas manufacturers via freight
Small Parcelinbound-spdIndividual packages arriving via parcel carriers (UPS, FedEx, USPS)

Listing Inbound Shipments

Use the shared shipments endpoint with type filters to list inbound shipments:

GET
/v0/shipments

List all shipments (filterable by type and status)

curl "https://api.3plguys.com/v0/shipments?type=inbound-container&take=50" \
  -H "Authorization: Bearer YOUR_TOKEN"
// Fetch both inbound types
const [containers, parcels] = await Promise.all([
  fetch(
    "https://api.3plguys.com/v0/shipments?type=inbound-container&take=50",
    { headers: { Authorization: `Bearer ${token}` } }
  ).then(r => r.json()),
  fetch(
    "https://api.3plguys.com/v0/shipments?type=inbound-spd&take=50",
    { headers: { Authorization: `Bearer ${token}` } }
  ).then(r => r.json()),
]);


console.log(`${containers.length} containers, ${parcels.length} parcels inbound`);
res = httpx.get(
    "https://api.3plguys.com/v0/shipments",
    params={"type": "inbound-container", "take": 50},
    headers={"Authorization": f"Bearer {token}"},
)
containers = res.json()

Filtering by Status

Track shipments at each stage of the receiving process:

curl "https://api.3plguys.com/v0/shipments?type=inbound-container&status=pending&take=50" \
  -H "Authorization: Bearer YOUR_TOKEN"
async function getInboundByStatus(status) {
  const res = await fetch(
    `https://api.3plguys.com/v0/shipments?type=inbound-container&status=${status}&take=50`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return res.json();
}


const pending = await getInboundByStatus("pending");
const processing = await getInboundByStatus("processing");
const received = await getInboundByStatus("forwarded");

Getting Shipment Details

Fetch full details for a specific inbound shipment:

GET
/v0/shipments/:id

Get full details of a single shipment

curl "https://api.3plguys.com/v0/shipments/42" \
  -H "Authorization: Bearer YOUR_TOKEN"
const shipment = await fetch(
  `https://api.3plguys.com/v0/shipments/${shipmentId}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then(r => r.json());


console.log(`Type: ${shipment.type}`);
console.log(`Status: ${shipment.status}`);
console.log(`Warehouse: ${shipment.warehouse.name}`);
console.log(`Cartons: ${shipment.cartons?.length ?? 0}`);
{
  "id": "42",
  "status": "pending",
  "type": "inbound-container",
  "warehouse": { "id": "1", "name": "Main Warehouse" },
  "notes": "Container #MSKU1234567 — 40ft HC",
  "cartons": [
    {
      "id": "5",
      "name": "24-Pack Case",
      "quantity": 200,
      "contents": [
        { "productId": "1", "sku": "ABC123", "productName": "Egg Shells", "quantity": 24 }
      ]
    }
  ],
  "totalCartonQuantity": 200,
  "totalProductQuantity": 4800,
  "invoiceId": "5",
  "createdAt": "2026-03-01T08:00:00.000Z",
  "updatedAt": "2026-03-01T08:00:00.000Z"
}

Tracking Receiving Progress

Poll inbound shipments to detect when they've been received and stocked:

const BASE = "https://api.3plguys.com/v0";


async function trackInboundShipments(token) {
  // Get all inbound container shipments
  const shipments = await fetch(
    `${BASE}/shipments?type=inbound-container&take=50`,
    { headers: { Authorization: `Bearer ${token}` } }
  ).then(r => r.json());


  for (const shipment of shipments) {
    console.log(
      `Shipment #${shipment.id}: ${shipment.status} at ${shipment.warehouse.name}`
    );


    if (shipment.status === "forwarded") {
      // Inventory has been added — trigger downstream sync
      await onShipmentReceived(shipment);
    }
  }


  // Return only shipments still in progress
  return shipments.filter(s => !["forwarded", "cancelled"].includes(s.status));
}

Inventory Replenishment Monitoring

Combine inbound shipment tracking with stock level monitoring to build a complete replenishment pipeline:

const BASE = "https://api.3plguys.com/v0";
const auth = { Authorization: `Bearer ${token}` };


const REORDER_THRESHOLD = 100; // Set your own reorder threshold


async function checkReplenishment() {
  // 1. Get current stock levels by product
  const products = await fetch(
    `${BASE}/inventory/products/breakdown?take=50`,
    { headers: auth }
  ).then(r => r.json());


  // 2. Find low-stock products (quantity is the total units across all warehouses)
  const lowStock = products.filter(p => !p.archived && p.quantity < REORDER_THRESHOLD);


  // 3. Check if replenishment is already inbound
  const inbound = await fetch(
    `${BASE}/shipments?type=inbound-container&status=pending&take=50`,
    { headers: auth }
  ).then(r => r.json());


  for (const product of lowStock) {
    const hasInbound = inbound.some(s =>
      s.cartons?.some(c =>
        c.contents.some(item => item.productId === product.id)
      )
    );


    if (hasInbound) {
      console.log(`${product.sku}: Low stock but replenishment inbound`);
    } else {
      console.log(`${product.sku}: Low stock — needs reorder!`);
      await sendReorderAlert(product);
    }
  }
}


// Run daily
setInterval(checkReplenishment, 24 * 60 * 60 * 1000);

Pagination for Large Volumes

If you receive many inbound shipments, paginate through the results:

async function getAllInboundShipments(token) {
  const all = [];
  let skip = 0;
  const take = 50; // Maximum allowed per request


  while (true) {
    const batch = await fetch(
      `${BASE}/shipments?type=inbound-container&take=${take}&skip=${skip}`,
      { headers: { Authorization: `Bearer ${token}` } }
    ).then(r => r.json());


    all.push(...batch);
    if (batch.length < take) break;
    skip += take;
  }


  return all;
}

Inventory impact

When an inbound shipment reaches forwarded status, the warehouse has received and stocked the goods. Stock levels are updated automatically — poll the stock levels endpoint to see the updated quantities.

Next Steps