---
search:
  tags:
    - PurchaseOrders
    - POST
seo:
  description: >-
    Admin and branch manager. Raises a purchase order with its line items in
    one… Reference for the POST /api/v1/purchase-orders endpoint in the
    PharmaFlow API.
sidebar:
  label: Create a purchase order
  badge: POST
title: Create a purchase order
type: openapi-operation
---
Admin and branch manager. Raises a purchase order with its line items in one transaction. The supplier and branch must exist and be active, and the order opens as DRAFT and is audited.

`POST /api/v1/purchase-orders`

**Request body** (`application/json`, required)

- `supplier_id` (string, required)
- `branch_id` (string, required)
- `expected_date` (string | null)
- `notes` (string)
- `items` (object[], required)

Request body example:

```json
{
  "supplier_id": "string",
  "branch_id": "string",
  "expected_date": "string",
  "notes": "",
  "items": [
    {
      "medicine_id": "string",
      "ordered_qty": -9007199254740991,
      "agreed_unit_cost": 0
    }
  ]
}
```

**Responses**

- `201` — Purchase order drafted
- `400` — The request body fails validation
- `401` — Not authenticated
- `403` — Access forbidden for this role
- `404` — Supplier not found, or branch not found

Response example, 201:

```json
{
  "id": "string",
  "status": "string",
  "created_at": "string"
}
```