Skip to content
Guides
/
/
Receive Products
Last updated

Receive Purchase Order Products

When products arrive from your supplier, use the receive endpoint to record the receipt, update inventory levels, and track quality issues. This endpoint automatically updates your inventory and manages purchase order status.

Receive Products

Use the POST method with /v2/purchase_orders/{purchase_order_id}/receives to record product receipts from a purchase order.

Path Parameters

ParameterTypeDescription
purchase_order_idstringThe unique identifier of the purchase order being received

Request Body Properties

PropertyTypeDescription
product_receivesarrayArray of products being received (required, minimum 1 product)

Product Receive Properties

Each product in the product_receives array requires:

PropertyTypeRequiredDescription
inventory_location_idstringRequiredLocation where the inventory is being received
received_quantityintegerOptionalQuantity actually received (minimum: 1). At least one of received_quantity or rejected_quantity must be provided and greater than 0.
skustringRequiredStock Keeping Unit identifier
rejected_quantityintegerOptionalQuantity rejected due to quality issues (minimum: 1). At least one of received_quantity or rejected_quantity must be provided and greater than 0.
lotstringOptionalLot number for tracking batches
expiration_datestring (date-time)OptionalExpiration date for perishable items (ISO 8601 format)

Automatic Updates

When you receive products, ShipStation automatically:

  1. Updates Inventory: Adds received_quantity to the specified inventory_location_id
  2. Updates Purchase Order Status:
    • First partial receive: open → receiving
    • All products fully received: open → received or receiving → received
  3. Records Receive History: Tracks what was received, when, and where

Example Request & Response

POST /v2/purchase_orders/{purchase_order_id}/receives

curl -i -X POST \
  https://api.shipstation.com/v2/purchase_orders/se-234/receives \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "product_receives": [
      {
        "sku": "WIDGET-001",
        "inventory_location_id": "se-12345",
        "received_quantity": 95,
        "rejected_quantity": 5,
        "lot": "LOT-2025-001",
        "expiration_date": "2026-01-01T00:00:00Z"
      }
    ]
  }'

Receiving Scenarios

Complete Receipt

Receive all ordered quantity in one shipment:

{
  "product_receives": [
    {
      "sku": "WIDGET-001",
      "inventory_location_id": "se-12345",
      "received_quantity": 100
    }
  ]
}

Partial Receipt

Receive part of an order (remaining quantity can be received later):

{
  "product_receives": [
    {
      "sku": "WIDGET-001",
      "inventory_location_id": "se-12345",
      "received_quantity": 60
    }
  ]
}

After receiving 60 of 100 units, the purchase order status changes to receiving. You can make additional receive calls later for the remaining 40 units.

Receipt with Rejections

Record damaged or rejected items:

{
  "product_receives": [
    {
      "sku": "WIDGET-001",
      "inventory_location_id": "se-12345",
      "received_quantity": 95,
      "rejected_quantity": 5
    }
  ]
}

The inventory will be increased by 95 units (only the received_quantity). The 5 rejected units are not added to inventory but are tracked.

Receipt with Lot Tracking

Track lot numbers and expiration dates:

{
  "product_receives": [
    {
      "sku": "WIDGET-001",
      "inventory_location_id": "se-12345",
      "received_quantity": 100,
      "lot": "LOT-2025-001",
      "expiration_date": "2026-01-01T00:00:00Z"
    }
  ]
}

Multiple Products

Receive multiple products from the same purchase order:

{
  "product_receives": [
    {
      "sku": "WIDGET-001",
      "inventory_location_id": "se-12345",
      "received_quantity": 100
    },
    {
      "sku": "GADGET-002",
      "inventory_location_id": "se-12345",
      "received_quantity": 50
    }
  ]
}

Split to Multiple Locations

Receive the same product into different warehouse locations:

{
  "product_receives": [
    {
      "sku": "WIDGET-001",
      "inventory_location_id": "se-12345",
      "received_quantity": 60
    },
    {
      "sku": "WIDGET-001",
      "inventory_location_id": "se-67890",
      "received_quantity": 40
    }
  ]
}

Status Lifecycle Example

Purchase order with 100 units ordered:

  1. Initial State: Status is open
  2. First Receive (60 units): Status → receiving
  3. Second Receive (40 units): Status → received (order complete)

Purchase order with multiple products:

  1. Product A: Ordered 100, Received 100 ✓
  2. Product B: Ordered 50, Received 30 (partial)
  3. Status: receiving (because Product B is incomplete)
  4. Product B: Additional receive of 20 units
  5. Status: received (all products complete)

Error Handling

Common errors when receiving products:

  • 400 Bad Request: Missing required fields or invalid data format
    • Invalid inventory location
    • Purchase order in invalid state for receiving
  • 404 Not Found: Purchase order or product ID doesn't exist

Validation Rules

  • Cannot receive products from a cancelled purchase order
  • Cannot receive products from a received purchase order (already complete)
  • inventory_location_id must exist and be active
  • At least one of received_quantity or rejected_quantity must be provided and greater than 0
Previous page
Next page