Orders API

Purchase orders and sales orders management endpoints.

Orders API

The Orders API handles both purchase orders (PO) and sales orders (SO), providing endpoints for order creation, management, and fulfillment.

Purchase Orders

GET /api/purchase-orders

Retrieve purchase orders.

Query Parameters:

status (string): Filter by status
supplier_id (string): Filter by supplier
date_from (string): Start date
date_to (string): End date
page (number): Page number
limit (number): Items per page

Response:

{
  "data": [
    {
      "id": "po_456",
      "po_number": "PO-2024-001",
      "supplier": {
        "id": "sup_789",
        "name": "Supplier ABC"
      },
      "status": "confirmed",
      "order_date": "2024-01-15T00:00:00Z",
      "expected_date": "2024-01-25T00:00:00Z",
      "total_amount": 1250.00,
      "items_count": 5,
      "created_at": "2024-01-15T09:00:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

POST /api/purchase-orders

Create a new purchase order.

Request Body:

{
  "supplier_id": "sup_789",
  "warehouse_id": "wh_789",
  "expected_date": "2024-01-25T00:00:00Z",
  "notes": "Urgent order for Q1 stock",
  "items": [
    {
      "product_id": "prod_123",
      "quantity": 100,
      "unit_cost": 25.00
    },
    {
      "product_id": "prod_124",
      "quantity": 50,
      "unit_cost": 15.00
    }
  ]
}

Response:

{
  "data": {
    "id": "po_457",
    "po_number": "PO-2024-002",
    "supplier": {
      "id": "sup_789",
      "name": "Supplier ABC"
    },
    "warehouse": {
      "id": "wh_789",
      "name": "Main Warehouse"
    },
    "status": "draft",
    "order_date": "2024-01-15T00:00:00Z",
    "expected_date": "2024-01-25T00:00:00Z",
    "total_amount": 3250.00,
    "items": [
      {
        "id": "poi_001",
        "product": {
          "id": "prod_123",
          "name": "Smart Widget",
          "sku": "SW-001"
        },
        "quantity": 100,
        "unit_cost": 25.00,
        "total_cost": 2500.00
      }
    ],
    "created_at": "2024-01-15T16:45:00Z"
  }
}

PUT /api/purchase-orders/:id/status

Update purchase order status.

Request Body:

{
  "status": "confirmed",
  "notes": "Confirmed with supplier"
}

Status Values:

draft: Being created
sent: Sent to supplier
confirmed: Confirmed by supplier
partial: Partially received
received: Fully received
cancelled: Cancelled

Response:

{
  "data": {
    "id": "po_456",
    "status": "confirmed",
    "updated_at": "2024-01-15T17:00:00Z"
  }
}

POST /api/purchase-orders/:id/receive

Record receipt of purchase order items.

Request Body:

{
  "received_items": [
    {
      "product_id": "prod_123",
      "quantity_received": 100,
      "unit_cost": 25.00,
      "quality_check": "passed"
    },
    {
      "product_id": "prod_124",
      "quantity_received": 45,
      "unit_cost": 15.00,
      "quality_check": "passed",
      "notes": "5 units damaged during shipping"
    }
  ],
  "received_date": "2024-01-20T14:30:00Z",
  "notes": "Most items received in good condition"
}

Response:

{
  "data": {
    "id": "po_456",
    "status": "partial",
    "received_items": 2,
    "total_items": 2,
    "received_date": "2024-01-20T14:30:00Z",
    "inventory_movements": [
      {
        "id": "mov_123",
        "product_id": "prod_123",
        "quantity": 100,
        "movement_type": "in"
      }
    ]
  }
}

Sales Orders

GET /api/sales-orders

Retrieve sales orders.

Query Parameters:

status (string): Filter by status
customer_id (string): Filter by customer
date_from (string): Start date
date_to (string): End date
page (number): Page number
limit (number): Items per page

Response:

{
  "data": [
    {
      "id": "so_123",
      "order_number": "SO-2024-001",
      "customer": {
        "id": "cust_456",
        "name": "Customer XYZ"
      },
      "status": "shipped",
      "order_date": "2024-01-15T00:00:00Z",
      "ship_date": "2024-01-16T00:00:00Z",
      "total_amount": 299.95,
      "items_count": 3,
      "shipping_address": {
        "name": "John Doe",
        "line1": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "postal_code": "90210"
      }
    }
  ],
  "meta": {
    "total": 250,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

POST /api/sales-orders

Create a new sales order.

Request Body:

{
  "customer_id": "cust_456",
  "warehouse_id": "wh_789",
  "ship_date": "2024-01-20T00:00:00Z",
  "shipping_address": {
    "name": "John Doe",
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "90210",
    "country": "US"
  },
  "items": [
    {
      "product_id": "prod_123",
      "quantity": 2,
      "unit_price": 49.99
    },
    {
      "product_id": "prod_124",
      "quantity": 1,
      "unit_price": 29.99
    }
  ]
}

Response:

{
  "data": {
    "id": "so_124",
    "order_number": "SO-2024-002",
    "customer": {
      "id": "cust_456",
      "name": "Customer XYZ"
    },
    "warehouse": {
      "id": "wh_789",
      "name": "Main Warehouse"
    },
    "status": "pending",
    "order_date": "2024-01-15T00:00:00Z",
    "ship_date": "2024-01-20T00:00:00Z",
    "total_amount": 129.97,
    "items": [
      {
        "id": "soi_001",
        "product": {
          "id": "prod_123",
          "name": "Smart Widget",
          "sku": "SW-001"
        },
        "quantity": 2,
        "unit_price": 49.99,
        "total_price": 99.98
      }
    ],
    "shipping_address": {
      "name": "John Doe",
      "line1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "90210"
    },
    "created_at": "2024-01-15T17:15:00Z"
  }
}

PUT /api/sales-orders/:id/status

Update sales order status.

Request Body:

{
  "status": "shipped",
  "tracking_number": "1Z999AA1234567890",
  "carrier": "UPS",
  "notes": "Shipped via UPS Ground"
}

Status Values:

pending: Order received, awaiting processing
processing: Order being prepared
shipped: Order shipped to customer
delivered: Order delivered
cancelled: Order cancelled

Response:

{
  "data": {
    "id": "so_123",
    "status": "shipped",
    "tracking_number": "1Z999AA1234567890",
    "carrier": "UPS",
    "ship_date": "2024-01-16T14:30:00Z",
    "updated_at": "2024-01-16T14:30:00Z"
  }
}

Inventory

Warehouses