Purchase Orders API

Complete reference for Purchase Order endpoints.

See also: Purchase Orders User Guide.

List Purchase Orders

GET /v1/purchase-orders

Query Parameters

Parameter	Type	Description
status	string	Filter by status: draft, pending_approval, approved, rejected, completed, cancelled
vendor_id	integer	Filter by vendor
department_id	integer	Filter by department
created_from	date	Filter by creation date (start)
created_to	date	Filter by creation date (end)
min_amount	number	Filter by minimum total amount
max_amount	number	Filter by maximum total amount

Example Request

curl -X GET "https://api.waqti.sa/v1/purchase-orders?status=approved&per_page=20" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Example Response

{
  "data": [
    {
      "id": 42,
      "po_number": "PO-2025-0042",
      "status": "approved",
      "vendor": {
        "id": 5,
        "name": "ABC Supplies Co."
      },
      "department": {
        "id": 2,
        "name": "Operations"
      },
      "currency": "SAR",
      "subtotal": 45000.00,
      "vat_amount": 6750.00,
      "total_amount": 51750.00,
      "created_at": "2025-01-15T10:30:00Z",
      "approved_at": "2025-01-15T14:22:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 20,
    "total": 42
  }
}

Create Purchase Order

POST /v1/purchase-orders

Request Body

{
  "vendor_id": 5,
  "department_id": 2,
  "project_id": 1,
  "currency": "SAR",
  "notes": "Quarterly office supplies",
  "delivery_address": "Riyadh, Main Office",
  "expected_delivery_date": "2025-02-01",
  "items": [
    {
      "description": "Printer Paper A4",
      "quantity": 100,
      "unit": "ream",
      "unit_price": 25.00,
      "vat_rate": 15
    },
    {
      "description": "Ink Cartridges",
      "quantity": 20,
      "unit": "piece",
      "unit_price": 150.00,
      "vat_rate": 15
    }
  ],
  "attachments": [
    {
      "name": "Quote.pdf",
      "url": "https://..."
    }
  ]
}

Response

{
  "data": {
    "id": 43,
    "po_number": "PO-2025-0043",
    "status": "draft",
    "vendor_id": 5,
    "department_id": 2,
    "subtotal": 5500.00,
    "vat_amount": 825.00,
    "total_amount": 6325.00,
    "items": [...],
    "created_at": "2025-01-15T16:00:00Z"
  }
}

Get Purchase Order

GET /v1/purchase-orders/{id}

Response

{
  "data": {
    "id": 42,
    "po_number": "PO-2025-0042",
    "status": "approved",
    "vendor": {
      "id": 5,
      "name": "ABC Supplies Co.",
      "email": "sales@abcsupplies.com"
    },
    "department": {
      "id": 2,
      "name": "Operations",
      "code": "OPS"
    },
    "project": {
      "id": 1,
      "name": "Q1 Procurement",
      "code": "PRJ-2025-Q1"
    },
    "created_by": {
      "id": 10,
      "name": "Mohammed Ali"
    },
    "currency": "SAR",
    "subtotal": 45000.00,
    "vat_amount": 6750.00,
    "total_amount": 51750.00,
    "notes": "Quarterly office supplies",
    "delivery_address": "Riyadh, Main Office",
    "expected_delivery_date": "2025-02-01",
    "items": [
      {
        "id": 101,
        "line_number": 1,
        "description": "Printer Paper A4",
        "quantity": 100,
        "unit": "ream",
        "unit_price": 25.00,
        "vat_rate": 15,
        "vat_amount": 375.00,
        "total": 2875.00
      }
    ],
    "approvals": [
      {
        "step": 1,
        "approver": "Ahmed Khalid",
        "status": "approved",
        "approved_at": "2025-01-15T14:22:00Z",
        "comments": "Approved"
      }
    ],
    "attachments": [
      {
        "id": 1,
        "name": "Quote.pdf",
        "size": 245000,
        "url": "https://..."
      }
    ],
    "audit_trail": [
      {
        "action": "created",
        "user": "Mohammed Ali",
        "timestamp": "2025-01-15T10:30:00Z"
      },
      {
        "action": "submitted",
        "user": "Mohammed Ali",
        "timestamp": "2025-01-15T10:35:00Z"
      },
      {
        "action": "approved",
        "user": "Ahmed Khalid",
        "timestamp": "2025-01-15T14:22:00Z"
      }
    ],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T14:22:00Z"
  }
}

Update Purchase Order

PUT /v1/purchase-orders/{id}

WARNING

Only draft POs can be updated. Submitted or approved POs require amendments.

Request Body

{
  "notes": "Updated notes",
  "expected_delivery_date": "2025-02-15",
  "items": [
    {
      "id": 101,
      "quantity": 150
    },
    {
      "description": "New Item",
      "quantity": 10,
      "unit_price": 100.00
    }
  ]
}

Delete Purchase Order

DELETE /v1/purchase-orders/{id}

WARNING

Only draft POs can be deleted. Other statuses should be cancelled instead.

Submit for Approval

POST /v1/purchase-orders/{id}/submit

Submits the PO for approval. The PO will be routed according to the configured approval workflow.

Response

{
  "data": {
    "id": 43,
    "status": "pending_approval",
    "current_approval_step": 1,
    "pending_approvers": [
      {
        "id": 15,
        "name": "Ahmed Khalid",
        "role": "Department Head"
      }
    ]
  }
}

Approve Purchase Order

POST /v1/purchase-orders/{id}/approve

Request Body

{
  "comments": "Approved as requested"
}

Reject Purchase Order

POST /v1/purchase-orders/{id}/reject

Request Body

{
  "reason": "Budget exceeded for this quarter"
}

Cancel Purchase Order

POST /v1/purchase-orders/{id}/cancel

Request Body

{
  "reason": "Vendor no longer available"
}

Download PDF

GET /v1/purchase-orders/{id}/pdf

Returns the PO as a PDF document.

Response

Binary PDF file with headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename="PO-2025-0042.pdf"

PO Line Items

Add Line Item

POST /v1/purchase-orders/{id}/items

Update Line Item

PUT /v1/purchase-orders/{id}/items/{item_id}

Delete Line Item

DELETE /v1/purchase-orders/{id}/items/{item_id}