Shipments

scope: shipments

Shipments represent the movement of goods in and out of warehouses. This page covers the shared read endpoints that work across all shipment types. For creating and managing specific shipment types, see Pick & Pack and Small Parcel (SPD).

When is inventory deducted?

Pick & Pack

Opens cartons, picks individual units, repacks. Per-unit labor fees.

submit→pending→forwarded ← deducted

SPD

Ships full cartons as-is. No opening or repacking.

submit ← deducted→pending→forwarded

Endpoints

GET

/v0/shipments

List all shipments (paginated, filterable by status and type)

GET

/v0/shipments/:shipmentId

Get full details of a single shipment

Shipment Types

Every shipment has a type that determines its workflow, required fields, and available operations.

Outbound

outbound-pickpackDocs →

Customer orders — warehouse opens cartons, picks individual units, repacks and ships to a customer address. Incurs per-unit labor fees.

outbound-spdDocs →

Small parcel delivery — ships full cartons as-is (no opening or repacking). Attach shipping labels and ship to Amazon FBA or similar.

outbound-ltl

Less-than-truckload outbound freight shipments.

Inbound

inbound-container

Receiving shipping containers into the warehouse.

inbound-spd

Small parcel inbound deliveries.

inbound-ltl

Less-than-truckload inbound freight shipments.

Status Lifecycle

All shipment types follow the same status progression. The API exposes normalized status names regardless of the internal representation.

Outbound (SPD, Pick & Pack, LTL)

draft→pending→processing→forwarded

Inbound (Container, SPD, LTL)

draft→pending→confirmed→processing→received

Cancellation & Rejection

pending→pending_cancel→cancelled

pending→rejected(inbound only)

Status	Description	Mutable?
`draft`	Initial state. Items, labels, notes, and addresses can be modified.	Yes
`pending`	Submitted and awaiting warehouse action. For outbound SPD, inventory is deducted at this stage.	No
`confirmed`	Inbound only. The warehouse has approved the inbound shipment and is ready to receive it.	No
`processing`	Warehouse is actively working on the shipment (picking, packing, labeling, or receiving).	No
`received`	Inbound only. Goods have been received into the warehouse. Terminal state.	No
`forwarded`	Outbound only. Shipped out. Terminal state. For Pick & Pack, inventory is deducted at this stage.	No
`rejected`	Inbound only. The warehouse has rejected the inbound shipment. Terminal state.	No
`pending_cancel`	Cancellation requested. Waiting for warehouse confirmation.	No
`cancelled`	Cancelled by the warehouse. Inventory restored if applicable. Terminal state.	No

Draft is the only mutable state

Once a shipment is submitted (moves past draft), its items, labels, and configuration can no longer be changed. Make sure everything is correct before submitting.

List Shipments

Returns a paginated list of all shipments across all types for your organization. Use the query parameters to filter by status or type.

Query Parameters

Parameter	Type	Description
`status`	enum	Filter by status: draft, pending, confirmed, processing, received, forwarded, rejected, pending_cancel, cancelled
`type`	enum	Filter by type: outbound-pickpack, outbound-spd, outbound-ltl, inbound-container, inbound-spd, inbound-ltl
`skip`	number	Number of records to skip (default: 0)
`take`	number	Number of records to return (default: 10, max: 50)

curl

curl "https://api.3plguys.com/v0/shipments?type=outbound-spd&status=pending" \
  -H "Authorization: Bearer <token>"

Node.js

const res = await fetch(
  "https://api.3plguys.com/v0/shipments?type=outbound-spd&status=pending",
  { headers: { Authorization: `Bearer ${token}` } }
);
const shipments = await res.json();

Python

res = httpx.get(
    "https://api.3plguys.com/v0/shipments",
    params={"type": "outbound-spd", "status": "pending"},
    headers={"Authorization": f"Bearer {token}"},
)
shipments = res.json()

Response

