Inbound Deliveries Guide

This guide explains how to create inbound delivery records for inventory restocking and purchase order processing.

Overview

Inbound deliveries represent shipments arriving at the warehouse. They are used to:

Register incoming inventory
Process purchase orders
Update stock levels
Track supplier deliveries

Endpoint

POST /inbound

Full URL: https://api.spreetaileu.com/api/api/v1/inbound

Authentication

Requires Bearer token authentication. See the Authentication Guide for details.

Inbound Delivery Structure

An inbound delivery includes:

PO Information: Primary and optional secondary PO references
Warehouse Routing: Required warehouse name used to resolve Linnworks location ID
Items: Product barcodes and quantities (with optional SKU)
Optional Metadata: Transport ID

Required Fields

Field	Type	Description
`PO_REFERENCE`	string	Unique PO reference (stored as `delivery_number`)
`Warehouse_Name`	string	Warehouse name provided by your Account Manager (for example: `RHEINE01`)
`items`	array	At least one item required (each with `barcode` and `Quantity`)

Optional Fields

Field	Type	Description
`Secondary_PO_Reference`	string	Secondary/external PO reference (stored as `external_delivery_number`)
`transport_id`	string	Optional transport/shipment identifier

Example: Complete Inbound Delivery

{
  "PO_REFERENCE": "DEL-2025-001",
  "Secondary_PO_Reference": "EXT-DEL-001",
  "Warehouse_Name": "RHEINE01",
  "transport_id": "TRANS-001",
  "items": [
    {
      "barcode": "1234567890123",
      "Quantity": 100,
      "SKU": "MAT-001"
    },
    {
      "barcode": "9876543210987",
      "Quantity": 50,
      "SKU": "MAT-002"
    }
  ]
}

Example: Minimal Inbound Delivery

{
  "PO_REFERENCE": "DEL-2025-002",
  "Warehouse_Name": "RHEINE01",
  "items": [
    {
      "barcode": "5555666677778",
      "Quantity": 25
    }
  ]
}

Code Examples

Python

import requests

def create_inbound_delivery(access_token, delivery_data):
    """Create an inbound delivery"""
    url = "https://api.spreetaileu.com/api/api/v1/inbound"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    response = requests.post(url, headers=headers, json=delivery_data)
    response.raise_for_status()
    return response.json()

# Example usage
delivery = {
    "PO_REFERENCE": "DEL-2025-001",
    "Warehouse_Name": "RHEINE01",
    "Secondary_PO_Reference": "EXT-DEL-001",
    "items": [{
        "barcode": "1234567890123",
        "Quantity": 100,
        "SKU": "MAT-001"
    }]
}

result = create_inbound_delivery(access_token, delivery)
print(f"Inbound delivery created: {result}")

JavaScript/Node.js

async function createInboundDelivery(accessToken, deliveryData) {
  const url = 'https://api.spreetaileu.com/api/api/v1/inbound';
  
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(deliveryData)
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Inbound delivery creation failed: ${error.error || response.statusText}`);
  }
  
  return await response.json();
}

// Example usage
const delivery = {
  PO_REFERENCE: `DEL-${Date.now()}`,
  Warehouse_Name: 'RHEINE01',
  Secondary_PO_Reference: 'EXT-DEL-001',
  items: [{
    barcode: '1234567890123',
    Quantity: 100,
    SKU: 'MAT-001'
  }]
};

createInboundDelivery(accessToken, delivery)
  .then(result => console.log('Inbound delivery created:', result))
  .catch(error => console.error('Error:', error));

Response

Success Response (201)

{
  "success": true,
  "message": "Inbound created successfully",
  "data": {
    "delivery_number": "DEL-2025-001",
    "client": "USB",
    "status": "pending",
    "items_count": 2
  }
}

Error Responses

400 Bad Request - Validation error:

{
  "success": false,
  "error": "Missing required field: PO_REFERENCE"
}

401 Unauthorized - Invalid or expired token:

{
  "success": false,
  "error": "Unauthorized"
}

409 Conflict - Duplicate delivery number:

{
  "success": false,
  "error": "Inbound with delivery_number 'DEL-2025-001' already exists"
}

Important Notes

Delivery Number Uniqueness

PO_REFERENCE values must be unique per client
If you submit the same PO_REFERENCE twice, you'll receive a 409 Conflict error
Use a consistent format (for example: DEL-YYYYMMDD-####)

Auto-Managed Fields

received_at is auto-generated by the API at ingest time
status is auto-set to pending
Item itm_number is auto-generated sequentially per line item
Do not send received_at, status, docnum, plant, batch, or itm_number

Warehouse Name

Warehouse_Name is required
The value must match a valid Linnworks warehouse location name (for example RHEINE01)
The API resolves this name to Linnworks pkStockLocationId during PO creation

Each item in the items array must have:

Required: barcode (string) and Quantity (integer, minimum: 1)
Optional: SKU (string)

Inventory Impact

Creating an inbound delivery will increase inventory levels
Items are added to available stock
Updates are reflected in inventory queries

Use Cases

1. Register Purchase Order Receipt

def register_po_receipt(access_token, po_number, items):
    """Register receipt of a purchase order"""
    delivery = {
        "PO_REFERENCE": f"PO-{po_number}",
        "Secondary_PO_Reference": po_number,
        "Warehouse_Name": "RHEINE01",
        "items": items
    }
    return create_inbound_delivery(access_token, delivery)

# Usage
po_items = [
    {
        "barcode": "1234567890123",
        "Quantity": 100,
        "SKU": "MAT-001"
    }
]

result = register_po_receipt(access_token, "PO-12345", po_items)

2. Batch Inbound Processing

def process_multiple_deliveries(access_token, deliveries):
    """Process multiple inbound deliveries"""
    results = []
    for delivery in deliveries:
        try:
            result = create_inbound_delivery(access_token, delivery)
            results.append({"success": True, "data": result})
        except Exception as e:
            results.append({"success": False, "error": str(e)})
    return results

Best Practices

Use Descriptive Delivery Numbers: Include PO numbers or supplier references
Always Provide Warehouse_Name: Use the exact warehouse name supplied by your Account Manager
Include Optional Metadata: Add Secondary_PO_Reference and transport_id when available
Validate Before Sending: Check required fields and item quantities
Track Delivery Status: Use GET /inbound/{deliveryNumber} to check delivery status
Handle Errors Gracefully: Implement retries/error handling for validation or conflict responses

Related Endpoints

GET /inbound/{deliveryNumber} - Retrieve inbound delivery details
GET /inventory - Check updated inventory levels after delivery