Purchasing API

The Purchasing API is read-only. Use it to list purchase orders (POs) and read one with its line items, for example to mirror order status into another system. Purchase orders are created, edited and received in the OpenBoxes web application; we document no REST endpoint for any of that, on any plan.

List Purchase Orders#

Retrieve purchase orders for your current location:

curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/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 None Filter by status (e.g., PENDING, PLACED, RECEIVED)
supplier string None 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 -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/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
      }
    ]
  }
}

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

Creating, editing and receiving purchase orders#

There is no supported REST endpoint for any of these, and nothing on this page or in the portal's API console will give you one. Purchase orders are created, edited, placed and received in the OpenBoxes web application: Purchasing ▸ Create Purchase Order for a new order, the order's own screen to add lines and place it, and Purchasing ▸ Ship from Purchase Order followed by the Inbound receiving screens to record what arrives. Those screens are ordinary web forms, not JSON endpoints.

The API is read-only for purchasing: list orders and read one, as shown above. If your integration needs to act on an order, the usual shape is to poll or subscribe to order.* webhook events and do the write in a downstream system (see Webhooks). The order.* events are delivered on every plan (Shared, Dedicated and Enterprise).

Known Limitations#

  • Read-only: we document no create, update, receive or cancel endpoint for purchase orders. Those actions happen in the OpenBoxes web application.
  • /api/v1/orders returns 404: the dedicated orders list endpoint is not exposed.
  • Partial receipts: quantityReceived on a line item accumulates across every receipt recorded against it in the application, so a partially received order shows a value between zero and quantity.
  • Supplier as location: in OpenBoxes, suppliers are modeled as locations with a Supplier location type. A PO's origin is the supplier's location.

Guides

From the blog