Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v1/purchases | List purchases (filter by status / supplierId) |
GET | /api/v1/purchases/{id} | Get a single purchase |
POST | /api/v1/purchases | Create a new purchase order |
PATCH | /api/v1/purchases/{id} | Partially update fields (not status — see transition) |
DELETE | /api/v1/purchases/{id} | Delete a purchase order (only allowed for deletable states) |
POST | /api/v1/purchases/{id}/transition | Transition status with audit log entry |
GET | /api/v1/purchases/{id}/logs | Retrieve the full status change audit log |
See Purchase orders concept for the lifecycle diagram. Use Purchase Documents for files attached to purchase orders.
GET /api/v1/purchases
| Query parameter | Type | Required | Allowed values |
|---|---|---|---|
status | enum | — | DRAFT, CONFIRMED, IN_TRANSIT, DELIVERED, CANCELLED |
supplierId | uuid | — | Filter by supplier |
Combine filters freely. Both parameters can be used together.
curl "{{BASE_URL}}/api/v1/purchases?status=IN_TRANSIT"curl "{{BASE_URL}}/api/v1/purchases?supplierId=3f2b9a1c-…"curl "{{BASE_URL}}/api/v1/purchases?status=DRAFT&supplierId=3f2b9a1c-…"
Response 200 OK — JSON array of SupplierPurchaseRecordDto.
POST /api/v1/purchases
Request body (CreateSupplierPurchaseRecordDto)
| Field | Type | Required | Description |
|---|---|---|---|
supplierId | uuid | ✅ | Supplier the order is placed with |
orderNumber | string | ✅ | Your internal order reference |
orderDate | date-time | ✅ | When the order was placed |
status | enum | — | Initial status (default DRAFT) |
expectedDelivery | date-time | — | Expected delivery date |
totalAmount | string (decimal) | — | Total amount (preserve precision as string) |
currency | string | — | ISO 4217 currency code |
notes | string | — | Free-form notes |
curl -X POST {{BASE_URL}}/api/v1/purchases \-H "Content-Type: application/json" \-d '{"supplierId": "3f2b9a1c-…","orderNumber": "PO-2026-0001","orderDate": "2026-04-21T09:00:00.000Z","expectedDelivery": "2026-05-10T00:00:00.000Z","totalAmount": "1249.50","currency": "EUR","notes": "Seasonal restock"}'
Response 201 Created — SupplierPurchaseRecordDto.
GET /api/v1/purchases/{id}
200 OK—SupplierPurchaseRecordDto.404 Not Found— purchase does not exist in your tenant.
PATCH /api/v1/purchases/{id}
Partially updates fields of a purchase. status transitions must go through the transition endpoint instead.
Allowed fields: orderNumber, orderDate, expectedDelivery, totalAmount, currency, notes.
curl -X PATCH {{BASE_URL}}/api/v1/purchases/… \-H "Content-Type: application/json" \-d '{ "expectedDelivery": "2026-05-15T00:00:00.000Z" }'
200 OK— updatedSupplierPurchaseRecordDto.404 Not Found— purchase does not exist in your tenant.
DELETE /api/v1/purchases/{id}
Deletes a purchase order. Only deletable from certain states (e.g. DRAFT or CANCELLED); attempting to delete an order in another state returns an error.
204 No Content— deleted.404 Not Found— purchase does not exist in your tenant.
POST /api/v1/purchases/{id}/transition
Transitions the purchase to a new status and records the change in the audit log.
Request body (TransitionPurchaseStatusDto)
| Field | Type | Required | Description |
|---|---|---|---|
toStatus | enum | ✅ | Target status — must be a valid successor of the current status |
reason | string | — | Reason for the transition (highly recommended) |
actualDelivery | date-time | — | Set when transitioning to DELIVERED |
curl -X POST {{BASE_URL}}/api/v1/purchases/…/transition \-H "Content-Type: application/json" \-d '{"toStatus": "DELIVERED","reason": "Received at warehouse","actualDelivery": "2026-04-20T14:30:00.000Z"}'
200 OK— updatedSupplierPurchaseRecordDto.404 Not Found— purchase does not exist.
Valid transitions follow the lifecycle diagram.
GET /api/v1/purchases/{id}/logs
Retrieves the ordered list of status changes for a purchase.
curl {{BASE_URL}}/api/v1/purchases/…/logs
Response 200 OK — JSON array of PurchaseStatusChangeLogDto:
[{"id": "l0g_01…","purchaseRecordId": "…","fromStatus": "CONFIRMED","toStatus": "IN_TRANSIT","reason": "Courier picked up at supplier","changedByUserId": "user_…","changedAt": "2026-04-22T08:00:00.000Z"}]
Purchase schema
SupplierPurchaseRecordDto:
{"id": "po-uuid…","supplierId": "3f2b9a1c-…","orderNumber": "PO-2026-0001","status": "IN_TRANSIT","orderDate": "2026-04-21T09:00:00.000Z","expectedDelivery": "2026-05-10T00:00:00.000Z","actualDelivery": null,"totalAmount": "1249.50","currency": "EUR","notes": "Seasonal restock","createdAt": "2026-04-21T09:00:00.000Z","updatedAt": "2026-04-22T08:00:00.000Z"}