[
  {
    "id": "22",
    "status": "pending",
    "type": "outbound-spd",
    "warehouse": {
      "id": "1",
      "name": "Main Warehouse"
    },
    "notes": "FBA shipment for Q1 restock",
    "cartons": [
      {
        "id": "1",
        "name": "10-Pack Case",
        "quantity": 5,
        "contents": [
          {
            "productId": "1",
            "sku": "ABC123",
            "productName": "Egg Shells",
            "quantity": 10
          }
        ]
      }
    ],
    "totalCartonQuantity": 5,
    "totalProductQuantity": 50,
    "invoiceId": null,
    "workflowId": null,
    "createdAt": "2026-02-26T13:22:08.514Z",
    "updatedAt": "2026-02-26T13:22:22.000Z"
  }
]

Get Shipment

Retrieve the full details of a single shipment by its ID. Returns 404 if the shipment does not exist or belongs to another organization.

GET /v0/shipments/22

{
  "id": "22",
  "status": "pending",
  "type": "outbound-spd",
  "warehouse": {
    "id": "1",
    "name": "Main Warehouse"
  },
  "notes": "FBA shipment for Q1 restock",
  "cartons": [
    {
      "id": "1",
      "name": "10-Pack Case",
      "quantity": 5,
      "contents": [
        {
          "productId": "1",
          "sku": "ABC123",
          "productName": "Egg Shells",
          "quantity": 10
        }
      ]
    },
    {
      "id": "2",
      "name": "24-Pack Case",
      "quantity": 3,
      "contents": [
        {
          "productId": "1",
          "sku": "ABC123",
          "productName": "Egg Shells",
          "quantity": 24
        }
      ]
    }
  ],
  "totalCartonQuantity": 8,
  "totalProductQuantity": 122,
  "invoiceId": "5",
  "workflowId": null,
  "createdAt": "2026-02-26T13:22:08.514Z",
  "updatedAt": "2026-02-26T13:22:22.000Z"
}

Response Fields

Parameter	Type	Description
`id`*	string	Unique shipment ID
`status`*	enum	Current status (see lifecycle above)
`type`*	enum	Shipment type (see types above)
`warehouse`*	object	The warehouse handling this shipment
`warehouse.id`*	string	Warehouse ID
`warehouse.name`*	string	Warehouse name
`notes`	string	Free-text notes attached to the shipment
`cartons`	array	Cartons included in this shipment (may be empty for drafts)
`cartons[].id`	string	Carton type ID
`cartons[].name`	string	Carton type name
`cartons[].quantity`	number	Number of cartons of this type
`cartons[].contents`	array	Products inside this carton type
`cartons[].contents[].productId`	string	Product ID
`cartons[].contents[].sku`	string	Product SKU
`cartons[].contents[].productName`	string	Product name
`cartons[].contents[].quantity`	number	Units of this product per carton
`totalCartonQuantity`	number	Total number of cartons across all carton types
`totalProductQuantity`	number	Total number of product units across all cartons
`invoiceId`	string \| null	Invoice ID if the shipment has been invoiced, null otherwise
`workflowId`	string \| null	Workflow ID linking grouped shipments, null if not part of a workflow
`createdAt`*	ISO 8601	Timestamp when the shipment was created
`updatedAt`*	ISO 8601	Timestamp of the last update

Error Responses

404Shipment not found

The shipment ID does not exist or does not belong to your organization.

Creating Shipments

The endpoints above are read-only. To create and manage shipments, use the type-specific endpoints:

Pick & Pack

Ship individual product units. Warehouse opens cartons, picks units, repacks, and ships to a customer address.

createdeleteitemsaddressnotessubmitcancel

Small Parcel (SPD)

Ship full cartons as-is. Select carton types and counts, upload shipping labels, and submit for FBA-style fulfillment.

createdeleteitemslabelsattachmentsnotessubmitcancel

Environments

Pick & Pack