Purchasing API

The Purchasing API supports creating and managing purchase orders (POs) for procuring goods from suppliers. Use it to automate procurement workflows, track order status, and record receipts against orders.

List Purchase Orders

Retrieve purchase orders for your current location:

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/purchaseOrders?max=25&offset=0"

Query Parameters

Parameter	Type	Default	Description
max	integer	all	Maximum records to return
offset	integer	0	Number of records to skip
status	string	--	Filter by status (e.g., PENDING, PLACED, RECEIVED)
supplier	string	--	Filter by supplier ID

Response

{
  "data": [
    {
      "id": "po-001",
      "orderNumber": "PO-2025-0042",
      "name": "Q2 Pharmaceutical Resupply",
      "status": "PLACED",
      "origin": {
        "id": "sup-001",
        "name": "PharmaCorp International"
      },
      "destination": {
        "id": "loc-001",
        "name": "Central Warehouse"
      },
      "orderedBy": {
        "id": "user-001",
        "name": "Jane Smith"
      },
      "dateOrdered": "2025-03-15T00:00:00Z",
      "orderItems": []
    }
  ]
}

Get Purchase Order Details

Retrieve a single purchase order with its line items:

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/purchaseOrders/po-001"

Response

{
  "data": {
    "id": "po-001",
    "orderNumber": "PO-2025-0042",
    "name": "Q2 Pharmaceutical Resupply",
    "status": "PLACED",
    "origin": { "id": "sup-001", "name": "PharmaCorp International" },
    "destination": { "id": "loc-001", "name": "Central Warehouse" },
    "dateOrdered": "2025-03-15T00:00:00Z",
    "orderItems": [
      {
        "id": "oi-001",
        "product": { "id": "prod-001", "name": "Ibuprofen 200mg" },
        "quantity": 10000,
        "unitPrice": 0.12,
        "totalPrice": 1200.00,
        "quantityReceived": 0
      },
      {
        "id": "oi-002",
        "product": { "id": "prod-002", "name": "Amoxicillin 250mg" },
        "quantity": 5000,
        "unitPrice": 0.25,
        "totalPrice": 1250.00,
        "quantityReceived": 0
      }
    ]
  }
}

Create Purchase Order

Create a new purchase order:

curl -X POST \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/purchaseOrders" \
  -d '{
    "name": "Emergency Medical Supply Order",
    "origin": { "id": "sup-001" },
    "destination": { "id": "loc-001" },
    "orderedBy": { "id": "user-001" },
    "dateOrdered": "2025-04-01T00:00:00Z",
    "orderItems": [
      {
        "product": { "id": "prod-001" },
        "quantity": 10000,
        "unitPrice": 0.12
      }
    ]
  }'

Required Fields

Field	Type	Description
name	string	Descriptive name for the order
origin	object	Supplier location with id
destination	object	Receiving location with id
orderedBy	object	Ordering user with id
dateOrdered	string	Order date in ISO 8601 format

Order Item Fields

Field	Type	Required	Description
product	object	Yes	Product reference with id
quantity	integer	Yes	Quantity to order
unitPrice	number	No	Price per unit

Update Purchase Order

Modify an existing purchase order (only in PENDING status):

curl -X PUT \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/purchaseOrders/po-001" \
  -d '{
    "name": "Q2 Pharmaceutical Resupply (Updated)",
    "orderItems": [
      {
        "id": "oi-001",
        "quantity": 15000,
        "unitPrice": 0.11
      }
    ]
  }'

Purchase Order Statuses

Status	Description
PENDING	Draft, can still be edited
PLACED	Submitted to supplier
PARTIALLY_RECEIVED	Some items received
RECEIVED	All items received
CANCELED	Order canceled

Receiving Against a Purchase Order

Record receipt of goods against a purchase order. This creates inventory transactions and updates stock levels:

curl -X POST \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/purchaseOrders/po-001/receive" \
  -d '{
    "items": [
      {
        "orderItemId": "oi-001",
        "quantityReceived": 10000,
        "lotNumber": "LOT-2025-PH-042",
        "expirationDate": "2027-06-30T00:00:00Z"
      }
    ]
  }'

Receipt Fields

Field	Type	Required	Description
orderItemId	string	Yes	ID of the order item being received
quantityReceived	integer	Yes	Quantity received in this shipment
lotNumber	string	No	Lot/batch number for the received goods
expirationDate	string	No	Expiry date for the received lot
binLocation	object	No	Destination bin location with id

Alternative: Generic API

Purchase orders can also be accessed through the generic CRUD endpoint:

# List via generic API
curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/generic/requisition?max=25"

Known Limitations

• /api/orders returns 404: The dedicated orders list endpoint is not exposed. Use /api/purchaseOrders or the generic API instead.
• Status restrictions: Orders in PLACED or RECEIVED status cannot be edited. Modify only PENDING orders.
• Partial receipts: Multiple receipts can be recorded against a single order item. The quantityReceived field accumulates across all receipts.
• Supplier as location: In OpenBoxes, suppliers are modeled as locations with a Supplier location type. Create the supplier as a location before referencing it in purchase orders.